On This Page
Reason Codes
A
Unified Checkout
request response returns one of the following reason
codes: Reason Code | Description | |
|---|---|---|
200 | Successful response. | |
201 | Capture
context created. | |
400 - Capture Context API | Bad request. Possible
reason values: | |
CAPTURE_CONTEXT_EXPIRED | This reason is returned when the capture context JWT has passed
its expiration time of 900 seconds (15 minutes). Example decrypted JWT fields include "exp":
"1762894371" and "iat":
"1762893471" . | |
CAPTURE_CONTEXT_INVALID | The Unified Checkout
configuration rejected the request due to invalid values. This
reason is returned when the minimum required fields are missing
or invalid or the capture context contradicts which products are
enabled. | |
CHECKOUT_ERROR | Checkout failed. This reason is
returned when a general, non‑payment‑method‑specific error
occurs during the UnifiedPayments checkout
flow. When the checkout failure is specifically related to
tokenization, Click to Pay SDK, SRC launch,
Google Pay, etc., the SDK returns a more specific
error | |
CLICK_TO_PAY_SDK_LOAD_ERROR | This reason is returned when the UI
cannot be successfully rendered. For example:
| |
CREATE_TOKEN_TIMEOUT | The token creation timed out. This
reason is returned when the Unified Checkout
JavaScript SDK cannot generate the transient token within the
expected time-frame. | |
CREATE_TOKEN_XHR_ERROR | This reason is returned when the system
attempts to create a token, but a network /
XHR-level
failure occurs before the token can be created. This is a
client-side SDK network failure, not a timeout or back-end
validation error. | |
ENCRYPT_CARD_FOR_SRC_ENROLMENT_ERROR | Encrypt card for
SRC
enrollment failed. This reason is returned when Unified Checkout attempts to encrypt a card to enroll it in
the SRC / Click to Pay system and the encryption
step fails. This causes the SRC enrolment to abort. | |
GOOGLEPAY_CHECKOUT_ERROR | Checkout failed. This reason is
returned when Unified Checkout attempts to complete a
Google Pay checkout, but the Google Pay–based transaction fails
internally in the Unified Checkout checkout
flow. | |
INVALID_APIKEY | Returned when the API key that is used
in the server‑side capture context request is invalid. | |
LAUNCH_SRC_CHECKOUT_ERROR | The launch SRC checkout failed. This
reason is returned by the Unified Checkout JavaScript
SDK when it cannot initialize or open the SRC checkout flow. | |
SDK_XHR_ERROR | SDK failed to load. This reason is
returned when the JavaScript SDK fails to load due to an XHR/network
error during Unified Checkout initialization. | |
SHOW_LOAD_CONTAINER_SELECTOR | The
specified DOM element cannot be found. Returned when the DOM element
specified in the show() configuration cannot be
found. This is a client-side JavaScript SDK error thrown during
rendering of the payment selection UI. | |
SHOW_LOAD_ERROR | There was a problem encountered when
loading the payment screen. Returned when the Unified Payments UI
fails to load the payment selection screen (iframe/UI) during the
.show() step | |
SHOW_LOAD_INVALID_CONTAINER | The supplied container parameter is
invalid. Returned when the container provided to
up.show() exists but is invalid—wrong type, not
suitable to host UC UI, unsupported context, or malformed in
configuration | |
SHOW_LOAD_SIDEBAR_OPTIONS | The supplied container parameter is
invalid when sidebar is selected. Returned when sidebar =
true and the containers supplied to
up.show() are not valid for the sidebar layout
(wrong type, unsupported container, or structurally
incompatible). | |
SHOW_PAYMENT_TIMEOUT | Occurs when an error is encountered
during the handling of a payment option. Returned when UC cannot
progress the user’s selected payment option in time: | |
SHOW_PAYMENT_UNAVAILABLE | No payment types could be presented to
the customer. This could be due to browser/device support or errors
encountered during the checkout. Returned when zero payment
methods can be presented in the .show() phase —
typically due to browser/device incompatibility, disabled payment
types, or internal errors while loading payment options. | |
SHOW_TOKEN_TIMEOUT | Occurs when the createToken call was
unable to proceed. Returned when the createToken
call cannot proceed within the expected time while rendering the
payment selection UI | |
SHOW_TOKEN_XHR_ERROR | Occurs when a network error is
encountered while attempting to create a token. Returned when the
createToken step within
.show() fails due to an actual network/XHR
error (blocked request, CORS/CSP violation, extension interference,
unreachable endpoint). | |
TOKENIZATION_ERROR | Tokenization failed. Returned when
tokenization of the selected payment method fails — due to invalid
payment data, a failed internal tokenization call, network issues,
or an unsupported/blocked payment environment. | |
TRIGGER_PAYMENT_TYPE_NOT_SUPPORTED | Trigger is not supported for this
payment type. Returned when up.trigger(paymentType)
is called with a payment method that does not support trigger mode,
is not enabled, not available on the device/browser, or not
recognized by UC. | |
UNIFIED_PAYMENTS_ALREADY_SHOWN | Occurs if you attempt to show a Unified
Payments instance multiple times. Returned when
.show() is invoked more than once on the same
UnifiedPayments instance. Create a new instance
(accept.unifiedPayments() ) if you need to show
UC again. | |
UNIFIED_PAYMENTS_PAYMENT_PARAMETERS | Occurs when no valid payment parameters
exist when initializing button. Returned when the merchant calls
accept.unifiedPayments() without providing
valid payment parameters — meaning the SDK cannot initialize the
payment buttons because the supplied configuration is missing,
empty, or malformed. | |
UNIFIED_PAYMENTS_VALIDATION_FIELDS | A validation error occurred. Missing or
invalid values in required fields | |
UNIFIED_PAYMENTS_VALIDATION_PARAMS | Trigger is not supported for this
payment type. Returned when up.trigger(paymentType)
is called with a payment method that does not support trigger mode,
is not enabled, not available on the device/browser, or not
recognized by UC. | |
400 -
Complete API | COMPLETE_AUTHENTICATION_CANCELED | Occurs when the user cancels the
authentication process during Cardinal step‑up. This value is
returned when the customer cancels or prematurely exits the 3‑D
Secure (Cardinal) step‑up authentication flow during
unifiedPayments.complete() . |
COMPLETE_AUTHENTICATION_FAILED | Occurs when the complete authentication
process fails during Cardinal Step‑Up. Returned when the 3‑D
Secure (Cardinal) authentication attempt fails—typically due to
incorrect OTP, issuer decline, timeout interpreted as failure,
or ACS technical error—during
unifiedPayments.complete() . | |
COMPLETE_ERROR | Occurs when an error occurs whilst
attempting to complete the transaction. Returned when an
unexpected or uncategorized error occurs during
unifiedPayments.complete() —typically caused
by internal processing exceptions or failures that cannot be
classified as authentication failure, user cancellation,
validation error, or processor decline. | |
COMPLETE_IN_PROGRESS | Returned when
unifiedPayments.complete() is invoked again
while a previous Complete operation is still running. This is caused
by duplicate submissions, race conditions, or UI re-renders that
trigger multiple Complete calls. | |
COMPLETE_NOT_ALLOWED | Occurs if complete is not allowed for
this transaction. Returned when the merchant calls
unifiedPayments.complete() in a state where
the transaction is not permitted to be completed—typically due
to missing/invalid Complete Mandate, calling complete() before
the customer has completed the UC UI flow, using an unsupported
payment type, or invoking complete() at the wrong time in the
lifecycle. | |
COMPLETE_TRANSACTION_CANCELLED | Occurs when the user cancels the
transaction. Returned when the user (or the payment provider
on behalf of the user) cancels the transaction during the
Complete phase — including cancellations on the UC UI,
cancellations during redirect/step‑up, or cancellation states
returned by APMs such as PPRO or Tink. | |
COMPLETE_TRANSACTION_FAILED | Consumer transaction has
failed. Returned when the payment attempt reaches the
processor or APM provider and is returned as a failure —
such as card declines, failed 3DS outcomes, APM failures, or
downstream processor rejections. | |
COMPLETE_VALIDATION_ERROR | Occurs when there is a validation issue
relating to the parameters you have supplied in your complete
call. Returned when the merchant sends invalid, missing,
malformed, or inconsistent parameters to the
unifiedPayments.complete() call — typically
a bad trust token or a mismatched/incorrect payload. | |
404 | The
specified resource not found in the system. | |
500 | Unexpected server error. | |