On This Page

Handle Errors

The Unified Checkout SDK uses a structured error object for all error scenarios. Errors are returned as exceptions from asynchronous methods and are also returned as events for centralized handling.

UnifiedCheckoutError

All SDK errors are instances of

UnifiedCheckoutError

with these properties:

UnifiedCheckoutError
Properties
Property	Type	Description
correlationId	string?	The correlation ID from an underlying API call, when applicable.
details	unknown?	Additional error-specific information. This is often an array of objects.
informationLink	string?	The URL linked to the online documentation for this error.
message	string	This property is a human-readable description of the error.
name	string	The value is always "UnifiedCheckoutError" .
reason	string	This property is a machine-readable error code, such as "CAPTURE_CONTEXT_INVALID" .

Detect Errors

Errors may be serialized through

postMessage

. Visa Acceptance Solutions recommends that you use the

name

property instead of

instanceof

try {
  const result = await checkout.mount('#buttons');
} catch (error) {
  if (error.name === 'UnifiedCheckoutError') {
    // Access error.reason, error.message, error.details
  }
}

You can also write a helper function that can be reused:

function isUnifiedCheckoutError(obj) {
  return (
    obj !== null &&
    typeof obj === 'object' &&
    obj.name === 'UnifiedCheckoutError' &&
    typeof obj.reason === 'string' &&
    typeof obj.message === 'string'
  );
}

Error Handling Patterns

Try/Catch

try {
  const client = await VAS.UnifiedCheckout(sessionJWT);
  const checkout = await client.createCheckout();
  const result = await checkout.mount('#buttons');
} catch (error) {
  console.error(error.reason, error.message);
}

Promise .catch()

VAS.UnifiedCheckout(sessionJWT)
  .then(client => client.createCheckout())
  .then(checkout => checkout.mount('#buttons'))
  .catch(error => console.error(error.reason, error.message));

Centralized Error Logging via Events

Errors from all integrations are applicable up to the client level. Use

client.on('error')

for centralized logging:

const client = await VAS.UnifiedCheckout(sessionJWT);

client.on('error', (err) => {
  errorReporter.send({
    source: err.source,   // "checkout", "trigger", "button", or "client"
    code: err.code,
    message: err.message
  });
});

Visa Acceptance Solutions recommends that you do this as it catches errors from all checkouts, triggers, and buttons created from this client instance.

Error Codes

Initialization Errors

These errors are returned during

VAS.UnifiedCheckout(sessionJWT)

Initialization Reason Values
Reason	Description
CAPTURE_CONTEXT_EXPIRED	The supplied JWT has expired. Generate a new session.
CAPTURE_CONTEXT_INVALID	The session JWT is not valid. For example, it has a bad signature or is malformed.
UNUSED_TARGET_ORIGINS	One or more targetOrigins in the session do not match the current page origin. The details array lists the unused origins.

Mount Errors

These errors are returned during

checkout.mount()

trigger.mount()

Mount Reason Values
Reason	Description
CHECKOUT_ALREADY_MOUNTED	The checkout or trigger is already mounted. Call unmount() first, or create a new instance.
MOUNT_CONTAINER_SELECTOR	The CSS selector does not match any Document Object Model (DOM) element. Check that the container exists before calling mount() .
MOUNT_ERROR	A problem occurred loading the payment iframe.
MOUNT_INVALID_CONTAINER	The supplied container parameter is not a valid CSS selector string or HTMLElement .
MOUNT_PAYMENT_TIMEOUT	A payment method timed out during initialization.
MOUNT_PAYMENT_UNAVAILABLE	No payment types could be presented to the customer. This may be due to browser or device support, or errors during checkout initialization.
MOUNT_SIDEBAR_OPTIONS	The supplied container parameter is invalid for sidebar mode.
MOUNT_TOKEN_TIMEOUT	Token creation timed out during mount. This may indicate a network issue.
MOUNT_TOKEN_XHR_ERROR	A network error occurred during token creation. Check the customer’s connectivity.

Complete Errors

These errors are returned during

checkout.complete()

trigger.complete()

Complete Reason Values
Reason	Description
COMPLETE_AUTHENTICATION_CANCELED	The customer cancelled the `3-D Secure` authentication step-up.
COMPLETE_AUTHENTICATION_FAILED	The `3-D Secure` authentication step-up failed.
COMPLETE_ERROR	A general error occurred during transaction completion.
COMPLETE_IN_PROGRESS	complete() has already been called and has not yet finished. Wait for the current call to resolve.
COMPLETE_NOT_ALLOWED	Complete is not allowed for this transaction, such as when autoProcessing is set to true .
COMPLETE_TRANSACTION_CANCELLED	The customer cancelled the transaction.
COMPLETE_TRANSACTION_FAILED	The transaction failed during processing.
COMPLETE_VALIDATION_ERROR	The parameters supplied to complete() have a validation error. Check the details for specifics

Checkout Errors

Checkout Reason Values
Reason	Description
CHECKOUT_ERROR	A general checkout error occurred.
CHECKOUT_PAYMENT_PARAMETERS	One or more payment parameters have a validation error.
CHECKOUT_VALIDATION_PARAMS	One or more checkout parameters have a validation error.

Trigger Errors

Trigger Reason Values
Reason	Description
TRIGGER_PAYMENT_TYPE_NOT_SUPPORTED	The specified payment type cannot be used with a trigger. Only PANENTRY and CLICKTOPAY values are supported.

Payment-Specific Errors

Payment-Specific Reason Values
Reason	Description
CLICK_TO_PAY_SDK_LOAD_ERROR	The `Click to Pay`SDK failed to load.
ENCRYPT_CARD_FOR_SRC_ENROLMENT_ERROR	Card encryption for `Click to Pay` enrollment failed.
GOOGLEPAY_CHECKOUT_ERROR	A Google Pay checkout error occurred.
LAUNCH_SRC_CHECKOUT_ERROR	Launching the `Click to Pay` checkout failed.
TRIGGER_PAYMENT_TYPE_NOT_SUPPORTED	The payment type is not supported for triggers.

General Errors

Reason Code	Description
UNKNOWN_ERROR	An unknown error has occurred.