Error Codes
Errors from the /v1 API return JSON with error, code, fix, docs, and selfHeal fields, plus an X-Request-Id response header.
{
"error": "Human-readable error message",
"code": "error_code",
"fix": "Suggested action to resolve the error",
"docs": "https://docs.vonpay.com/reference/error-codes#error_code",
"selfHeal": {
"retryable": false,
"nextAction": "no_action",
"llmHint": "Machine-readable guidance for SDKs and agents."
}
}
The selfHeal object is always present in the standard envelope and gives SDKs and agents a machine-readable hint about whether the request is retriable and what to do next. A small number of responses fall outside this envelope: the switched-off payment status stream and its token renewal answer a bare 503 with no JSON body. They still carry the X-Request-Id header.
Some codes add fields to the envelope. The most common is reason, a short fixed value that says which case of the code you got. Each code's entry on this page says when reason is present and which values it takes. Treat a value you do not recognise as open text, because new values can be added.
HTTP Status Codes
| Code | Meaning | Common Causes |
|---|---|---|
| 400 | Bad Request | Invalid request body, missing required fields, validation failure |
| 401 | Unauthorized | Missing or invalid Authorization: Bearer token |
| 404 | Not Found | Session ID doesn't exist |
| 408 | Request Timeout | The request body did not finish arriving in time |
| 409 | Conflict | Session is in the wrong state (e.g., already completed) |
| 410 | Gone | Session has expired (configurable TTL — 30-minute default) |
| 413 | Content Too Large | The request body is over the endpoint's size limit |
| 429 | Too Many Requests | Rate limit exceeded |
| 500 | Internal Server Error | Unexpected server error |
Error Codes Reference
| Code | HTTP | Description |
|---|---|---|
auth_missing_bearer | 401 | No Authorization: Bearer header provided |
auth_invalid_key | 401 | API key is malformed or does not exist |
auth_key_expired | 401 | Key has rotated past its grace window |
client_secret_invalid | 401 | A browser call sent an X-Vonpay-Client-Secret header that is not this checkout session's client secret. Nothing was done |
client_secret_required | 401 | This checkout session requires its client secret and the browser call did not send it. Nothing was done |
client_secret_in_path | 400 | A client secret was put in the URL path where the checkout session id belongs. Nothing was done |
auth_missing_bearer_publishable | 401 | No Authorization: Bearer header on a browser-callable /v1/public/* route |
auth_invalid_key_publishable | 401 | Publishable key not recognized on this host — most often an environment mismatch, not a bad key. See below before rotating anything |
auth_key_expired_publishable | 401 | Publishable key is past its rotation grace window. Publishable keys reach the browser by redeploy, not by swapping an environment variable |
auth_key_type_forbidden | 403 | Publishable key used on a secret-only endpoint, or sandbox/live mode mismatch |
api_key_permission_denied | 403 | A restricted key does not hold the permission this request needs |
api_key_limit_exceeded | 422 | The charge, refund or checkout session total does not fit a restricted key's money limits. Nothing was charged, refunded or created |
platform_fee_exceeds_amount | 422 | The platform fee on your account is at least this payment's amount. Nothing was charged |
auth_merchant_inactive | 401 | Merchant account is disabled or suspended |
merchant_not_onboarded | 403 | Live-key creation is blocked until merchant-onboarding review completes |
live_keys_need_processor | 403 | The account is approved, but no payment processor is connected to it yet |
test_keys_are_sandbox_only | 403 | Test keys were requested on a live business; they come from its sandbox |
live_keys_not_on_sandbox | 403 | A live key was requested on a sandbox |
processor_check_unavailable | 503 | We could not confirm the account's payment setup. Temporary, and not a problem with your request; retry shortly |
auth_service_unavailable | 503 | Authentication service is temporarily unavailable |
session_not_found | 404 | Session ID does not exist |
payment_intent_not_found | 404 | No payment intent with that id for this API key |
transaction_not_found | 404 | No transaction with that id for this API key |
checkout_address_not_found | 404 | The request reached a {name}.vonpay.com address that is not serving checkout. Use the checkoutUrl from POST /v1/sessions exactly as returned, and send API calls to its host |
session_expired | 410 | The session ended: its time limit passed, or it ended with no successful charge. Create a new one, unless the body carries expiredFrom: "processing": then a charge may have been taken, so do not charge again |
session_attempt_limit_reached | 422 | The checkout session has used all its payment attempts. Nothing was sent or charged: create a new session |
client_read_secret_limit_reached | 409 | No new in-page read secret was minted: 3 of the payment's secrets still work, or 10 have been minted. Reuse one you hold |
card_brand_not_accepted | 422 | The store does not accept this card's brand. Nothing was saved or charged: ask for a card of another brand on the same session |
shopper_attempt_limit_reached | 422 | The store cannot accept a card from this shopper right now. Nothing was sent or charged, and a new session will not help: ask the shopper to contact the store |
bot_check_required | 403 | Browser verification is switched on for the account and the request carried no verification pass. Nothing was charged or saved |
bot_check_expired | 403 | The verification pass was already used or expired. Nothing was charged or saved: resend once with a fresh pass |
bot_check_failed | 403 | The verification pass was not valid. Nothing was charged or saved: do not resend |
bot_check_unavailable | 503 | The payment could not be verified right now. Nothing was charged: wait about a minute and retry |
session_already_completed | 409 | The session's payment already finished: the buyer was charged once (or, on a captureMethod: "manual" session, authorized once). On POST /v1/payment_intents it also covers a linked session that expired, or had a payment-provider transaction recorded without succeeding (charged: false, outcome may not be final). Do not retry or create a new session (would double-charge). Read the outcome via webhook or the session read |
session_wrong_state | 409 | Session is in the wrong state for this operation |
session_not_expirable | 409 | The session could not be expired and nothing changed. A payment may exist on it that has not been reported, so do not take payment another way; read the session in the response. See below |
session_not_modifiable | 409 | PATCH /v1/sessions/{id} could not change the total, the metadata or the guest's details and nothing changed. reason says why. See below |
session_update_conflict | 409 | PATCH /v1/sessions/{id}: other changes to the same session kept landing while this one was applied. Nothing changed and the session is still open; retry the same request after a moment. A card or wallet payment can also get it: nothing was charged, and the buyer pays again |
card_form_adopt_refused | 409 | The card form of the old checkout session could not move to the new one, and nothing changed. vora.js answers not_switched with the reason. See below |
charge_in_progress | 409 | A charge is already in flight — for this session on the hosted surface, or for this Idempotency-Key on POST /v1/payment_intents. Do not retry, do not create a new session, and do not reissue with a fresh Idempotency-Key — on some provider configurations a second attempt is a second charge that cannot be merged afterwards. Read the original's status instead. See below |
session_payment_in_progress | 409 | Another payment on this session is still running, and this request charged nothing. Its outcome is not known yet: do not show success or a decline, do not retry, and do not create a new session. Read the session until it settles. After a processing error it is a short wait instead: try again in a few minutes. See below |
payment_under_review | 409 | The session's previous payment ended with a processing error, and it may have taken money. This request charged nothing. Do not let the buyer pay again; tell them the payment is being reviewed and to contact you. See below |
payment_form_expired | 409 | The buyer's card went into a card form an earlier, declined attempt on this session had already used. Nothing was charged and the session is still open: load the fresh card form and submit again. nextAction: "reload_payment_form" |
payment_form_busy | 409 | A payment on this session is running right now, so its payment form is not handed out again. Nothing was charged by this request: read the session again after about a second. nextAction: "wait_and_retry" |
payment_form_used | 409 | A card save resent into a card form that an earlier submit on the session already used. Nothing new was saved and nothing was charged. Not retryable: if the earlier save succeeded, use that card; otherwise start a new session. See below |
charge_already_in_flight | 409 | Another request with this Idempotency-Key is still running. Retry with the same key after retryAfterSeconds — never with a fresh one. Nothing was charged by this request |
charge_reservation_unavailable | 503 | The pre-charge record for your Idempotency-Key could not be written; nothing reached the processor. Retry the same request with the same key |
expected_amount_mismatch | 409 | The payment was for a total the session no longer holds. The buyer was not charged. Show the current total and have the buyer approve it again. See below |
session_integrity_error | 500 | Internal session state mismatch — contact support |
validation_error | 400 | Request body failed schema validation |
currency_not_supported | 422 | New payments refuse this currency. Nothing was charged, saved or created. Use a different currency |
validation_missing_field | 400 | A required field is missing from the request body |
validation_invalid_amount | 400 | Amount is not a positive integer or exceeds maximum |
validation_unknown_field | 400 | The body carried a field this endpoint does not accept. Refused, never ignored. Two causes: wrong casing, or a real field that belongs on a different call |
merchant_not_configured | 422 | Merchant is missing required configuration (e.g., payment provider credentials); on a refund, capture or void, no payment account the payment can safely be sent to, and nothing moved |
binder_unavailable | 409 | Merchant has no payment provider configured for this operation — complete onboarding. A test key does not avoid it |
sandbox_account_required | 422 | A test key was used where there is no test environment: on a live account, or on a sandbox with no payment provider. Test payments run only on a sandbox account |
capability_not_supported | 422 | The merchant's payment provider does not support the requested operation — check GET /v1/capabilities |
rate_limit_exceeded | 429 | A rate limit was reached: per secret key on the server API, per IP for publishable-key, unauthenticated and browser calls. Wait Retry-After (1 to 60 seconds), then retry with backoff |
rate_limit_exceeded_per_key | 429 | Per-API-key rate limit (30 session-creates/min). Wait Retry-After, or contact support if you need a higher ceiling |
provider_unavailable | 502 | Upstream payment provider is not responding |
payment_outcome_unknown | 502 | A capture or void reached the payment provider, but its result could not be recorded. Do not retry: a retried capture can capture twice. Read the payment intent back. See below |
provider_operation_refused | 422 | The payment provider refused a capture or void as invalid, and the authorization still stands. Nothing moved. Not retryable unchanged. See below |
provider_attestation_failed | 403 | Payment provider rejected the session-bound attestation |
provider_charge_failed | 402 | Card declined or charge rejected by the upstream provider |
payment_method_not_stored | 422 | The processor never kept this saved card on file, so it refused the charge. Nothing was charged. The customer must re-enter the card |
recurring_mandate_required | 422 | An automatic charge on a card issued in India that has no recurring-payment mandate. Nothing was charged. Charge it with the customer present, or use another card |
provider_request_rejected | 422 | Payment provider rejected the request as invalid before any money moved (not a decline, not an outage) — fix the offending field and retry |
internal_error | 500 | Unexpected server error |
webhook_missing_signature | 401 | Inbound provider webhook is missing its signature header |
webhook_invalid_signature | 401 | Webhook signature does not match the expected value |
webhook_not_configured | 503 | Webhook verification secret is not configured on the server |
webhook_test_delivery_failed | 422 | A synchronous webhook test-send probe could not reach your endpoint. Not retryable: check the subscription URL, then send the test again |
origin_forbidden | 403 | Internal endpoint called from outside the checkout page |
transaction_verification_failed | 403 | Transaction could not be verified with the payment provider |
unsupported_media_type | 415 | Content-Type header is missing or not application/json |
request_body_too_large | 413 | The request body is over this endpoint's size limit. Nothing was processed |
request_body_timeout | 408 | The request body did not finish arriving in time. Nothing was processed. Retryable |
endpoint_not_implemented | 501 | A payment-intent operation is not yet implemented for this merchant's provider (capability gate) |
endpoint_retired | 410 | A permanently retired endpoint. No public API call returns it today |
idempotency_replay_incompatible | 422 | Idempotency key was reused with a different request body |
unexpected_redirect | n/a | Raised by the server SDKs, never sent by the API: the SDK got an HTTP redirect and refused to follow it. Do not retry; check the base URL, proxy and network |
idempotency_key_required | 400 | An Idempotency-Key header is required and none was sent. Today it applies on refunds whose payment was taken on a connection keeping no queryable record of a reversal, and on payment routes that keep no record of their own. From the 28 October 2026 cut-off it can apply to any charge on POST /v1/payment_intents. Not retryable as sent. See below |
invalid_transition | 409 | Payment intent is in a state that forbids the requested operation (e.g. capture on succeeded) |
operation_in_flight | 409 | An earlier capture or void with this Idempotency-Key is still being processed. Retry the same request with the same key in a few seconds |
capture_amount_exceeds_authorized | 422 | amount_to_capture is larger than the amount authorized on the intent. The response carries authorized_amount |
refund_intent_not_refundable | 422 | The parent payment intent is not in a refundable state (refunds require status: "succeeded") |
refund_amount_exceeds_remaining | 422 | Requested refund amount is greater than the remaining refundable balance |
refund_before_settlement | 422 | The payment has not settled yet, so it cannot be refunded. Nothing moved. Wait for settlement, then send the refund again with a new Idempotency-Key |
refund_currency_mismatch | 422 | Refund currency does not match the parent intent's currency |
refund_target_is_duplicate | 422 | The transaction names a duplicate record of a payment recorded under another transaction. The response names the one to use in refund_instead |
refund_target_not_refundable | 422 | The transaction cannot be refunded through the API. Contact support with its id |
payment_method_required | 422 | This merchant's payment provider requires a vaulted payment method on the request |
payment_method_not_found | 404 | The payment_method.id does not exist or does not belong to this merchant, or it is a single-use card with no buyer saved more than 24 hours ago |
saved_card_buyer_required | 422 | A card was to be saved for later use with no buyer identified. Nothing was charged or saved |
required_fields_missing | 422 | A card payment lacked buyer details your account requires. The buyer was not charged |
payment_method_consent_missing | 422 | The token was vaulted without off-session consent. Consent is write-once — collect the card again rather than trying to update the token |
security_code_session_not_found | 404 | The security_code_session is unknown, another account's or mode's, or was opened for a different payment_method. Nothing was charged |
security_code_session_expired | 410 | The security code session was already used or is older than 15 minutes. Nothing was charged. Open a new one and ask the buyer again |
security_code_not_collected | 422 | The browser SDK has not confirmed a valid security code for this session yet, or the code was entered for a different saved card. Nothing was charged |
security_code_not_verified | 402 | Strict security-code check: the card issuer did not report a match, so the charge was not completed. Nothing was charged |
security_code_check_in_progress | 409 | Capture or void of a strict security-code payment whose check is still being finished automatically. Retry shortly |
mit_anchor_unknown | 422 | A merchant-initiated charge of a saved card left out mit.original_transaction_id, and the card has no customer-present payment to link it to. Nothing was charged |
buyer_required_for_saved_card | 422 | The session's provider saves the card as part of the charge and needs a buyer to save it against. Nothing was charged. The buyer is fixed when the session is created and cannot be added afterwards — create a new session with buyerId. See below |
buyer_not_found | 404 | The buyer id is unknown to this merchant (opaque — same body for a missing id, another merchant's buyer, or a test/live mode mismatch) |
buyer_email_conflict | 409 | A buyer with no reference was updated onto an email another buyer with no reference already has, or a sign-up with no buyer_id used a customer's email. Nothing changed; not retryable |
buyer_reference_conflict | 409 | POST /v1/buyers used an external_id that belongs to a buyer created with your key for the other mode (test vs live). Nothing changed; not retryable |
buyer_update_conflict | 409 | Other updates to the same buyer's metadata kept landing while this one was applied. Nothing changed; retry the same request after a moment |
mirror_amount_below_line_items | 400 | The connected-store mirror's line items (plus shipping, on Next Commerce) exceed the amount being charged. Refused before the charge — the store order would be worth more than the money taken. One-sided: charging more than the lines itemise is allowed. See Connected Platforms |
refund_declined | 422 | The provider declined or refused the refund — no money moved through this refund. If error says the payment was disputed, the buyer already has the money back through the chargeback: do not retry or refund another way. Otherwise a corrected retry is possible, with a new Idempotency-Key. See below |
service_unavailable | 503 | The endpoint is temporarily unavailable — retry with backoff |
feature_unavailable | 503 | The capability is deliberately switched off, not briefly down. Retrying will not clear it — degrade to your webhook path. See below |
rate_limit_service_unavailable | 503 | The rate limiter itself is unavailable — you have not exceeded a limit |
charge_at_submit_not_enabled | 422 | This session is not eligible for charge-at-submit — vault the card and charge server-side |
validation_url_scheme_forbidden | 400 | successUrl / cancelUrl must be HTTPS on a public host in live mode (localhost is test-mode only) |
webhook_subscription_not_found | 404 | The webhook-subscription id is unknown to this merchant |
webhook_subscription_conflict | 409 | A subscription already exists for this URL — update or delete it instead |
webhook_subscription_url_immutable | 400 | An update sent url. A subscription's URL cannot change; nothing was changed. Create a new subscription and delete the old one |
webhook_event_not_found | 404 | The webhook-event id is unknown to this merchant |
wallet_domain_not_found | 404 | The wallet-domain id is not registered to this merchant |
wallet_domain_invalid | 422 | Body failed validation — either domain is not a bare hostname, or wallet_type is not apple_pay / google_pay |
wallet_domain_wrong_type | 404 | Only Apple Pay registrations host a verification file |
wallet_domain_no_binder | 409 | No wallet-capable gateway on the account yet |
wallet_domain_rate_limited | 429 | One check per 30 seconds per domain and wallet: poll for status instead |
wallet_domain_provider_unavailable | 503 | The upstream domain-registration provider is unreachable — retry with backoff |
wallet_session_refused | 422 | The payment provider refused to start the Apple Pay or Google Pay session, usually because the domain is not registered or verified for wallets. Not retryable: hide the wallet button and fix the domain. See below |
wallet_not_saved | 422 | An Apple Pay or Google Pay save (or a charge that asked to save, on a connection that refuses to save wallets) came back without a saved wallet. Nothing was charged or saved. Do not resend the same request. See below |
url_not_fetchable | 422 | The style-match tool in these docs could not read the page at that URL, for a reason a retry will not change. Try another public page. See below |
report_too_large | 422 | A payment report request is valid but too big. Not retryable unchanged: narrow it. See below |
mirror_settle_only_disabled | 400 | mirror.settle_only was refused for this request — use parent_order_ref with the add-on's line_items instead |
mirror_settle_only_order_not_payable | 409 | mirror.settle_only: the store order is cancelled, refunded, a test order, or has nothing left to pay. The buyer was not charged. See below |
mirror_settle_only_amount_mismatch | 400 | mirror.settle_only: your amount or currency does not match the store order's unpaid balance. Charge order_balance. The buyer was not charged |
mirror_settle_only_unverifiable | 503 | mirror.settle_only: the store order could not be read, or another payment for it is still being recorded. Retryable. The buyer was not charged |
Connected-platform and order-model refusals
These refuse the request before any charge, so the buyer is never charged when one fires — with one exception. A raw mirror block on POST /v1/payment_intents with destination: shopify is checked only partially before the charge: an unconnected store or a missing permission is discovered after the payment, so mirror_shop_not_authorized and mirror_shop_missing_scopes are never returned on that path — you get a completed payment and no store order. The order / mirrorTo shape is checked before the charge on both routes.
Two codes depend on the surface. A field the shared schema refuses at parse — a Shopify voucher or shipping — comes back as validation_error on POST /v1/sessions (and a Shopify shipping on order / mirrorTo likewise; that shape has no voucher field at all); only the raw block on POST /v1/payment_intents names it with a mirror_shopify_* code. Diagnosis for each — the likely cause and the exact check to run — is on Troubleshooting.
| Code | HTTP | Meaning |
|---|---|---|
mirror_malformed | 400 | The mirror block (mirror or metadata.mirror on POST /v1/payment_intents) arrived as a string or number rather than a nested JSON object — usually a client-side serialization bug |
mirror_too_large | 400 | The serialized mirror block is over the 4096-byte cap. Trim line_items, drop optional customer fields, or move long strings into metadata |
mirror_line_missing_product_ref | 400 | A mirror line item has no external_product_ref — every line needs the connected store's variant id |
mirror_line_invalid_variant_ref | 400 | A Shopify mirror line's external_product_ref (variantId on the order model) is not a product variant id. Send the numeric variant id or gid://shopify/ProductVariant/<id>, or remove it to send the line as a custom item. line_index names the line. See Linking lines to products |
mirror_shop_not_authorized | 400 | That store host is not connected to this merchant. Connect it in the dashboard, then retry with the exact same host in mirror.shop. A Next Commerce store has one owner: connecting a store another account owns moves it to you, and that account stops receiving its orders, refunds and webhooks. Shopify refuses a store another account holds. On a sandbox account, do not connect your live store: a sandbox may name your live Next Commerce store as it is, or leave out mirror. See Test orders |
mirror_test_order_limit_reached | 429 | A sandbox account's test orders go into your live Next Commerce store, so only a limited number can be open at one time. Nothing was charged. The response carries shop and limit. Cancel the open test orders in the store, or wait about a day for them to clear, then retry. Do not retry in a loop. The server SDKs do not retry it for you (retryable is false there) |
mirror_shop_missing_scopes | 422 | The store connection exists but lacks the permissions to write orders and customers. Re-grant the connection, then retry |
mirror_upsell_unsupported | 400 | Upsell append is not available for Shopify mirrors — drop parent_order_ref / upsell_key and send the extra item as its own order |
mirror_shopify_voucher_unsupported | 400 | Raw block on POST /v1/payment_intents only. Shopify does not price store vouchers. Use mirror.coupon for a display-only label, or charge the full amount |
mirror_shopify_shipping_unsupported | 400 | Raw block on POST /v1/payment_intents only. mirror.shipping is not carried onto a Shopify order, so the order total would be short by that amount. Fold shipping into a line_items[] entry instead |
mirror_voucher_disabled | 400 | Store-priced vouchers are not available on this call: on POST /v1/sessions always (hosted checkout never re-prices a discounted total), and on POST /v1/payment_intents while the platform has them switched off. Use mirror.coupon as a label that does not change the total |
mirror_voucher_amount_mismatch | 400 | The amount sent is not what the store prices this basket and code at. Quote it first, or omit the amount on a hosted session and let us price it |
mirror_voucher_rejected | 400 | The connected store refused the discount code — check it exists and is active there, or drop the voucher and charge the undiscounted total |
mirror_voucher_unverifiable | 503 | The store could not price the discount right now. Retryable — unlike every other voucher refusal on this list |
order_total_mismatch | 400 | The order model does not add up to the charge: line totals plus order.shipping.amount must equal amount. Coupons are display-only and do not reduce it |
order_mirror_conflict | 400 | Both the order / mirrorTo model and a raw mirror block were sent. They describe the same store order two ways — keep one |
order_model_disabled | 400 | The order / mirrorTo model is not enabled for this account. Send a mirror block instead, or ask support to enable it |
upsell_duplicate | 409 | This upsell_key already has a charge on this store. Nothing was charged again — treat the original payment named in original_payment_intent_id as the outcome. That field is omitted when the earlier payment is in the other mode (live or test) from your key |
Subscription refusals
These codes refuse a Subscriptions request. None of them charges or changes anything.
Starting a subscription
Returned by POST /v1/payment_intents with recurring, and by the product terms read. Every rule is checked before the card is charged.
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
recurring_not_enabled | 422 | Subscriptions is not switched on for this account, or it is switched on but its setup is not finished. An account setting, not a request problem. | Contact Von Payments support to switch Subscriptions on and complete the setup. To take a one-off payment meanwhile, send the charge without recurring. Nothing was charged. |
product_not_ready | 409 | The subscription product named in recurring.product has no renewal schedule yet (it was created before products carried one). A schedule is never guessed. | Set the product's renewal schedule in your dashboard, then retry the same request. Nothing was charged. |
recurring_signup_in_progress | 409 | Another sign-up for the same shopper email and product, in the same mode, has not finished yet: for example its bank check is still open in another tab, or a store retried a sign-up without an Idempotency-Key. Refused before the card was charged, because two sign-ups would charge the first period twice. An unfinished sign-up stops blocking after a day; one authorized and waiting for your capture, after a week; a paid one, once it is fully refunded or we have resolved it. | Wait for the other payment to finish. If it succeeded, the customer is subscribed, and a retry answers recurring_already_subscribed. If it failed or was abandoned, retry after a few minutes. If the answer does not clear, contact support: the other payment may be paid and need us to resolve it. Nothing was charged, and the Idempotency-Key is released. |
recurring_already_subscribed | 409 | A live subscription (active, past due, paused or on hold) already exists for this shopper's email and this product. A new purchase never changes an existing subscription, because an email alone does not prove who is buying. | Manage the existing subscription through the shopper's subscription link, or send the buyer_id the subscription was created under to restart it on a new card. Nothing was charged. |
subscription_product_not_found | 404 | No subscription product this key can reach: it does not exist, or belongs to another account or the other mode (a live key reaches only vsprod_live_*, a test key only vsprod_test_*). A sign-up and the terms read also refuse an archived product. Reading one product or changing it reaches an archived product by its vsprod_… id only. | Send the product's vsprod_… id or its store reference, with a key of the product's mode. |
invalid_recurring | 400 | recurring is malformed, has no product, or names a product that is unknown or matches more than one of your products. Also returned when recurring is combined with mit, network_token, payment_method_type or gateway, or when your account's payment setup cannot start subscriptions. | Send recurring: { product } with one live product of your account, and correct the field the message names. Nothing was charged. |
recurring_requires_consent | 400 | No payment_method was sent, or the card cannot start a subscription. It must be a card (not a wallet) the shopper saved in their own browser no more than 30 minutes earlier, never used for a merchant-initiated charge, and charged with its buyer_id when it is bound to one. A card imported with POST /v1/tokens, or saved on an earlier visit, never qualifies. | Collect the card from the shopper again in this checkout, and send the new payment_method within 30 minutes. Nothing was charged. |
recurring_requires_buyer_email | 400 | No buyer_email (or buyer.email) was sent. A subscription is tied to the shopper's email. | Add the shopper's email and retry. Nothing was charged. |
recurring_requires_buyer_ip | 400 | No buyer_ip_address was sent. It is kept with the agreement as evidence for a disputed renewal. | Send the public address your server saw for the shopper, and retry. Nothing was charged. |
recurring_terms_mismatch | 400 | Something in the request contradicts the product: a recurring.interval, interval_count, amount, currency or product_ref that differs from the product's, a top-level currency that is not the product's, or a top-level amount above the product's price. | Remove the contradicting field: the product's value is used. Leave out the top-level amount and currency to charge the product's price. Nothing was charged. |
recurring_amount_mismatch | 400 | No longer returned. Replaced by recurring_terms_mismatch. | Branch on recurring_terms_mismatch. |
When you send no buyer_id and buyer_email already belongs to one of your customers that has a buyer_id, the sign-up is refused 409 buyer_email_conflict: send that customer's buyer_id. A sign-up that sends a buyer_id is never refused for its email, because one email may belong to several of your customers. When buyer_id belongs to a customer created with your other-mode key, it is refused 409 buyer_reference_conflict.
Changing a subscription
Returned by the /v1/subscriptions calls. Nothing was changed.
| Code | HTTP | Meaning | What to do |
|---|---|---|---|
not_switched_on | 503 | Subscriptions is not switched on for this account. A setting, not an outage: retrying returns the same answer, and the server SDKs do not retry it. | Contact Von Payments support. Meanwhile, hide whatever calls it. |
subscription_not_found | 404 | No subscription this key can reach: an unknown id, another account's, or the other mode's (a live key reaches only vsub_live_*, a test key only vsub_test_*). On the Manage subscription link, also an ended subscription: only active, past-due, paused and held subscriptions have a page. | Check the id was not cut short, and that the key's mode matches the id. |
idempotency_key_reused | 409 | This Idempotency-Key was already used for a different change: another subscription, another action, or other values. | Send this change with a new key. Reuse a key only to retry the exact same request. |
subscription_status_not_allowed | 409 | The subscription's status does not allow this change. current_status names it. An ended subscription cannot be paused, resumed or cancelled. | Read the subscription, and pick a change its status allows. See Calls. |
subscription_renewal_in_progress | 409 | A renewal charge was sent and is waiting for its answer, which decides the next bill date. | Retry the same request with the same key after about a minute (Retry-After: 60). If it lasts more than an hour, contact support. |
subscription_date_out_of_range | 400 | The date is not YYYY-MM-DD or is outside the allowed range. min_date and max_date give the range, in your billing time zone. | Send a date inside the range. |
subscription_cancel_scheduled | 409 | A cancel is scheduled for the end of the paid period, so there is no next renewal to skip, and the next bill date cannot move. | If the customer wants to keep the subscription, withdraw the scheduled cancel with DELETE /v1/subscriptions/{id}/scheduled_cancel, then send this change with a new key. |
subscription_discount_invalid | 400 | The discount cannot be set. reason says why: 100% off, the wrong currency, a percent outside 0 to 100, an amount that is not above 0, or a duration that does not match duration_in_renewals. | Fix the field reason names. To stop charging, cancel or pause instead. |
price_increase_not_permitted | 403 | The change would raise the highest renewal charge above what this restricted key may charge (current_amount, max_amount, in amount_currency). Removing a discount counts as a raise. | Use a key whose per-charge maximum covers the new charge, or a full secret key. |
schedule_notice_required | 409 | The change would charge the customer sooner, less than 8 days from now: too soon for the 7-day notice we email to the customer. | If the customer asked for it, send it again with customer_requested: true, a note saying how they asked, and a new key. Otherwise pick a later date. |
subscription_customer_change_limit_reached | 409 | The change was sent with customer_requested: true, and the customer has already made their one schedule change (a skip, a new next bill date or a pause) in the last 12 months. next_change_allowed_on says when the next one is allowed. | Tell the customer the date. Do not resend without customer_requested to get round the limit. See Changes the customer asked for. |
subscription_pause_not_allowed | 409 | The pause was sent with customer_requested: true, and the business has turned customer pauses off. The subscription's customer_pause.allowed is false with reason: "not_allowed". | Do not offer the customer a pause. A pause you decide on yourself, sent without customer_requested, is not limited by this setting. Never leave the flag off to get round it. See Customer pauses. |
subscription_pause_too_long | 400 | The pause was sent with customer_requested: true, and the business limits a customer pause to max_cycles billing cycles. resumes_on was missing or later than max_resumes_on. | Send resumes_on on or before max_resumes_on (YYYY-MM-DD, your billing time zone). The subscription's customer_pause.max_resumes_on gives the same date before you ask. |
subscription_limited_discount_active | 409 | The interval cannot change while a discount for a set number of renewals is running. | Change the interval after the discount ends, or remove the discount first. |
schedule_change_pending | 409 | Another change that bills sooner or more often is waiting for its notice to the customer (pending_schedule_change on the subscription). Only one can wait at a time. | Withdraw it by sending the subscription's current value back, then send this change with a new key. |
return_url_not_allowed | 422 | The return_url is not on one of your own domains: a store you connected, or a domain your staff added under Subscriptions › Settings › Your websites. | Use an address on one of those domains, or leave return_url out. |
Changing a subscription product
Returned by the product calls. Nothing was created or changed.
Codes whose docs link names another page are documented there. Rate-limit buckets are on the Rate Limits page.
Validation Errors (400)
Validation errors include a descriptive message from the schema validator. For most of them the error field carries the raw validator output — a JSON array of issue objects, each with the failing field's path and a message:
Exception —
validation_unknown_field. That code'serroris a written sentence naming the offending fields, and the body carries anunknownFieldsarray alongside it. If you wrote a parser that assumeserroris always a serialized issue array, it will not handle this one — readunknownFieldsinstead.
{
"error": "[\n {\n \"expected\": \"number\",\n \"code\": \"invalid_type\",\n \"path\": [\n \"amount\"\n ],\n \"message\": \"Invalid input: expected number, received string\"\n }\n]",
"code": "validation_invalid_amount",
"fix": "Amount must be a positive integer in minor units (cents). 1499 = $14.99",
"docs": "https://docs.vonpay.com/integration/create-session#amount-format",
"selfHeal": {
"retryable": false,
"nextAction": "fix_request",
"llmHint": "Amount must be a positive integer in the currency's minor unit (cents for USD, pence for GBP). 1499 = $14.99. Decimals or strings are rejected.",
"actions": [
{ "type": "check_format", "field": "amount", "expected_pattern": "^[1-9][0-9]*$" }
]
}
}
Common validation issues:
| Field | Rule |
|---|---|
amount | Must be a positive integer (1–99,999,999) |
currency | Must be exactly 3 characters |
country | Must be exactly 2 characters |
successUrl | Must be HTTPS (localhost exempt in sandbox/test mode) |
lineItems | Max 100 items |
metadata values | Max 500 characters each |
For POST /v1/sessions, currency and amount are always required.
Debugging
Every /v1 response includes X-Request-Id (success or error). When contacting support, include this ID for fast issue resolution.
X-Request-Id: CezuRjYK_sos
The value is a short URL-safe identifier (mixed-case letters, digits, -, and _) on most routes; webhook-subscription and webhook-event routes return a full UUID instead.
Per-code reference
auth_missing_bearer
HTTP: 401. The request did not include an Authorization: Bearer <key> header. Add the header with your vp_sk_* or vp_pk_* key. (A legacy vp_key_* key, treated as a secret key, is also accepted.)
auth_invalid_key
HTTP: 401. The API key is malformed, unknown, or has been revoked. Check the prefix (vp_sk_test_, vp_sk_live_, vp_pk_test_, vp_pk_live_) and confirm the key exists in /dashboard/developers/api-keys. If you just rotated, double-check the grace window hasn't expired.
auth_key_expired
HTTP: 401. The key has rotated past its grace window (default 24 hours, configurable per rotation). Distinct from auth_invalid_key so SDKs can detect rotation and fetch a fresh key instead of failing the request. Get a fresh key from /dashboard/developers/api-keys.
client_secret_invalid
HTTP: 401, from a browser call under /v1/public/*. The X-Vonpay-Client-Secret header holds a value that is not this checkout session's client secret: malformed, another session's, or wrong. Nothing was done. A wrong value is always refused, even on a session that does not require the secret. Read clientSecret again on your server for this session (POST /v1/sessions or GET /v1/sessions/{sessionId}), or send no header. Never send a guess. vora.js reports it as frame_client_secret_invalid.
client_secret_required
HTTP: 401, from a browser call under /v1/public/*. This checkout session requires its client secret, and the call did not send it. Nothing was done. Your server receives clientSecret on POST /v1/sessions and GET /v1/sessions/{sessionId}; pass it to vora.sessions.retrieve(), which sends it as the X-Vonpay-Client-Secret header. vora.js reports it as frame_client_secret_required.
client_secret_in_path
HTTP: 400. The URL path of a /v1/public/sessions/{sessionId} call holds a client secret (a value with _secret_ in it) where the session id belongs. It is refused before anything is read or done, and the value is not recorded. An older vora.js (before 1.45.1) puts whatever it is given into the URL path: pass the client secret only to vora.js 1.45.1 or later, or pass the session id. See Client secret.
The _publishable variants
The browser-callable /v1/public/* routes return _publishable counterparts of
the three key errors above — auth_missing_bearer_publishable,
auth_invalid_key_publishable, auth_key_expired_publishable. Same HTTP
statuses, same meanings; the self-heal envelope steers you toward a
publishable key. For auth_key_expired_publishable, remember a publishable
key reaches the browser inside your built bundle, so replacing it takes a
redeploy, not an environment-variable change.
auth_invalid_key_publishable
HTTP: 401. Check the environment before the key. A publishable key is
scoped to the host that issued it, and the browser SDK's apiBaseUrl option
defaults to production — it is not inferred from the key — so a session
created against one host and a browser left on the default fails every call with
this code while the key is valid where it came from. That is why it carries
nextAction: "fix_request", not rotate_key. Diagnosis: Troubleshooting →
auth_invalid_key_publishable.
auth_key_type_forbidden
HTTP: 403. Primary cause: a publishable key (vp_pk_*) used against a secret-only endpoint like GET /v1/sessions/:id. Session creation is one of them: a price can only be set with a secret key, so POST /v1/sessions refuses a publishable-key request carrying amount, currency, lineItems, mirror or order, with reason: "price_requires_secret_key" and the refused names in refusedFields. Every session needs a currency, so a publishable key cannot create one: create sessions on your server with your secret key. Also fires on sandbox/live-mode mismatches, in both directions: a sandbox key attempting to create a live payment session, and a live key used on a sandbox account (POST /v1/sessions, POST /v1/payment_intents, POST /v1/tokens and GET /v1/capabilities). A sandbox account holds test keys only; a live key there is refused outright and is never simulated. The fix field on the response tells you exactly what to switch to.
api_key_permission_denied
HTTP: 403. The API key is a restricted key: it is valid, but it holds only the permissions chosen when it was created, and this request needs one it does not hold. The error string names the permission. When the key holds only a narrow permission, refused_fields lists the request fields that permission does not cover. Retrying does not help. Use a key that holds the permission, or create a new restricted key that includes it: a restricted key's permissions can never be changed after it is created.
api_key_limit_exceeded
HTTP: 422. The charge, refund or checkout session total does not fit the restricted key's money limits, so it was refused before anything was sent. Nothing was charged, refunded, created or changed. Branch on limit:
limit | Meaning |
|---|---|
per_charge | The charge is over the key's per-charge maximum |
per_session | A checkout session's total is over the most one payment under the key may be: its per-charge maximum, or its 24-hour total when that is lower. Returned by POST /v1/sessions and by a total change with PATCH /v1/sessions/{sessionId} |
daily_total | The charge or session would take the key's rolling 24-hour total past its limit. Approved and still-pending charges count; declined ones do not. Each payment session the key created also counts, at its total, while it is under 24 hours old or still open for payment, paid or not. Expiring an unused session frees its room. Clears by waiting |
currency | The charge or refund is not in the key's limit currency, limit_currency |
per_refund | The refund is over the key's per-refund maximum. A refund with no amount counts as the whole remaining balance |
refund_daily_total | The refund would take the key's rolling 24-hour refund total past its limit. Requested and completed refunds count; failed and canceled ones do not. Clears by waiting |
not_set | The key can charge or refund but has no limit for that action |
unreadable | The key's limits could not be read or counted |
unsupported | Your payment connection cannot apply a 24-hour limit. Use a key with only a per-charge maximum |
With per_charge, per_session, daily_total, per_refund or refund_daily_total, limit_minor is the limit and, for the two 24-hour totals, used_minor is what already counts, both in minor units of limit_currency. A key's limits can never be changed: create a new key for different limits.
On a session with recurring, the renewal price is capped the same way. A key with no charge limit, a full key and a mode: "setup" session are not capped.
platform_fee_exceeds_amount
HTTP: 422. The platform fee set on your account (a percentage plus any fixed amount per payment) would be at least the whole payment, so the payment was refused before anything was sent. Nothing was charged. This is an account setting, not a request error: a retry fails the same way for a payment this size or smaller. Contact support to correct the fee.
merchant_not_onboarded
HTTP: 403. You tried to create a live-mode API key before onboarding review completed. The message reads "Your account is being reviewed. Live keys unlock once we approve it.", or "This account is not approved for live payments." if the application was declined. Test keys come from your business's sandbox at any time; live keys can be created once the account is ready to transact. Distinct from auth_merchant_inactive (401), which fires on a previously-approved account that has since been deactivated.
A live key needs approval and a connected payment processor. This code covers the first condition only; live_keys_need_processor covers the second.
live_keys_need_processor
HTTP: 403. The account is approved, but no payment processor is connected to it yet, so a live key would have nothing to charge against. Connect one and live keys unlock; no second approval is needed. Rotating an existing live key is not gated.
test_keys_are_sandbox_only
HTTP: 403. Test keys were requested on a live business. Test keys belong to the business's sandbox: open Developers, activate the sandbox, and create them there. Test keys you already hold on the live business keep working.
live_keys_not_on_sandbox
HTTP: 403. A live key was requested on a sandbox. Switch to your live business to create live keys. Live keys you already hold keep working.
processor_check_unavailable
HTTP: 503. We could not confirm the account's payment setup in time. This is our side, not your request: nothing about the account has changed and no decision has been made. Retry shortly. A repeat is worth reporting to support.
auth_merchant_inactive
HTTP: 401. The merchant account has been disabled or suspended. Check /dashboard for status banners; contact support if unexpected.
auth_service_unavailable
HTTP: 503. The authentication service is temporarily unavailable. This is retriable — the SDK auto-retries with backoff.
session_not_found
HTTP: 404. The session ID does not exist. Sessions are scoped to the merchant; you cannot look up another merchant's session with your key. Confirm the ID was created with the same key mode you're now querying with. A lookup by payment intent or transaction id answers its own code: payment_intent_not_found or transaction_not_found.
payment_intent_not_found
HTTP: 404. No payment intent with that id for this API key. Returned by GET /v1/payment_intents/{id} and its capture, void, cancel and mirror-order routes, by POST /v1/refunds and GET /v1/refunds for a payment_intent that is not found, and by a merchant-initiated POST /v1/payment_intents whose original payment is not found. The answer is the same for an unknown id and for another account's payment, so it never confirms that an id exists. On the payment intent routes and GET /v1/refunds it is also the answer for a payment of the other key mode: a test key works only with vpi_test_*, a live key only with vpi_live_*. Nothing was read or changed. These lookups answered session_not_found before.
Check that the id is the id returned by POST /v1/payment_intents, that it is not cut short, and that the key's mode matches the id's prefix. Sending the same request again returns the same answer.
transaction_not_found
HTTP: 404. No transaction with that id for this API key. Returned by POST /v1/refunds and GET /v1/refunds for a transaction that is not found. The answer is the same for an unknown id and for another account's transaction. On GET /v1/refunds it is also the answer for a transaction of the other key mode; POST /v1/refunds refuses the other mode with 400 payment_method_mode_mismatch. Nothing was refunded. These lookups answered session_not_found before.
Check that the id is a vp_tx_ id this account received (for example vp_tx_id on GET /v1/sessions/{id}), that it is not cut short, and that the key's mode matches the id's prefix. To refund by payment intent instead, send payment_intent. Sending the same request again returns the same answer.
checkout_address_not_found
HTTP: 404. The request reached a {name}.vonpay.com address that is not serving checkout. Send it to the host of the checkoutUrl that POST /v1/sessions returned, and use that URL exactly as returned: it is on checkout.vonpay.com unless the merchant has turned on a branded address. Building the hostname yourself is what produces this error, and retrying the same host returns it again.
session_expired
HTTP: 410. The session expired (TTL configurable at create — default 30 minutes, range 5 minutes to 7 days), or its status is failed or cancelled. A session reopened for another card after a decline is pending, not failed, and does not get this error until it has no attempts left: a card entered into an already-used card form then is answered with this code and retry: { allowed: false, attempts_remaining: 0 }.
If the body carries expiredFrom: "processing", do not start over. The session ended while a charge on it was still being decided. On this 410, which only the buyer's checkout calls return, charged: false beside it means every recorded attempt ended without taking money. (The 409 from POST /v1/payment_intents can carry the same two fields, and there charged: false describes only that request.) Without charged, a charge may have been taken: do not tell the buyer they were not charged, and do not charge them again for the same order. Wait for the payment webhook, and contact support with the session id before charging again (see expiredFrom). Otherwise, create a new session. (If the session already succeeded, you get session_already_completed, HTTP 409, instead; see below.)
A repeat of an earlier card charge with the same Idempotency-Key usually gets that request's recorded result with replayed: true, not this 410. For a decline, that result carries charged: false. The repeat itself moves no money.
session_attempt_limit_reached
HTTP: 422. The checkout session has used all of its payment attempts. Nothing was sent to the payment provider and nothing was charged or saved by this request, and retrying on the same session returns the same code. If the buyer is still trying to pay, create a new session (POST /v1/sessions, with a new Idempotency-Key) and restart there. Repeated hits from one storefront usually mean automated card testing: do not create sessions in a loop. On a store that refuses some card brands, the same code also answers once one session has had the card brand checked 30 times (see card_brand_not_accepted), so it does not always mean the shopper used real payment attempts.
shopper_attempt_limit_reached
HTTP: 422. The store cannot accept a card from this shopper right now: too many of the cards this shopper saved at your store were declined recently. Nothing was sent to the payment provider and nothing was charged or saved. Not retryable, and a new checkout session returns the same code (unlike session_attempt_limit_reached, which is limited to one session). Show the shopper a plain message to contact the store. Do not tell them a number or a wait time, and do not create sessions in a loop: repeated hits usually mean automated card testing.
client_read_secret_limit_reached
HTTP: 409. POST /v1/payment_intents/{id}/client_read_secret minted nothing. The response's limit says why: live means 3 secrets of this payment still work, so give the page one of those or wait until one expires; ever means 10 have been minted for this payment, and no more ever will be. Nothing was minted or revoked. Not retryable. See Show the check in a pop-up on your page.
card_brand_not_accepted
HTTP: 422. The store does not accept the brand of this card, and the message names the brand. The card charge (POST /v1/public/sessions/{sessionId}/charge) can return it, and so can the card save (POST /v1/public/tokens) on an elements session with chargeAtSubmit: false or a mode: "setup" session, since 2026-11-15. Nothing was saved or charged, no payment was created, and the refusal does not count toward the session's attempt limits. Not retryable with the same card: ask the shopper for a card of another brand on the same session. Do not create a new session for it. One session can have the card brand checked at most 30 times; after that the endpoint answers session_attempt_limit_reached. In the browser, when the session carries your refused brands, vora.js 1.52.0 and later stops such a card before it is sent, and reports frame_card_brand_not_accepted.
bot_check_required
HTTP: 403. Browser verification is switched on for the account and a card charge (POST /v1/public/sessions/{id}/charge) or card save (POST /v1/public/tokens) carried no bot_check_token. Wallet saves are not checked, and neither is a card save from the embedded card form, where the payment was already made. It is refused before anything reaches the payment provider: nothing was charged or saved, no payment attempt was used, and nothing is stored that a resend could replay. The response's bot_check object carries what a client needs to obtain a pass and resend once. Browser verification is off unless Von Payments has switched it on for your account.
bot_check_expired
HTTP: 403. The verification pass had already been used or had expired: each pass is single-use and lasts five minutes. Nothing was charged or saved. Resend once with a fresh pass. On the card charge, send the same Idempotency-Key if you sent one: nothing was stored against it. If the resend is refused again, show the buyer that the payment could not be verified.
bot_check_failed
HTTP: 403. The verification pass was not valid, or was issued for a different checkout session, action or site. Nothing was charged or saved. Do not resend the request: tell the buyer the payment could not be verified and nothing was charged. Pressing Pay again runs a fresh verification.
bot_check_unavailable
HTTP: 503. The payment could not be verified right now: verification could not complete while the account is in its strictest protection setting, or too many unverified attempts were made recently. Nothing was charged or saved. This is not an unclear outcome, so do not poll for a charge. Wait about a minute and retry.
session_already_completed
HTTP: 409. A completion call (POST /v1/public/tokens or …/charge), or a session retrieve, hit a session whose payment has already finished: the session reached succeeded, so the buyer was charged exactly once (on a captureMethod: "manual" session, authorized exactly once: read charged on the response). The same answer is given when money for the session was recorded after its time limit passed.
A payment that is still running gets its own code, session_payment_in_progress, so on the buyer's card charge this code always means the session is finished. POST /v1/payment_intents with a session_id also answers it for a linked session that expired, or had a payment-provider transaction recorded without succeeding. The body carries charged: false, and expiredFrom: "processing" when the session ended while its charge was being decided; the outcome may not be final.
On POST /v1/payment_intents, charged: false does not mean the buyer's card is untouched: your request charged nothing, and on a captureMethod: "manual" session the session's own payment can be authorized and held. A hold sends only payment_intent.authorized until you capture it, so read GET /v1/payment_intents/{id} (status: "authorized") or the session (paymentStatus: "held", whose paymentIntentId is the hold), or wait for payment_intent.authorized.
Do not retry, and do not create a new session for the same purchase: either would risk charging the buyer again. Read the outcome from your payment_intent.succeeded / payment_intent.authorized / charge.succeeded / charge.failed webhook or the session read, and show the buyer the state it reports.
This is a distinct 409 Conflict, not session_expired's 410 Gone, so even a status-only client will not "start over" into a re-charge. Branch on the code for the remediation.
payment_form_expired
HTTP: 409. Only on a session that a decline re-opened for another card. The buyer's card was entered into the card form that an earlier, declined attempt on the same session had already used, so the payment provider refused it. Nothing was charged (on a card save, nothing was saved), the card was never judged, and the session is still open. selfHeal.retryable is true and nextAction is reload_payment_form.
The body carries retry. With retry.allowed: true the fresh card form is ready: load it and submit again. With allowed: false and attempts_remaining above 0 it is still being prepared: read the session again after about a second. Loading the card form (POST /v1/public/binder-load) answers this code too, with retry.allowed: false and no form, while the fresh form is being prepared: load it again in about a second. On the charge itself, this code is sent only while the session can still take a charge; once it has no attempts left, or the fresh form could not be made, the charge is answered 410 session_expired with retry: { allowed: false, attempts_remaining: 0 }. Do not ask the buyer for a different card because of this error.
If you use the browser SDK, you do not handle this code yourself: vora.js reloads the card fields and reports the outcome to your page, see Embedded Fields errors.
payment_form_busy
HTTP: 409. Only on loading the payment form (POST /v1/public/binder-load). A card or wallet payment on this session is running right now, so its payment form is not handed out again. This request charged nothing. It normally clears within a few seconds. selfHeal.retryable is true and nextAction is wait_and_retry.
Read the session again (GET /v1/public/sessions/{id}) after about a second: it is then either paid or offers a fresh payment form. Do not start another payment, do not create a new session, and do not treat this as a decline.
payment_form_used
HTTP: 409. Only on a card save with no card details (POST /v1/public/tokens on a mode: "setup" session, or an elements session with chargeAtSubmit: false). The card form on this session was already used by an earlier submit, usually a resend after a save that succeeded, so the payment provider will not accept it again. Nothing new was saved and nothing was charged. selfHeal.retryable is false and nextAction is create_new_session.
If the earlier save succeeded, that card is saved: use the card id from that response, or list the buyer's cards with GET /v1/payment_methods, rather than asking the buyer again. Reloading the same session's form returns the same used form, so to let the buyer enter a card again, create a new session and load its form. Not payment_form_expired, which comes with a fresh form on a session that a decline re-opened.
charge_in_progress
HTTP: 409. A payment for this request is already under way, has already completed, or has an outcome we cannot confirm yet, and this request was refused so it is not taken twice. The code is keyed on one of two things, depending on the surface:
| Surface | What the code is keyed on | Read this to resolve it |
|---|---|---|
| Hosted checkout / Embedded Fields | the session | Retrieve the session, or wait for the charge.* webhook |
POST /v1/payment_intents | your Idempotency-Key for this merchant | Read the original payment's status |
Idempotency-KeyOn some provider configurations a second attempt becomes a second charge, and once both land nothing can merge them. A 409 here is not a key collision to route around: an Idempotency-Key names the operation, never the attempt — see Idempotency.
On POST /v1/payment_intents, depending on your account's payment connection, it has up to three causes. Each one means do not create another payment for this order:
| Cause | What the error message tells you |
|---|---|
Your Idempotency-Key was already used for a charge | Whether that charge is still running, has completed (approved or declined), or may have reached the buyer's card with no confirmed outcome. In that last case, contact support before doing anything else |
| This request reached the payment provider, and its outcome is not confirmed yet | The buyer may have been charged. A charge that settled for a different amount than requested is reversed automatically where we can identify it; where we cannot, our team is alerted and reverses it by hand. Contact support with the payment intent id to confirm |
| An earlier charge on the same saved card has not finished resolving | Nothing was sent for this request. Do not charge the card again until the earlier payment resolves |
When we can identify the earlier payment, the response carries original_payment_intent_id and the message names it: read it with GET /v1/payment_intents/{id}. It is omitted when it could not be read, or when that payment is in the other mode (live or test) from your key, so treat it as optional.
If you never received the original response and the 409 carried no original_payment_intent_id — the call reached us, the connection dropped, and you hold a key but no id — there is no lookup by Idempotency-Key, and the payment_intent.* webhooks carry the payment id rather than your key. Design for it: send your own order reference in metadata on every charge and record the Idempotency-Key against your order before you send the request, so a dropped response is recoverable from your records plus reconciliation. If it has already happened, stop and contact support with the Idempotency-Key you sent; a retry with a fresh key cannot resolve it. The same applies if the code persists beyond about a minute.
The browser SDK surfaces the session-scoped condition as frame_charge_in_progress — see Embedded Fields — errors.
A different code, one word apart — charge_already_in_flight is a 409 you do retry, with the same key:
charge_already_in_flight | charge_in_progress | |
|---|---|---|
| Retry? | Yes — same body, same key | No — do not retry, do not reissue |
| What to do | Wait the advertised interval, send it again | Read the original payment's status, or wait for the charge.* webhook |
session_payment_in_progress
HTTP: 409. Another payment attempt on this session is still running, so this request was refused. For example the buyer pressed pay twice, or an Apple Pay or Google Pay payment on the same session is still waiting on the buyer's bank. This request charged nothing (the body carries charged: false; on a card or wallet save, nothing was saved either), but the other attempt's outcome is not known yet. selfHeal.retryable is false and nextAction is reconcile, except after a processing error (below).
Do not show the buyer success, and do not show a decline. Do not resubmit automatically and do not create a new session. Read the session until it settles, from your server with GET /v1/sessions/{id} or from the browser with GET /v1/public/sessions/{id}?accept=payment_in_progress, or wait for the charge.succeeded / charge.failed webhook. From the browser, send ?accept=payment_in_progress: with it, the read answers sessionStatus: "payment_in_progress" with no payment form while the other attempt runs. Without it, a session whose payment is running inside its time limit reads sessionStatus: "ready", so the read cannot tell you that attempt is still running. A paid session then answers session_already_completed; a session that offers a payment form again means that attempt did not pay, and the buyer may submit again. The same answer is given when the session's time limit passes while a charge on it is still being decided, for example while the buyer is still on their bank's security check. If the session still reads in progress after several minutes, contact support with the X-Request-Id.
It comes from the buyer's card charge (POST /v1/public/sessions/{id}/charge), the card or wallet submit (POST /v1/public/tokens), the Apple Pay and Google Pay session calls (POST /v1/public/wallets/apple-session and google-session, when the session's time limit passed while its charge is still being decided), and POST /v1/payment_intents when you send the session_id of a session that charges at submit and whose own payment is still running. On that last one, do not charge the buyer with a payment intent instead: if the session's payment does not succeed, the buyer pays again through the checkout. The browser SDK reports this code as frame_other_payment_in_progress, see Embedded Fields errors.
After a processing error
When the session's previous payment ended with processing_error, the next Pay press is checked with the card processor first, and it is never sent within 5 minutes of the earlier attempt. While that check runs, the press answers this code with selfHeal.retryable true and nextAction wait_and_retry: nothing was charged, so ask the buyer to try again in a few minutes. If the processor shows money on the earlier attempt, or it still cannot be confirmed 15 minutes after the earlier attempt, the press answers payment_under_review instead.
payment_under_review
HTTP: 409. The session's previous payment ended with a processing_error, and the card processor shows money on it, or we could not confirm within 15 minutes of that payment that it took none. This request charged nothing. selfHeal.retryable is false and nextAction is contact_support.
Do not let the buyer pay again: a second payment could charge them twice. Do not show a decline or success. Tell the buyer their payment is being reviewed and to contact you. Check the earlier payment in your dashboard before you take any new payment from that buyer. It comes from the buyer's card charge (POST /v1/public/sessions/{id}/charge) and the wallet payment on POST /v1/public/tokens.
charge_already_in_flight
HTTP: 409. Retryable — but only with the same Idempotency-Key. Another request carrying this key is still running, or an earlier one stopped before we could record its outcome; we refused rather than send a second charge for the same key. This request did not charge the buyer.
Wait retryAfterSeconds (carried on the response) and retry with the same request body and the same Idempotency-Key. A fresh key is the one action that turns this into a double charge — an earlier attempt on the existing key may already have charged the buyer. When we know which earlier attempt holds the key, and it is in the same mode (live or test) as your key, the response also carries original_payment_intent_id: read that payment with GET /v1/payment_intents/{id}. If the code keeps coming back for more than about a minute and no id was returned, stop: there is no lookup by Idempotency-Key, so contact support with the key you sent. Contrast with charge_in_progress, which you do not retry at all.
charge_reservation_unavailable
HTTP: 503. Retryable — with the same Idempotency-Key. The durable record we write for your key before charging could not be written, so the request was refused. The buyer was not charged — nothing was sent to the payment processor, so there is no in-flight attempt to collide with. Retry after retryAfterSeconds with the same request body and the same key.
A charge sent without an Idempotency-Key is reserved too and can get this code. Retry the same body, and send a key this time: without one, a retry is treated as a new payment. See Idempotency.
expected_amount_mismatch
HTTP: 409, from a wallet payment (POST /v1/public/tokens) or a card payment (POST /v1/public/sessions/{sessionId}/charge). The buyer was not charged: the refusal happens before anything reaches the payment provider. expected_source says why:
buyer_approved: theexpected_amountsent with the payment (the total shown to the buyer) differs from the session's current total, usually because it was changed withPATCH /v1/sessions/{id}after the buyer saw it.request_start: noexpected_amountwas sent, and the total changed while the request was being processed.
The response also carries expected, actual (the session's current amount and currency) and mismatched (["amount"], ["currency"] or both). Show the buyer the current total and have them approve it again. Not retryable as-is. The express-checkout element reports this to your page as frame_wallet_total_mismatch.
session_not_expirable
HTTP: 409, from POST /v1/sessions/{sessionId}/expire. Nothing changed, and this is not a safe signal that no money moved. A session is expirable while it is pending, unpaid, and carries no recorded payment, and a declined elements + chargeAtSubmit session can be closed once it has been quiet for 10 minutes. On a declined session the response carries a reason: recent_activity (with retryAfterSeconds and a Retry-After header) means call again after that many seconds; payment_may_be_in_flight may never clear, and an unrecognised reason means the same. Any other state returns this code, including a session that expired while a payment was in progress (expiredFrom: "processing") or before the platform recorded how sessions expired (expiredFrom: null). A payment may exist for those that has not been reported yet.
Do not take payment for the order another way after a 409, and do not rely on polling the session or on a webhook to tell you what happened: there is no session-expiry event, and otherwise a payment that lands on an already-expired session is not reported today. On an elements + chargeAtSubmit session, expiredFrom: "processing" can later change to failed once the provider confirms the payment was never authorized after a timed-out bank check, and that attempt's payment_intent.failed / charge.failed webhooks announce it. Read the session object in the response, then contact support with the session id. Contrast 200, which does mean the session is closed and nothing can start on it. See Close a session so you can charge another way.
session_not_modifiable
HTTP: 409, from PATCH /v1/sessions/{sessionId}. Nothing was changed. The response carries reason and a session object (id, status, paymentStatus):
not_open: a payment is in progress, the session was paid, held, declined or expired, it was created to forward the card to another processor, or it has passed its time limit. Past its time limit, the echoedsessioncan still readpendingandunpaidfor a short while. Do not take payment for the same order another way while a payment is in progress.integration_mode: only sessions created withintegrationMode: "elements"can be changed, because hosted and embedded-form sessions fix the total and the metadata when the payment form loads. Create a new session.setup_session: a no-charge setup session has no total.store_order: a total change on a session linked to a connected-store order, whose total is the store's. Change the order instead. Its metadata can still be changed.in_page_bank_check: a total change on a session where the buyer's bank checks the amount on the page before paying, and the charged total must match the checked one. Create a new session with the new total. Its metadata can still be changed.
A request that sends buyer details (buyerId, buyerEmail, setupForFutureUse or storedCredentialUse) works only on an elements payment session with chargeAtSubmit: true. It can also get these reason values:
stored_credential_declared: the session was created withstoredCredentialUserecurringorinstallment, and the request sends another value. The same value again answers200.customer_named: the session already names a customer, and the request changes a value. A repeat of the stored values answers200.subscription_signup: the session starts a subscription.forwarded_gateway: the session sends the card to your own gateway.card_form_group: the session has acard_form_group.payment_attempted: a payment was already tried on the session.
integration_mode, setup_session, store_order and not_open apply to it too. You can ignore this answer: the payment goes ahead on what the session already holds, and the card is not kept. With buyerId, the card is not kept under that customer.
Not retryable. A session that is still open but kept changing while your change was applied answers session_update_conflict instead, which is retryable. See Change an open session's total or metadata.
session_update_conflict
HTTP: 409, from PATCH /v1/sessions/{sessionId}. Nothing was changed, and the session is still open and payable. A change is applied only if the session has not changed since it was read; when another change lands first (another metadata update to the same session, or a payment attempt that started and was handed back), the server reads the session again and retries. This code means every try was overtaken. The response carries reason: "concurrent_update" and a session object (id, status, paymentStatus) showing the session as last read.
Retryable: wait a moment and send the same request again. If you update one session from several places, send the updates one after another rather than in parallel. Do not abandon the checkout or take payment another way because of this answer. The buyer equivalent is buyer_update_conflict.
A card payment (POST /v1/public/sessions/{id}/charge) or a wallet payment (POST /v1/public/tokens) also answers it, with reason: "concurrent_update" and no session object. Your server changed the session's buyer details (for example with buyerId or buyerEmail) as the payment started. Nothing was charged and the session is still open. The buyer pays again: with the same card for a card payment. Do not ask for a different card, and do not create a new session.
card_form_adopt_refused
HTTP: 409. The checkout could not move the card form of the old session to the new one, so nothing was changed: the old session is as it was, and the new session keeps its own card form. Your page sees this through vora.js: collection.switchSession() answers not_switched with the same reason, and the page builds a new form for the new session. Not retryable.
Handle every reason the same way: build a new form. If a payment was already sent from the old form, first read its outcome on your server, and do not offer another payment while it is pending or unknown. The reasons are for your logs. Two of them point at your server:
not_declared: the two sessions do not carry the samecard_form_group. Your server sets it onPOST /v1/sessionsorPATCH /v1/sessions/{sessionId}, for the sessions of one shopper's checkout.group_too_broad: the group holds too many open sessions to be one shopper's checkout. Derive it per checkout on your server, never from a customer id, a store id or a constant.
The others describe the two sessions or the form: different_merchant, different_provider_instance, different_mode, different_currency, different_buyer, integration_mode_unsupported, form_mismatch, form_used, form_expired, source_has_payment, source_not_closable, target_not_open, form_owned_elsewhere and chain_too_long.
session_wrong_state
HTTP: 409. The session is in a state that forbids this operation (e.g. the session already succeeded and cannot be cancelled). Read the response body — the fix field describes the allowed state transitions.
session_integrity_error
HTTP: 500. Internal session state mismatch. Capture the X-Request-Id and contact support — not safely retriable without investigation.
currency_not_supported
HTTP: 422. The request named a currency that new payments refuse: IQD, LYD, ISK, MGA, CLF, UYW, UYI and UGX. A wrong assumption about how many decimal places their amounts carry would show or pass on an amount 10× or 100× off what was charged, so they are refused. Nothing was charged, saved or created. The body carries currency, the refused code. Returned by POST /v1/sessions, PATCH /v1/sessions/{id} and POST /v1/tokens when they send currency, and by POST /v1/payment_intents and POST /v1/mirror/quote. Payments already made in these currencies can still be read, captured, voided and refunded. Not retryable as sent: use a different currency, or contact support if you need this one.
validation_error
HTTP: 400. The request body failed schema validation. The response error field contains the validator's output — a JSON array of issue objects, each carrying the path to the bad field (for example path: ["amount"]) and a message such as Invalid input: expected number, received string. On POST and PATCH /v1/webhook_subscriptions it is also the answer when the enabledEvents list contains any unrecognised event name: the message is the fixed sentence "verify the URL and that every event type is a recognized event", nothing is stored, and no signing secret is issued. See Webhook events. On POST /v1/payment_intents it is also the answer to an Idempotency-Key starting with vp_sys: (any letter case), a prefix reserved for platform use: nothing is charged, and the message is "Idempotency-Key values starting with 'vp_sys:' are reserved for platform use. Choose a different key and retry." Send the request again with a different key.
validation_missing_field
HTTP: 400. A required field is missing. See Create a Session for the required fields.
validation_unknown_field
HTTP: 400. The request body carried one or more fields the endpoint does not accept. The error string names them in a readable sentence and unknownFields lists them, up to 20. When there were more, unknownFieldCount gives the full number.
This fires on every endpoint with a strict schema — payment intents, refunds, tokens, buyers, webhook subscriptions, sessions. Unknown fields are refused, never ignored. Two causes, in rough order of frequency:
- Casing. The session surface is camelCase —
success_url→successUrl,line_items→lineItems,unit_amount→unitAmount. Where asuggestionsmap is present it gives the canonical name for each offending key. - Right field, wrong endpoint. The field is real but belongs on a different call, and the
errorstring says where. The most common instance:setup_for_future_usesent toPOST /v1/payment_intents. Reuse consent is captured when the card is vaulted and read back automatically at charge time, so the charge call refuses it. See Preventing a double charge → common mistake.
Do not retry until the field is moved or renamed — retryable: false, nextAction: fix_request.
Wanting to attach arbitrary custom data? Nest it under the top-level
metadataobject, which is stored and round-tripped verbatim.
validation_invalid_amount
HTTP: 400. Amount is not a positive integer, is zero, or exceeds the 99,999,999 maximum. Remember: amounts are in minor units — 1499 = $14.99, not $1,499.
merchant_not_configured
HTTP: 422. It has two meanings:
-
On a charge or session create: the merchant has not completed onboarding for this operation, usually because payment-provider credentials are not provisioned. Complete boarding via the merchant dashboard, or contact support.
-
On a refund, capture or void of an existing payment: there is no payment account the operation can safely be sent to, so it was refused, not sent to a different account. No money was moved. This happens in three cases:
- the payment was made on a payment account that is no longer connected to the merchant;
- no payment account can be matched to the payment (none, or more than one);
- a capture only: the payment's account is no longer active, and the merchant has no other active payment account for the payment's mode (live or test). While the merchant's payments are switched off, such a capture still goes through. A refund or void of that payment is always accepted.
Nothing in the request can fix it and retrying will not help: contact support with the
X-Request-Id. If the payment account cannot be confirmed just now, the answer is a retryable503service_unavailableinstead, with no money moved: retry shortly.
binder_unavailable
HTTP: 409. The merchant has no payment provider configured for this operation, so the request cannot be routed to one. The merchant (not the integrator) must complete onboarding to attach a payment provider. A test key does not get around it: a test payment runs on the account's own provider test environment, so an account with no provider cannot take test payments either. To build before onboarding is done, the account holder applies for a sandbox account in the dashboard (see sandbox_account_required). Not retriable as-is.
sandbox_account_required
HTTP: 422. Test payments run only on a sandbox account backed by a payment provider's test environment. This request had no test environment to reach, for one of two reasons:
| You sent | On | Do this |
|---|---|---|
A test key (vp_sk_test_*, vp_pk_test_*) | A live merchant account | Use your sandbox account's test keys. A live account's test keys cannot take a test payment |
| A test key | A sandbox whose processor test account is not set up yet | Open the sandbox in Developer Tools and click Set up dashboard access, which finishes setting it up, then send the request again |
Returned by POST /v1/sessions, POST /v1/payment_intents, POST /v1/tokens, GET /v1/capabilities and the browser session, token and checkout calls. Nothing was charged. Retrying, or switching between test and live keys on the same account, will not help, and a live key on a sandbox account is refused with auth_key_type_forbidden.
capability_not_supported
HTTP: 422. The merchant's payment provider does not support the operation you invoked — for example partial refunds, ACH, or network tokens — even though the route exists. Call GET /v1/capabilities for the merchant's supported_operations matrix and gate capability-dependent calls on it; the matrix is provider-dependent. Not retriable without a different capability or provider.
It is also returned by POST /v1/sessions when the request asks for captureMethod: "manual" on an account whose payment connection cannot hold a payment for later capture. That refusal happens before any session exists, so nothing is charged. Create the session with automatic capture, or contact support about a connection that can hold.
POST /v1/security_code_sessions returns it when the account's payment connection does not support re-entering a saved card's security code, or when the saved payment method is a wallet rather than a card. Nothing is charged.
rate_limit_exceeded
HTTP: 429. A route limit was reached. A call with a secret key is counted per key on the server API, with a loose per-IP ceiling beside it; publishable-key, unauthenticated and browser calls are counted per IP. X-RateLimit-Limit shows the ceiling that applied. Wait the Retry-After interval (1 to 60 seconds; the same number is in selfHeal.actions[].retryAfterSeconds), then retry with jittered exponential backoff. The SDK auto-retries up to maxRetries times. The per-API-key axis has its own distinct code, rate_limit_exceeded_per_key.
On POST /v1/sessions this per-IP limit (10/min) applies only to calls with a publishable key or no key. Create sessions from your server with a secret key (vp_sk_*, or a legacy vp_key_*): those calls are limited per key, plus a loose 1500/min per IP, so integrations sharing one outbound address (serverless or edge workers) do not share a quota. See Rate Limits.
rate_limit_exceeded_per_key
HTTP: 429. Per-API-key bucket exceeded on POST /v1/sessions (30 session creates/min). Wait the Retry-After interval (1 to 60 seconds), then retry with jittered exponential backoff. A single key should not exceed this under normal traffic. If your integration legitimately does, contact support for a ceiling increase. Distinct from rate_limit_exceeded so SDKs can tell them apart.
provider_unavailable
HTTP: 502. Upstream payment provider is not responding.
⛔ Retriable on a charge only with the same Idempotency-Key. A 502 does not mean nothing happened — the provider was called and the response was lost, which is why the charge is recorded server-side as outcome-unknown. Send the retry with the same key you used the first time and it collapses onto the original attempt. Without a key there is nothing to collapse onto, and not every connection provides idempotency of its own, so a keyless retry can charge the buyer twice. The SDKs apply the same rule to their built-in retry: they withhold it on money-moving calls unless you supplied a key.
On a capture or void, check code before retrying: a 502 carrying payment_outcome_unknown means the provider accepted the operation, and it must not be retried.
On a charge, capture or void, only an outage, a timeout or an unconfirmed answer is a 502; on a refund, an unconfirmed answer is a 202 instead. When the provider definitely refuses a request, the answer is a 4xx that is not retryable as sent: provider_operation_refused on a capture or void, refund_declined or refund_before_settlement on a refund, and wallet_session_refused or wallet_not_saved on a wallet.
On a refund, a 502 means the refund was not processed and the refundable balance is unchanged. Retrying with the same Idempotency-Key only returns the stored failed refund and sends nothing, so send it again with a new key. A refund whose outcome is not known yet is never a 502: it comes back as 202 with status: "requested" and must not be issued again (A 202 is not a failure).
payment_outcome_unknown
HTTP: 502, from POST /v1/payment_intents/{id}/capture or POST /v1/payment_intents/{id}/void. The payment provider accepted the operation, but its result could not be recorded. The body carries capture_outcome: "unknown" or void_outcome: "unknown". The money may have moved (capture), or the hold may already be released (void).
⛔ Do not retry. A retried capture can capture twice. This is the opposite of provider_unavailable, the other 502 these routes return, which may be retried with the same Idempotency-Key: branch on code, never on the status alone. Read the payment intent back with GET /v1/payment_intents/{id}; the payment webhook reports the final outcome. Do not tell the buyer a hold was released until the intent confirms it. The response's selfHeal.nextAction is reconcile, and the server SDKs never retry this code on their own from 2.11.0.
provider_operation_refused
HTTP: 422, from POST /v1/payment_intents/{id}/capture or POST /v1/payment_intents/{id}/void. The payment provider refused the capture or void as an invalid request, and its own record shows the authorization still standing. Nothing was captured and nothing was released. selfHeal.retryable is false: the same request will be refused again, so do not retry it automatically.
Read the payment intent with GET /v1/payment_intents/{id} to confirm it is still authorized. If a capture was refused, check the amount against what was authorized; otherwise contact support with the X-Request-Id. A hold that is never captured or voided is released by the card's bank when it expires. Not the same as payment_outcome_unknown, where the provider accepted the operation.
provider_attestation_failed
HTTP: 403. The payment provider rejected the session-bound attestation token during the charge step. The most common cause is amount or scope drift between session create and complete — the attested amount or scope no longer matches the session. Fix: verify the session amount matches the attestation payload, or create a new session and re-attest. Not safely retriable without investigation when the cause is a scope / integrity mismatch — capture the X-Request-Id before retrying. The specific provider-native reason (e.g. ATTESTATION_EXPIRED, ATTESTATION_INVALID, ATTESTATION_MERCHANT_MISMATCH) is included in the error message so the buyer can be shown a more specific hint in your UI.
provider_charge_failed
HTTP: 402. The upstream payment provider returned a terminal charge failure — card declined, insufficient funds, fraud-rule block, or a network-side decline (issuer, scheme, or processor). Fix: prompt the buyer to try a different payment method. Retrying the same card/session is unlikely to succeed and may trigger additional issuer-side flags. This is distinct from provider_unavailable (transient infrastructure) and transaction_verification_failed (post-charge reconciliation mismatch).
payment_method_not_stored
HTTP: 422. The processor reports that this saved card was never kept on file, so it refused the charge before any money moved. It is not a card decline and not an outage: the same charge is refused the same way now or later, and you cannot repair the card from your side. selfHeal.nextAction is no_action, because the customer must act, not your request.
Do not retry, and do not count it as a decline. Ask the customer to re-enter their card, then charge the new saved card. If many saved cards fail this way, contact support with the X-Request-Id. The refused attempt is recorded as a failed payment intent, named by payment_intent_id on the error. No webhook is sent for it.
recurring_mandate_required
HTTP: 422. An automatic (merchant-initiated) charge on a card issued in India. Such a card can be charged automatically only with a recurring-payment mandate registered during the customer's first payment, and this card has none, so the processor refused the charge before any money moved. It is not a card decline and not an outage: the same automatic charge is refused the same way now or later. selfHeal.nextAction is no_action.
Do not retry automatically. Charge the card while the customer is present, or ask the customer for a different card. If many automatic charges fail this way, contact support with the X-Request-Id. The refused attempt is recorded as a failed payment intent, named by payment_intent_id on the error. No webhook is sent for it. Since 3 November 2026 that payment intent carries decline_code: "recurring_mandate_required" with action: "hard". Payments refused this way before that date carry no decline_code.
The record of a refused charge
When the payment provider refuses a POST /v1/payment_intents before any money moves, the error can carry payment_intent_id: a payment intent with status: "failed" that records the refused attempt. Nothing was charged. It comes only with these five codes: provider_request_rejected, capability_not_supported (a network token the payment connection cannot take), payment_method_not_stored, payment_method_unvaulted and recurring_mandate_required. The field is left out in the rare case the record could not be written.
- Read the record with
GET /v1/payment_intents/{id}. Nocharge.failedorpayment_intent.failedwebhook is sent for it: this response is the notice. - Send a corrected request with a new
Idempotency-Key. Nothing was charged, so a new key cannot charge twice, and the payment provider may refuse a reused key with a different body for 24 hours.
provider_request_rejected
HTTP: 422. The merchant's payment provider rejected the request as invalid before any money movement was attempted — this is neither a card decline (provider_charge_failed, 402) nor a transient outage (provider_unavailable, 502). It is a permanent request-validation failure: retrying the identical body will fail again, and because the buyer's card was never the problem, sending them for a different card fails identically. Inspect the fields a provider most commonly constrains beyond our own schema — currency (must be enabled on the merchant's provider account), amount (within the provider's minimum/maximum for that currency), and any statement-descriptor or metadata values (provider length/character limits) — then retry with corrected values. If every charge on this merchant fails this way, the merchant's provider configuration is likely incomplete; capture the X-Request-Id and escalate. Not retriable as-is.
On POST /v1/public/sessions/{sessionId}/charge (charge at submit) this code has one dominant cause: the provider had no 3-D Secure return target. The hosted challenge needs somewhere to send the buyer back to, which comes from the session's successUrl. Create the session with a successUrl and retry. The card was neither charged nor declined. See Charge at submit → 3-D Secure.
On POST /v1/tokens this code covers provider rejections during vaulting. The 422 is permanent — correct the request rather than retrying.
When no payment connection on your account accepted the charge, the error message says so and selfHeal.nextAction is contact_support. Nothing was charged, and the request body is not the cause. If you changed your account's routing rules, check that this payment can still reach an active connection. Otherwise contact support with the X-Request-Id. The same answer comes back for an Apple Pay or Google Pay payment, or a wallet save, on POST /v1/public/tokens, with no retry block.
payment_method_consent_missing
HTTP: 422. Your server attempted a merchant-initiated charge (mit.initiator: "merchant") against a token whose setup_for_future_use is null or "on_session" — the buyer never consented to off-session reuse.
It is also returned for a customer-initiated charge on a saved card (mit.initiator: "customer") made with no anchor, when the card was saved with no setup_for_future_use at all. For that charge any setup_for_future_use is enough, so the card does not need collecting again: send the charge without an mit block, or name an approved payment on the card. The rest of this section is about merchant-initiated charges.
Consent is write-once: it is recorded at vault time and no endpoint updates it, so retrying with the same token cannot succeed. The card must be collected again, with setup_for_future_use: "off_session" sent on the call that vaults it:
| Your flow | Send it on |
|---|---|
| Embedded fields, charging at submit | POST /v1/public/sessions/{id}/charge |
| Embedded fields, vault without charging | POST /v1/public/tokens |
| Server-to-server, already holding a provider-side card handle | POST /v1/tokens |
POST /v1/tokens is the wrong endpoint for the common case — for a card collected by embedded fields it needs a provider-side handle you don't hold. Use the route that collected the card.
Obtain explicit buyer consent before that call — the consent record must match what the buyer agreed to — then charge the new token normally. retryable: false, nextAction: fix_request.
Full model: Tokenization → reusability.
internal_error
HTTP: 500. Unexpected server error. Capture the X-Request-Id and contact support.
webhook_missing_signature
HTTP: 401. Answered to a payment provider whose call to our inbound webhook endpoint arrived without its signature header — not something your integration receives.
webhook_invalid_signature
HTTP: 401. Two meanings, one code. Raised to you by the server SDK's webhooks.constructEvent / construct_event when your verification of a webhook we sent fails — wrong whsec_* secret (never your API key), body parsed before hashing, or a timestamp outside the window (5 minutes past, 30 seconds future); diagnosis on Troubleshooting. Answered to a payment provider when its call to our inbound endpoint carries a signature that does not match.
webhook_not_configured
HTTP: 503. The verification secret for an inbound provider webhook is not configured on our side — answered to the provider, not to you. Contact support with the X-Request-Id.
webhook_test_delivery_failed
HTTP: 422. A synchronous webhook test-send probe ran but could not reach your subscription endpoint: a transport error or a timeout. selfHeal.retryable is false and nextAction is fix_request (the server SDKs call the same advice fix_input and do not repeat the call). Sending again unchanged usually fails the same way, so check that the subscription URL is correct and reachable from the public internet, then send the test again. Note the distinct outcome: if your endpoint is reached but returns a non-2xx, that comes back as a 200 with delivered: false and the endpoint's response_status, not this code.
origin_forbidden
HTTP: 403. The endpoint is internal and only callable from the hosted checkout page; an external caller hit it directly. If you are building a server-side integration, use the public API (e.g. POST /v1/sessions) instead of the internal checkout endpoints.
transaction_verification_failed
HTTP: 403. Transaction could not be verified with the payment processor. Contact support with the X-Request-Id — this is not safely retriable without investigation (a transaction either exists on the processor or it doesn't).
unsupported_media_type
HTTP: 415. The Content-Type header is missing or not application/json. This check is enforced on the browser-facing public endpoints — POST /v1/public/tokens and the public confirm endpoint — so set Content-Type: application/json when calling them. (A trailing ; charset=… parameter is tolerated.)
request_body_too_large
HTTP: 413. The request body is larger than this endpoint accepts. It was refused before it was read in full, so nothing was created, charged or changed. The response carries the limit as maxBytes. The limit counts the bytes of the body as sent, whatever Content-Length says:
| Endpoint | Limit |
|---|---|
POST /v1/sessions, PATCH /v1/sessions/{id} | 512 KB |
Other secret-key endpoints: /v1/payment_intents and its actions, /v1/refunds, POST /v1/tokens, /v1/buyers, /v1/security_code_sessions, POST /v1/sessions/{id}/expire, /v1/webhook_subscriptions, POST /v1/wallet-domains | 256 KB |
POST /v1/mirror/quote | 64 KB |
POST /v1/public/tokens | 16 KB for a wallet, 4 KB otherwise |
POST /v1/public/sessions/{id}/charge and /complete, POST /v1/sdk-telemetry, POST /v1/public/telemetry/browser | 4 KB |
PATCH /v1/tokens/{id}, POST /v1/public/sessions/{id}/wallet_challenge/cancel, /v1/public/wallets/*, POST /v1/public/security_code_sessions/{id} | 1 KB |
POST /v1/public/binder-load | 256 bytes |
No real request comes close to these limits. If you get this code, look for a bug that makes the body grow: an unbounded list, repeated keys, or an embedded file. Sending the same body again returns the same error. Before 2026-10-24 some of these endpoints answered an oversized body with validation_error.
request_body_timeout
HTTP: 408. Retryable. The request body did not finish arriving before the endpoint's read deadline, so the read was cancelled and nothing was created, charged or changed. The response carries the deadline as timeoutMs: 10 seconds on the browser-facing endpoints (/v1/public/* and the hosted checkout page), 30 seconds on the server-to-server ones. A normal request sends its whole body at once. This code means a stalled connection or a client that streams the body slowly. Send the request again.
endpoint_not_implemented
HTTP: 501. The requested payment-intent operation is not available for this merchant's payment provider. Read client.capabilities.get() and check supportedOperations before invoking optional operations like paymentIntents.capture, paymentIntents.void, or refunds.create with partial amounts. Not retriable — the operation will not succeed without a different capability or provider.
GET /v1/webhook_listen (the live webhook feed that vonpay checkout listen reads) answers it too, at once and with no Retry-After, when the feed is switched off. Retrying will not change it: watch deliveries at your webhook subscription's URL instead (Streaming endpoints).
endpoint_retired
HTTP: 410. Returned by an endpoint that has been permanently retired: today, only the dashboard's former "Create test session" tool, so no public API call returns it. Do not retry it. To run a test payment, create a checkout session with your sandbox account's test keys.
idempotency_replay_incompatible
HTTP: 422. The same Idempotency-Key was sent with a different request body. For payment-intent creation, the server compares the new request against the original on amount, currency, and capture_method; if any of those differ, the replay is rejected to prevent silent state corruption. Either retry with the original values or generate a fresh idempotency key for the new request. On capture, the comparison is on amount_to_capture: leaving it out and sending the full amount count as different.
idempotency_key_required
HTTP: 400. The request carried no Idempotency-Key header where one is required. It has two separate triggers, on two different surfaces, for the same reason — there the header is the only duplicate guard available:
On a refund — it fires only when the payment being refunded was taken on a provider connection whose provider keeps no queryable record of a reversal. On that kind of connection our own record is the only evidence a refund happened, so without the header a repeated call creates a new refund record, a new downstream request, and a second real reversal to the buyer. Every other provider connection still accepts a refund with no key.
On a charge — today it fires on payment routes that keep no queryable record of their own, where our key is the only thing standing between a retry and a second charge to the buyer. From the 28 October 2026 cut-off any keyless charge to POST /v1/payment_intents can be refused with it, before anything is reserved or charged. Until that refusal starts, a keyless charge still succeeds, and its response carries Deprecation: true, Sunset: Wed, 28 Oct 2026 00:00:00 GMT and a Link header pointing at this entry. A Sunset header on your charge responses means that call needs a key. See Idempotency.
Not retryable as sent, on either surface. The identical keyless request fails identically, forever. The header has to be added first.
The fix: send one stable value per logical operation and reuse it verbatim on every retry of that operation. A UUID is fine, as is <order_id>_<operation>. Use a fresh value only for a genuinely different operation — a second, intentional refund of the same payment, or a different charge.
⛔ Do not vary the key to get past an error. Adding a key satisfies this code; changing one between retries is what causes the duplicate both triggers exist to prevent. If you are already sending a key and getting a 409 charge_in_progress, the answer is not a new key. Send a key on every connection and every route, not just where it is enforced — see Refunds.
invalid_transition
HTTP: 409. The payment intent is in a state that forbids the requested operation — e.g., trying to capture an intent that's already succeeded, or void one that's already voided. The error envelope carries current_status (the intent's actual state) + reject_reason — a discriminator the SDK exposes as currentStatus / rejectReason — so you can branch without a follow-up retrieve.
reject_reason takes one of five values:
| Value | What it means |
|---|---|
intent_not_found | No intent with that id for this account |
terminal_state | The intent is in a state the operation cannot act on |
invalid_transition | The operation is not legal from the current state |
concurrent_update | Another capture or void is in flight for this intent right now |
lookup_failed | The intent could not be read to decide |
concurrent_update is the one to add a branch for — it is how you detect a race between two operations on the same payment. Treat it as "unknown outcome, retry the read", never as a terminal state: a payment still in flight read as terminal is how a live payment gets cancelled or refunded. A value the server SDK does not recognise arrives as rejectReason: undefined — treat that the same way. For the others, read current_status: if it is final (succeeded, captured, voided, failed), stop and fix the request (for example refund instead of void once the intent has captured). If it is not final yet, retry the same request with the same Idempotency-Key later: on capture and void this error is never stored as the key's answer, so the retry checks again.
operation_in_flight
HTTP: 409. An earlier capture or void with the same Idempotency-Key on this payment intent is still being processed. This request sent nothing and changed nothing. Retry the same request with the same key in a few seconds; you then get the first request's answer. Do not switch to a new key. If it persists for more than about a minute, read the payment intent.
capture_amount_exceeds_authorized
HTTP: 422. The amount_to_capture you sent is larger than the amount authorized on this payment intent. Nothing was captured.
You can capture less than was authorized — that is a partial capture and it is supported. You cannot capture more.
Decide the amount before you capture: a partial capture is final on that intent. There is no incremental capture. Capturing less moves the intent straight to succeeded with amount set to what you took, and any further capture on it is rejected as invalid_transition — the difference can only be collected as a new charge. If the final amount is not known yet, capture once you know it.
The error response carries authorized_amount, so you can re-issue immediately with amount_to_capture at or below that figure — or omit the field entirely to capture the full authorized amount. Not retriable unchanged; fix the amount first.
refund_intent_not_refundable
HTTP: 422. The payment intent named in payment_intent is not in a refundable state: refunds require the parent intent to have status: "succeeded". An intent in requires_action / authorized / captured / failed / voided / cancelled cannot be refunded: call /capture or /void instead, or, if the intent failed or was cancelled, no refund applies because no money moved. Check the parent intent's current status before retrying. Not retryable as-is.
The same code refuses a refund on a payment whose settlement records a dispute or chargeback, with current_status reading disputed or chargeback even though the intent itself reads succeeded. The buyer gets the money back through the dispute, so do not refund it another way.
refund_amount_exceeds_remaining
HTTP: 422. The requested refund amount is greater than what's left to refund on this intent. The error envelope carries remaining_refundable (the captured amount minus what's already been refunded) so the SDK / agent can re-request with a valid amount, or you can omit amount to refund the full remaining balance. Fix the input and retry.
refund_before_settlement
HTTP: 422. The payment has not settled yet, so there is nothing to send back and the provider refuses the refund. No money moved and the buyer was not refunded.
Wait for settlement, usually the provider's overnight batch however long ago the capture succeeded, then send the refund again with a new Idempotency-Key. Before you send it, list the payment's refunds with GET /v1/refunds: if one is already requested or succeeded, do not send another. The refused request is recorded as a failed refund, so no refundable balance was consumed, and its key is spent: sending it again with the same key returns 200 with idempotent: true and status: "failed", and never refunds. Retrying immediately, with any key, fails identically.
- Do not treat it as a completed refund — nothing was refunded.
- Do not void or cancel the payment as a workaround. Any payment that can reach this error has been captured, so the cancel call rejects it with
invalid_transition.
refund_target_is_duplicate
HTTP: 422. The transaction you named is a duplicate record of a payment that is recorded under a different transaction, so refunding it would not reverse the payment the buyer actually made. The response names the transaction to use instead in refund_instead. Refund that one. Not retryable as-is; retrying with the same transaction fails the same way.
refund_target_not_refundable
HTTP: 422. The transaction you named cannot be refunded through the API. This is a property of that payment, not of your request, so a retry will not change it. Contact support with the transaction id; do not refund the buyer another way first, or you risk paying them twice.
refund_currency_mismatch
HTTP: 422. The currency in the refund request differs from the parent intent's currency. Refunds always settle in the original capture currency — either drop the currency field (it defaults to the intent's currency) or supply the matching ISO-4217 code. Fix the input and retry.
refund_declined
HTTP: 422. No money moved and the buyer was not refunded. The provider accepted the request and then resolved it to a terminal failure without raising an error — a synchronous decline.
Read this as the refund did not happen, not as "the refund is pending". The refund is recorded as failed, so the intent's refundable balance is untouched.
Read error first. If it says the payment was disputed, the buyer's bank has already returned the money through the chargeback. Do not retry, and do not refund the buyer any other way: they would be paid twice. Otherwise a corrected retry is possible once the cause below is fixed: send it with a new Idempotency-Key, because this request's key is spent (a retry with the same key returns the stored failed refund with 200 and never reaches the provider).
The same code is returned when the provider refuses the refund request outright as invalid; the error message then says the provider "refused this refund request". This request issued no new refund, and sending it again is refused the same way. An earlier attempt at the same refund may still have gone through, so list the payment's refunds with GET /v1/refunds before you refund the buyer any other way.
Common causes, in the order worth checking: the processor sub-account has insufficient balance to fund the refund; the original card is closed; or a fraud or compliance hold is blocking refunds. All three are gateway-side — retrying the same call unchanged will decline again. Resolve the cause on the gateway account first, list the payment's refunds, then send the refund again with a new key.
buyer_required_for_saved_card
HTTP: 422. Nothing was charged. This session's provider vaults the card as part of taking the payment, and a vaulted card has to be saved against a buyer — but this session has no buyer attached.
Retrying cannot succeed. The buyer is fixed when the session is created and cannot be added afterwards, so the same call will fail the same way however many times you send it. Create a new session with buyerId set, and have the buyer enter the card again.
In the browser SDK this arrives as a thrown frame_buyer_required_for_saved_card: your submit() rejects. Do not confuse it with frame_consent_requires_buyer (vora.js 1.43.x and earlier, no longer raised from 1.44.0), the same missing buyer on a gateway that charges anyway: that one never throws and the buyer has been charged. Read result.token to know whether the card was saved. Branch on the code: see the two codes and Recurring & saved cards.
payment_method_required
HTTP: 422. This merchant's payment provider requires a previously-vaulted payment method on every charge, but the request omitted one. Use the two-step flow: (1) POST /v1/tokens with the buyer's payment data to vault it, then (2) POST /v1/payment_intents with payment_method: { id: <vp_pmt_*> }. Some providers also support a browser-side confirmation flow (omit payment_method, then confirm in the buyer's browser) — call GET /v1/capabilities to see whether the merchant's current provider supports that path. Not retriable as-is.
payment_method_not_found
HTTP: 404. The payment_method.id is unknown to this merchant. Verify the id was not truncated, that it was created against the same merchant whose API key you're using, and that the test/live mode matches the key prefix. Payment-method ids are scoped to the merchant; you cannot reference another merchant's token. Not retriable as-is — fix the id and retry.
It is also returned for a card saved single-use (no setup_for_future_use) with no buyer identified, once it is more than 24 hours old: such a card can only be charged in the window right after it was saved. To charge a card again later, save it with setup_for_future_use on a session that identifies the buyer (buyerId, buyerEmail or buyer).
On DELETE /v1/tokens/{id} with a buyer_id, it is also returned when the card exists but was not saved for that customer. The answer is deliberately the same as for an unknown id, so it never reveals whose card it is.
security_code_session_not_found
HTTP: 404. A charge sent a security_code_session that is unknown, belongs to another account or mode, or was opened for a different payment_method than the one being charged. Nothing was charged. A session is opened for one saved card and can only charge that card: send the session your server opened for this payment_method. See Re-enter a saved card's security code.
security_code_session_expired
HTTP: 410. The security code session was already used by a charge, or is older than 15 minutes. Nothing was charged. Each session pays for one charge attempt whatever the outcome, so do not retry with it: open a new one with POST /v1/security_code_sessions and ask the buyer for the code again.
security_code_not_collected
HTTP: 422. The charge named a security code session for which the browser SDK has not yet confirmed a valid code: the buyer has not submitted it, or the page runs a vora.js older than 1.40.2, which does not send that confirmation. The code may also have been entered for a different saved card. Nothing was charged, and the session is not used up: once the field's submit() resolves, send the same request again, for the card the session was opened for. This check is reported by the buyer's browser and is not a fraud control; see security_code_verification: "strict".
security_code_not_verified
HTTP: 402. The charge used security_code_verification: "strict" and the card issuer did not report a security-code match (mismatch, not received, not verified, or no result). Nothing was charged. The card authorization is released; the response carries payment_intent (id, status) and cvv_result_code. If payment_intent.status reads authorized, the release is still being retried automatically: do not capture or void it yourself. Open a new security code session and ask the buyer to enter the code again. A payment connection that never returns a security-code result refuses every strict charge, so leave the field off there.
security_code_check_in_progress
HTTP: 409. A capture or void on a strict security-code payment whose check is still being finished. The payment is captured or released automatically. This request changed nothing; retry shortly if you still need it.
mit_anchor_unknown
HTTP: 422. A merchant-initiated charge of a saved card left out mit.original_transaction_id, and the card has no approved customer-present payment to link it to. Where available on your account, an approved $0 card check counts instead, but only one made for the same use: its card_check.stored_credential_use must equal mit.reason. Nothing was charged. Send mit.original_transaction_id, or take a customer-present payment with the card first. Retrying unchanged fails the same way.
saved_card_buyer_required
HTTP: 422. A request asked to save a card for later use but identified no buyer, so the card would have no owner. POST /v1/sessions returns it for the embedded card form (integrationMode: "embed") when the session declares a save (setupForFutureUse, storedCredentialUse, or mode: "setup" with a buyer email) or asks for the saved-card list, with no buyerId (or buyer.externalId): an email alone cannot name the customer there. Send buyerId, use integrationMode: "elements", or omit the save. The check on POST /v1/tokens, and on saving a card without charging it through POST /v1/public/tokens, is off by default; when it is on, it is returned only where nothing is being charged. Nothing was charged and nothing was saved. Where the buyer is charged and the card saved in the same step, the payment is never refused for this: the card is saved for that payment only and setup_for_future_use comes back null.
Identify the buyer: buyerId, buyerEmail or a buyer object on POST /v1/sessions (then collect the card again on that session), or buyer_id / buyer on POST /v1/tokens. If the card is only for this payment, omit setup_for_future_use.
required_fields_missing
HTTP: 422. A card payment (POST /v1/public/sessions/{id}/charge) was missing buyer details your account requires, so the buyer was not charged (charged: false). This check is off by default; when on, it applies to every card payment. missing_fields lists required fields never supplied and invalid_fields lists supplied values that are unusable, such as a phone number with too few digits. Field names are name, email, phone, shipping_address and billing_address.
The requirements are your dashboard's buyer-field settings, fixed onto the session when it was created, and the details are read from the session. Set them at create (buyerName, buyerEmail, and buyerContact for phone and addresses, secret key only), or create a new session with them. A billing address may also be sent on the payment as billing_address. A required billing address must be complete: street, postal code, city, country, and the state where the country has states or provinces. A partial one is refused as missing. Not retryable as sent.
buyer_not_found
HTTP: 404. The buyer id on GET /v1/buyers/{id} or PATCH /v1/buyers/{id} is unknown to this merchant. The response is opaque — the same body whether the id is missing, belongs to a different merchant, or its test/live mode doesn't match the key (buyer ids are mode-prefixed vp_by_test_* / vp_by_live_*) — so buyer ids cannot be probed across merchants or modes. To find a buyer by your own reference, use GET /v1/buyers?external_id= or ?email=. See Buyers.
buyer_email_conflict
HTTP: 409. One email may belong to several of your buyers (since 9 November 2026), so this code is narrow. It is returned in two cases. A PATCH /v1/buyers/{id} on a buyer with no external_id set an email that another buyer with no external_id, in the same mode, already has (there is at most one such buyer per email): update that buyer instead, or give the buyers external_ids. Or a subscription sign-up with no buyer_id used an email that belongs to one of your customers with an external_id: nothing was charged; send that customer's buyer_id. Nothing was changed in either case, and the same request gets the same answer. POST /v1/buyers no longer returns this code: an external_id no buyer has yet always creates a new buyer. See Buyers.
buyer_reference_conflict
HTTP: 409. A POST /v1/buyers used an external_id that already belongs to a buyer created with your key for the other mode (test vs live). Buyer records never cross modes, and an external_id is unique per merchant across both, so this key can neither create nor update a buyer with it. Nothing was changed. Not retryable: the same request gets the same answer. Use the key for the mode that buyer was created in, or give the buyer in this mode a different external_id (for example, a test_ prefix on test data). On POST /v1/sessions, POST /v1/payment_intents and POST /v1/tokens the same conflict does not fail the request: it succeeds without a buyer linked. See Buyers.
buyer_update_conflict
HTTP: 409, from PATCH /v1/buyers/{id}, and from POST /v1/buyers for a buyer that already exists. The update merges your metadata keys into the buyer's stored metadata without overwriting keys another request added in the meantime. Other updates to the same buyer kept landing while this one was applied, so nothing was changed: no metadata key and no other field. Retryable: send the same request again after a moment. If you update one buyer from several places, send the updates one after another rather than in parallel. See Buyer metadata merges.
service_unavailable
HTTP: 503. The endpoint is temporarily unavailable. Retriable — back off exponentially and retry. Distinct from provider_unavailable (the payment provider is unreachable) and auth_service_unavailable (the key-verification service is down); this one covers the endpoint itself.
On a refund, capture or void whose message says the payment account could not be confirmed, nothing was recorded and no money moved. Retry with the same Idempotency-Key.
On POST /v1/payment_intents: a check we run before charging could not complete, so nothing was sent to your payment provider and this request charged nothing. Retry shortly with the same request and the same Idempotency-Key; selfHeal.retryable is true.
If the message says we could not check your Idempotency-Key, an earlier request with the same key may already have charged the buyer. Do not mark the order unpaid. The retry returns that earlier payment if one completed, and this request's real answer if none did. If it says we could not verify the retry against the original payment, that original payment stands. In both cases a new key is the one action that can charge the buyer twice.
Branch on the code, not the class: charge_reservation_unavailable (503) means nothing happened, a 409 charge_in_progress means something already did, and a 400 idempotency_key_required means add a key. Never vary a key.
feature_unavailable
HTTP: 503. The capability you called is switched off. This is a deliberate configuration, not an outage — retrying the same call will keep returning this response, however long you back off. Branch on it:
service_unavailable(503) means try again shortly — the endpoint is briefly down.feature_unavailable(503) means stop trying — the capability is off and will stay off until it is turned on.endpoint_not_implemented(501) means the operation does not exist for your payment provider at all.
Fall back to your asynchronous path: reconcile the outcome from your webhook rather than looping on the call. The response is not a failed payment — it is a refusal to answer synchronously.
It is returned by the public guest-completion endpoint (POST /v1/public/sessions/{id}/complete). The check runs before your key is authenticated, so a valid publishable key still sees it; it is not a credentials problem.
rate_limit_service_unavailable
HTTP: 503. The rate-limiting service is temporarily unavailable, so the request could not be admitted. Retriable in a few seconds. Not the same as rate_limit_exceeded (429) — you have not exceeded anything, the limiter simply could not answer.
charge_at_submit_not_enabled
HTTP: 422. The session is not eligible for Embedded Fields charge-at-submit. Vault the card with POST /v1/public/tokens and charge server-side with POST /v1/payment_intents instead. Distinct from endpoint_not_implemented (501), which means the capability is off platform-wide or for your gateway rather than wrong for this particular session.
validation_url_scheme_forbidden
HTTP: 400. A successUrl or cancelUrl used a scheme or host that live mode does not allow. Live mode requires HTTPS on a public host; localhost is accepted in test mode only. Fix the URL and retry.
webhook_subscription_not_found
HTTP: 404. The webhook-subscription id is unknown to this merchant. Check the id format and that it belongs to your account — subscription ids are merchant-scoped, so another merchant's id reads as missing rather than forbidden.
webhook_subscription_conflict
HTTP: 409. A webhook subscription already exists for this URL. Update or delete the existing one rather than creating a duplicate — list your subscriptions with GET /v1/webhook_subscriptions to find it.
webhook_subscription_url_immutable
HTTP: 400. A PATCH /v1/webhook_subscriptions/{id} included url. A subscription's delivery URL is fixed once it is created, and nothing was changed by this request. Not retryable as sent.
To deliver to a new URL, create a new subscription for it. It gets a new signing secret: store it and verify deliveries with it. Confirm the new subscription receives events, then delete the old one. To change only the event list, description or status, send the update without url; that keeps the existing URL and signing secret.
unexpected_redirect
Raised by the server SDKs, never sent by the API (Node and Python 3.0.0 and later). The API answered with a redirect, which it never does, so something else is answering: a proxy, a mistyped base URL, or a hijacked connection. The SDK does not follow it. retryable is false and nextAction is check_configuration. Do not retry: check that the SDK's base URL is https://checkout.vonpay.com with no path, then any proxy and the network.
webhook_event_not_found
HTTP: 404. The webhook-event id is unknown, or belongs to a session your account does not own. Same merchant-scoping rule as subscriptions above.
wallet_domain_not_found
HTTP: 404. The wallet-domain id is not registered to this merchant, or has been removed.
wallet_domain_invalid
HTTP: 422. The request body failed validation. Two things can trigger it, and the message does not distinguish them: the domain was not a bare RFC 1123 hostname (letters, digits, hyphens and dots, 253 characters max — no scheme, no path, no port, no IP literal), or wallet_type was something other than apple_pay / google_pay. Check both before assuming it is the hostname.
wallet_domain_wrong_type
HTTP: 404. You asked for the verification file on a Google Pay row. Only Apple Pay registrations host a verification file (How domain entries work).
wallet_domain_no_binder
HTTP: 409. The account has no active wallet-capable payment gateway, so there is nothing to register a domain against. Complete merchant onboarding first.
wallet_domain_rate_limited
HTTP: 429. Over the check limit for that domain and wallet. Poll GET /v1/wallet-domains/{id} for status instead of calling verify repeatedly.
wallet_domain_provider_unavailable
HTTP: 503. The upstream provider that performs domain registration is temporarily unreachable. Retriable with exponential backoff.
wallet_session_refused
HTTP: 422, from POST /v1/public/wallets/apple-session or POST /v1/public/wallets/google-session. The payment provider refused to start the Apple Pay or Google Pay session for this page, so the wallet sheet cannot open. The usual cause is a domain that is not registered, or not yet verified, for wallet payments. Not an outage, and retrying will not change it. In the browser, vora.js 1.44.0 and later report it as frame_wallet_unavailable.
Hide the wallet button for this page and let the buyer pay by card. Then check the domain with GET /v1/wallet-domains, add it with POST /v1/wallet-domains (see How domain entries work), and check that wallet payments are enabled for the account. If the domain is registered and verified and this persists, contact support with the X-Request-Id.
wallet_not_saved
HTTP: 422, from an Apple Pay or Google Pay save on POST /v1/public/tokens (a session that saves without charging). The payment provider did not approve the zero-amount check, or approved it and stored nothing. Nothing was charged and nothing was saved. In the browser, vora.js 1.44.0 and later report it as frame_wallet_unavailable.
Do not resend the same request: it carries a single-use wallet token. Ask the buyer to tap the wallet button again, or to pay by card. If every wallet save on the account fails this way, the account is probably not set up to save wallets: contact support with the X-Request-Id.
Also from an Apple Pay or Google Pay charge that asked to save the card, when the merchant's payment connection refuses to save a wallet. The payment is then sent once more without saving, and this code means that attempt was refused too. Nothing was charged or saved, and the buyer's next tap pays without saving: ask them to tap again. When the second attempt goes through, the tap is charged without saving (charged: true, id and token null).
report_too_large
HTTP: 422, from the payment reports: GET /v1/payment_intents and GET /v1/payment_intents/summary. The request is valid but too big. One field says why:
timeout_ms: the request took longer than the limit, 5,000 ms for the list or 8,000 ms for the summary. Use a shorter window, or add filters such asoutcomeorcurrency.max_groups(summary only): the answer would have more than 2,000 groups. Group by fewer dimensions or a coarser time unit, or add filters.
Do not send the same request again: it is not retryable unchanged (selfHeal.retryable is false).
url_not_fetchable
HTTP: 422, from the Match my site tab of the style playground in these docs. The page at the URL you entered cannot be used, and a retry will not change that: the site answered with a client error (for example 403 or 404), redirected to an address that is not allowed, redirected without a target or more than three times, or returned more than the size limit. The error message names the reason. Use another public page that opens in a browser without signing in, or paste your stylesheet instead. A timeout, a network error, or the site answering 408, 429 or a 5xx is a retryable 502.
mirror_settle_only_disabled
HTTP: 400. mirror.settle_only was refused before the card was charged — the buyer was not charged. Either send the standard upsell instead (parent_order_ref with the add-on's line_items), or see Settle-only for the conditions a settle-only request has to meet.
The next three codes come from the check Von Payments makes before a settle-only charge: it reads the order named in parent_order_ref from your connected store. Each response carries what the store reported:
| Field | Value |
|---|---|
reason | Why, as a fixed value. The values are listed under each code |
charge_amount, charge_currency | What your request asked to charge |
order_balance | The order's unpaid balance, in minor units of order_currency. null when the store could not be read |
order_balance_raw | The store's own figure for that balance, as the store sent it |
order_currency | The order's currency. null when unknown |
order_status, payment_status | The store's own status words, for example cancelled or refunded. Treat them as open text |
mirror_settle_only_order_not_payable
HTTP: 409, from POST /v1/payment_intents with mirror.settle_only. The store order cannot take a payment. The buyer was not charged.
reason | The store order |
|---|---|
order_cancelled | is cancelled |
order_refunded | is refunded, in full or in part |
order_is_test | is a test order, which is never marked paid |
nothing_outstanding | has nothing left to pay |
Do not charge for this order. A cancelled or refunded order cannot record the add-on, so offer it on a new order. If the balance is zero because your own line-add has not reached the order yet, add the item first. Then send the same request again. Do not use a new Idempotency-Key to get past this code.
mirror_settle_only_amount_mismatch
HTTP: 400, from POST /v1/payment_intents with mirror.settle_only. The store marks the whole unpaid balance paid, so it cannot record a payment of a different amount. The buyer was not charged.
reason: "amount_mismatch": the order's unpaid balance is not youramount. Chargeorder_balanceinstead.reason: "currency_mismatch": the order is inorder_currency, not in yourcurrency.
If the store wants up to 2 minor units less than your amount, you do not get this code. Von Payments charges the store's balance, and the payment carries that amount. A store that wants more is always refused.
If the balance covers more than this add-on (for example, two add-ons added before either was paid), charge each add-on right after you add it. Or charge the combined balance once.
mirror_settle_only_unverifiable
HTTP: 503, from POST /v1/payment_intents with mirror.settle_only. Retryable. Von Payments could not confirm the order's unpaid balance, so it did not charge. This is not a verdict on your amount. The buyer was not charged.
reason | What happened |
|---|---|
store_unavailable | The store did not answer in time, was throttling, or returned an error |
not_connected | The store connection could not be used for this read |
currency_unknown, balance_unreadable | The store did not report a readable balance and currency |
settle_in_progress | Another payment for the same order is still being recorded on it |
Send the same request again shortly. The same Idempotency-Key is safe, because nothing was created. For settle_in_progress, charge the add-ons for one order one at a time. If the code keeps coming back, check the store connection in your dashboard.
Order-before-charge refusals (order_first_*)
These apply when your account creates the order in the connected store before the card is charged. All eleven refuse before any money moves — on every one of them, the buyer was not charged.
They divide into three responses, and the difference matters:
| Response | Codes |
|---|---|
| Retry with the identical body | order_first_lookup_unavailable, order_first_record_unavailable, order_first_repoint_unavailable, order_first_store_timeout, order_first_store_unavailable |
| Fix the request, then resend | order_first_order_rejected, order_first_amount_mismatch, order_first_currency_mismatch |
| Contact support | order_first_unsupported_destination |
| Do not retry: an earlier payment for this purchase exists | order_first_already_paid, order_first_payment_unresolved |
On order_first_store_timeout and order_first_store_unavailable the store may have created the order already — it simply never told us. An unconfirmed attempt is matched by the purchase (buyer, line items, quantities, prices, voucher): an identical retry adopts that order, a retry with any of those changed creates a second one. If the basket has to change, treat it as a new purchase — the abandoned order is released automatically when no payment completes.
order_first_lookup_unavailable
HTTP: 503. Our record of earlier attempts for this purchase could not be read, so the request was refused rather than risk a duplicate order. Retry the identical body after ~3s.
order_first_record_unavailable
HTTP: 503. The durable record written before contacting the store could not be written, so the request was refused. Retry the identical body after ~3s.
order_first_repoint_unavailable
HTTP: 503. This is a retry, an order for it already stands in your store, and the link from that order to this attempt could not be written. The existing order is untouched and is released automatically if no payment completes. Retry the identical body after ~3s.
order_first_store_timeout
HTTP: 503. The store did not answer in time while creating the order, so the charge was refused rather than billed against an order Von could not confirm. The order may exist. Retry the identical basket after ~5s — see the warning above.
order_first_store_unavailable
HTTP: 503. The store was throttling or temporarily unavailable. It did not reject the order's contents, so there is nothing to correct in your request. The order may exist. Retry the identical basket after ~10s — see the warning above. If it persists for several minutes the store is likely rate-limiting a burst: reduce concurrency rather than retrying harder.
order_first_order_rejected
HTTP: 400. The store refused the order outright, so nothing was created. This is a store-side validation failure about the order's contents — usually a product or variant reference that does not exist in that store, a quantity it will not accept, or a malformed price. It is not a discount problem. Reconcile your line_items against the store's catalogue and resend; an identical retry is rejected identically.
Also returned when the store created the order but reports nothing left to pay on it (already paid, or fully covered by a discount). Nothing was charged and the order is not cancelled. Do not retry; check the order in your store.
order_first_amount_mismatch
HTTP: 400. The store created the order and priced it at a total that does not equal the amount you are charging, so Von refused rather than record a payment that does not match the order. Charge the order_total returned on this error — the store's number is authoritative. The order is left standing, so a corrected retry attaches to it instead of creating a second one.
⚠️ Do not call POST /v1/mirror/quote to resolve this. Quote prices a cart; order-before-charge exists precisely because a store's cart total and its order total can disagree — a standing site-wide offer can apply to one and not the other.
order_first_currency_mismatch
HTTP: 400. The store priced the order in a different currency than the one being charged. Charge in the currency named by order_currency on this error, or reconfigure the store to price in your intended currency.
This is deliberately separate from an amount mismatch because the numbers can be identical while the money is not — a ¥1000 order and a $10.00 charge are both 1000 in minor units.
order_first_already_paid
HTTP: 409. A new charge arrived for the same purchase (same buyer, items and store) as an earlier payment that already went through, while the store order is still open (usually because marking it paid had not finished). This request did not charge the buyer. The response carries original_payment_intent_id, the earlier payment, whenever it can be read, and the earlier payment is recorded on the store order automatically.
Not retryable. Do not retry with a new Idempotency-Key, a different card or a changed basket: each of those charges the buyer a second time for something already paid. Treat the purchase as paid, read GET /v1/payment_intents/{original_payment_intent_id} and show the buyer their confirmation. If the buyer genuinely wants the same items again, contact support.
order_first_payment_unresolved
HTTP: 409. A new charge arrived for the same purchase as an earlier payment that has not finished (for example, the buyer is still completing a bank check) or whose result has not been confirmed. If that earlier payment goes through, a second charge would bill the buyer twice, so this one was refused. This request did not charge the buyer. original_payment_intent_id is included when the earlier payment has a record, and omitted (not null) when it does not yet.
Not retryable as is. When original_payment_intent_id is present, read it: succeeded means the purchase is paid; failed means the same basket can be retried. Do not get past this with a new key, card or basket. If it persists beyond a few minutes, contact support so the earlier payment can be resolved.
order_first_unsupported_destination
HTTP: 503. Your account is configured for order-before-charge, but the platform named in mirror.destination cannot create an order ahead of the charge, and there is no fallback to charge-first. Not retryable — a configuration mismatch on our side. Contact support.
Decline reasons (failure_code)
A declined charge surfaces two ways:
- Synchronously — the API returns
402provider_charge_failedon the charge routes. ⚠ A declinedPOST /v1/payment_intentsis different: it returns201withstatus: "failed", not a4xx— see A decline is a 201. A client that only reads the body on an error status never sees the decline fields at all. - Asynchronously — a
charge.failedorpayment_intent.failedwebhook fires, carrying seven fields (allstring | null):failure_code— the normalized decline reason to branch on.decline_code— the same value under the API response's name. See the two names.action—soft/hard/fix_and_retry/generic, the retry classification.decline_message— buyer-safe wording for this decline. See Showing a decline to the buyer.failure_reason— a human-readable summary of the decline, written for you, not your buyer. See Whofailure_reasonis for.network_decline_code— the raw issuer code (e.g.05,51); for logging/analytics only.rule_code— which of your own rules refused it, when one did.nullon every other outcome. See Telling your rules apart.
The same value under two names
The normalized decline arrives as failure_code and decline_code on every failed-family webhook payload — the same value under both names, so one handler can read the webhook and the API response by the same key. It is normalized to a fixed vocabulary; the full set and recommended handling follow. Every decline also carries action (soft / hard / fix_and_retry / generic), derived from the same mapping on both surfaces — branch on that for retry or dunning logic rather than maintaining the column yourself.
failure_code | action | Meaning | Retry the same card? | Recommended next step |
|---|---|---|---|---|
card_declined | generic | Declined with no further detail supplied. | Unlikely to help | Prompt for a different payment method. |
insufficient_funds | soft | The card lacks available funds. | Not now | Suggest a different card; the same card may succeed later. |
expired_card | fix_and_retry | The card has passed its expiry date. | No | Ask the buyer to re-enter a valid card. |
incorrect_cvc | fix_and_retry | The CVC/security code was wrong. | Only after correction | Ask the buyer to re-enter the security code. Retrying the same value fails identically. |
incorrect_zip | fix_and_retry | The billing postal code did not match. | Only after correction | Ask the buyer to re-enter the billing ZIP/postal code. Retrying the same value fails identically. |
incorrect_number | fix_and_retry | The card number is wrong, usually mistyped. Since 2 November 2026; earlier declines of this kind read generic_decline and were not relabelled. | Only after correction | Ask the buyer to check the number on the card, or to use a different card. |
card_velocity_exceeded | soft | The card hit an issuer velocity limit. | Not now | Suggest a different card or trying again later. |
fraudulent | hard | The issuer or a fraud rule blocked the charge. | No | Show a generic decline message — do not reveal the fraud signal. Suggest a different method or contacting the issuer. |
stolen_card | hard | The card was reported stolen. | No | Show a generic decline message; suggest a different method. |
lost_card | hard | The card was reported lost. | No | Show a generic decline message; suggest a different method. |
do_not_honor | soft | The issuer declined without a specific reason. | Not now | Suggest a different card. The same card may succeed on a later attempt, spaced out over days. |
issuer_unavailable | soft | The issuer could not be reached. | Not now | The same card may succeed on a later attempt, spaced out over days. Offer a different card meanwhile. |
processing_error | soft | The card processor could not process the payment, and no bank refused the card. Since 10 November 2026; earlier ones read generic_decline. | Yes, a little later | Do not ask for a different card. First read the payment with GET /v1/payment_intents/{id}, and retry only while it still reads failed: a processing error does not prove that no money moved. Send the retry with a new Idempotency-Key. On a checkout session, see payment_under_review. |
blocked_by_rule | hard | A rule you configured on your own account refused the charge. No issuer was asked. | No | Prompt for a different payment method. Do not suggest contacting the bank — no bank saw this charge. |
authentication_not_completed | soft | The buyer was sent to their bank's 3-D Secure check and did not finish it (closed the page, or ran out of time). Nobody declined the payment and nothing was charged. Since 2026-10-12. Earlier payments arrived as generic_decline or with no reason; those that read generic_decline were updated to it by a one-off correction in October 2026, without re-sent webhooks. | Yes, once the buyer completes the check | Offer another try; suggest a different method only if they cannot complete the check. A check that did not pass is authentication_failed; a bank that refused the payment and asked for the check is still a decline. |
authentication_failed | soft | The buyer went through their bank's 3-D Secure check and it did not pass, including when the buyer cancelled it on the bank's page. Usually no charge was sent. If the bank approved the payment even though the check did not pass, Von Payments does not keep that approval: the payment is reported failed with this code, and any amount held is released or any amount taken is refunded automatically. A charge.refunded event with reason: abandoned_payment_reversed then follows the charge.failed. Since 2026-10-22; earlier payments, reported as generic_decline (or do_not_honor where the payment processor ran the check), were updated to authentication_failed on 2026-10-23, and webhooks already delivered for them were not re-sent. | Yes, usually on a new checkout session | Let the buyer try again or use a different payment method. A failed check ends the checkout session, so the next try needs a new one. |
recurring_mandate_required | hard | An automatic charge on a card issued in India with no recurring-payment mandate. No bank refused it and nothing was charged. Only on the failed payment intent that a recurring_mandate_required refusal records, since 3 November 2026; no webhook is sent for that payment. | No | Charge the card while the customer is present, or ask for a different card. |
generic_decline | generic | An unmapped or unrecognized raw decline. | Unlikely to help | Prompt for a different payment method. |
An unmapped raw code is normalized to generic_decline before it reaches you, so a webhook always carries one of the values above.
On some connections the failure webhook for a checkout-session payment (hosted page, embedded card form or wallet) carries do_not_honor for a check that did not pass. The payment is corrected to authentication_failed seconds later and the webhook is not sent again, so the value on GET /v1/payment_intents/{id} is the final one.
Retrying a soft decline counts against the card networks' limits on repeat attempts: see card network retry limits.
Who failure_reason is for
failure_reason is written for you, not your buyer. It is the most informative single string we return about why a charge failed — put it in your logs and your support tooling.
Three of its values state that a card is reported lost or stolen, or that fraud is suspected. Present those to a buyer as an ordinary decline, exactly as you would generic_decline:
failure_code | What failure_reason says | What the buyer should see |
|---|---|---|
fraudulent | "The payment was declined as suspected fraud." | A generic decline |
stolen_card | "The card was reported stolen." | A generic decline |
lost_card | "The card was reported lost." | A generic decline |
fraudulent is a risk score, not a finding. network_decline_code stays out of buyer-facing copy entirely — it is for logging and analytics.
Showing a decline to the buyer
decline_message is the field written for your buyer. It accompanies the decline on the charge response and on the failed-family webhooks, and it is the one you can render or put in a dunning email without leaking a fraud signal.
Show decline_message; log failure_reason. They are not the same string and should not be collapsed into one. Where failure_reason names a fraud, lost or stolen signal, decline_message gives all of those the ordinary decline wording — byte for byte identical to card_declined and generic_decline — so the five cannot be told apart:
The card was declined. Please use a different payment method.
On a successful charge the decline fields are not there to read: the API response returns them explicitly null, and the success webhooks (charge.succeeded and its siblings) omit the keys entirely — so decline_code === null is true on one surface and false on the other. Test that the charge actually failed before rendering decline_message; printing it unconditionally shows a decline to a buyer who just paid.
Codes the buyer can actually act on keep their own wording: insufficient_funds, expired_card, incorrect_cvc, incorrect_zip and incorrect_number each name what to fix, because a generic string there costs a sale the buyer was willing to complete.
Decline reasons in the browser
A decline reported to the browser, by the embedded card form or the hosted checkout page, uses a smaller set of codes. It never says which card detail was wrong, or that the card was flagged. One exception: a rule of yours that refuses a card brand outright is reported as card_brand_not_accepted, naming the brand only (since 15 November 2026):
Server decline_code | Browser code |
|---|---|
incorrect_cvc, incorrect_zip, expired_card, incorrect_number | incorrect_card_details |
fraudulent, stolen_card, lost_card, blocked_by_rule (except a card-brand rule: card_brand_not_accepted), recurring_mandate_required | card_declined |
| Any other code | Unchanged |
The exact reason still reaches your server on the charge.failed webhook and on secret-key responses.
On an elements session that charges at submit, frame_payment_declined carries the browser code on error.declineCode (vora.js 1.42.0 and later). Branch on that field, never on error.message: the message names no code. A declined card reads "The payment was declined.", and incorrect_card_details adds "Check the card details, or use a different card." From vora.js 1.39.0 to 1.43.2 the message also put the code in brackets. declineCode is absent on a wallet payment, a card save and the default embed mode, which never names a decline code. Read the exact reason on your server.
Two values are not declines, and nothing was charged:
authentication_not_completed: the buyer did not finish their bank's security check (3-D Secure). The same card can work: let the buyer try it again, on this session whenerror.retryableistrue, otherwise on a new session.authentication_failed: the bank's security check did not pass, often because the buyer cancelled it. The checkout session usually ends: whenerror.retryableisfalse, start a new session, where the same card or another payment method can work; when it istrue, the card form was reset and the buyer can try again on it.
blocked_by_rule before rendering it in a browserdecline_message is buyer-safe, but for blocked_by_rule it is not browser-safe: its wording differs from the generic decline, which makes a refusal by your own rule distinguishable from an issuer decline. A scripted caller could use that difference to map which cards you refuse.
Our browser-facing responses do not carry decline_message at all, so this cannot reach a buyer's page by itself — every copy of it you hold came from a secret-key response or a webhook. That makes the coarsening yours to do: if you echo the field into a page, replace it with your generic decline copy when failure_code is blocked_by_rule.
Your own copy keyed off failure_code is the option for tone control or a language other than English — decline_message is English only. Either way, the charge response carries the same fields; do not wait on the webhook to tell someone their card failed.
blocked_by_rule — your own rule, not a bank decline
This is the one value in the list that is not a decline in the usual sense. The charge never reached an issuer: a routing rule on your own account refused it first.
It is not limited to card brands — the rule may key on a brand you have chosen not to accept, a card country you block, prepaid cards, or be a catch-all with no name of its own.
Which of your rules fired is reported as rule_code — but only if you gave the rule a code. See Telling your rules apart below.
Reporting a rule refusal as its own code requires provider support, as rule tags do. On a provider that does not distinguish it, a refusal by your own rule arrives as generic_decline — so the absence of blocked_by_rule is not proof no rule fired. Confirm your provider reports it before building decline-rate reporting on it.
Its action is hard: the same card is refused for as long as the rule stands, so the buyer needs a different payment method.
Telling your rules apart — rule_code
Every rule produces the same decline_code, so a brand rule and a country rule are indistinguishable by that field alone. rule_code carries the code you gave the rule in your provider dashboard — or, on a provider that assigns its own rule identifiers, that identifier — minus any provider prefix. It is what lets you branch on them separately.
{
"status": "failed",
"decline_code": "blocked_by_rule",
"action": "hard",
"rule_code": "amex_not_accepted"
}
You have to name your rules for this to work. Left blank, every rule emits one identical value and rule_code comes back null — set a custom code on each rule before you write any handling. A null on a blocked_by_rule payment means the rule has no custom code, or (see the availability note above) your provider does not report rule refusals separately at all.
- It is echoed back as you typed it, minus any provider prefix. We do not interpret it.
- A code that is not a plain identifier comes back
nullrather than altered. Letters, digits,_and-, up to 64 characters, and the first character must be a letter or a digit —_amex_blockis rejected tonull, which looks identical to never having named the rule.
rule_code appears wherever decline_code does on a secret-key surface: the payment intent, and the charge.failed / payment_intent.failed / session.failed webhooks. Browser-facing responses — every response a buyer's browser can receive, including POST /v1/public/sessions/{id}/charge — report a rule refusal as the generic card_declined and carry no rule_code (except a rule that refuses a card brand outright, reported as card_brand_not_accepted, naming the brand only): a publishable key is readable from your page source, and naming the rule there would let anyone map which cards you refuse. Read the full value from your server: on the payment intent create/confirm response or a later GET /v1/payment_intents/{id} (decline_code), or on the charge.failed webhook (failure_code).
For a worked example — configuring the rule, branching on it, and what to tell the buyer — see Handling rule declines.
If you branch on failure_code directly, treat any value you do not recognize as hard and prefer action, which is a closed set.
When the decline block is absent
action is not a classificationaction accompanies the decline on the payment intent create/confirm response, on GET /v1/payment_intents/{id} for a failed payment, and on the charge.failed / payment_intent.failed / session.failed webhooks; the browser charge-at-submit response does not carry it. Where present it can still be null — the decline carried a code we hold no classification for, or the failure never resolved a normalized code at all — and it is deliberately not reported as generic. action, decline_code and decline_message derive from the same code, so in the second case they are all null together. Never treat a missing action as permission to retry.
Trigger the declines above by order total in test mode; the processor's test environment decides by the total, not by the card number. Note that the fraud decline surfaces failure_code as fraudulent on the wire. blocked_by_rule is the exception — no order total produces it, because it depends on a rule configured on your account rather than on the payment. Exercise your handling for it by configuring a rule in your provider dashboard.