# `RevolutCheckoutError` Error type thrown by the Revolut Checkout SDK when operations fail. All SDK errors implement this interface, allowing for consistent error handling across all payment methods and widgets. ## Type signature ```typescript interface RevolutCheckoutError extends Error { name: 'RevolutCheckout' type: RevolutCheckoutErrorType code?: number message: string } type RevolutCheckoutErrorType = | 'error.unknown' | 'error.unauthenticated-access' | 'error.order-not-found' | 'error.transaction-invalid-state' | 'error.declined' | 'error.token-not-found' | 'error.email-is-not-specified' | 'error.order-already-completed' | 'error.deactivated-merchant' | 'error.invalid-postcode' | 'error.invalid-email' | 'error.invalid-name' | 'error.invalid-address' | 'error.do-not-honour' | 'error.insufficient-funds' | 'error.3ds-failed' | 'error.expired-card' | 'error.incorrect-cvv-code' | 'error.order-is-cancelled' | 'error.trusted-principal-not-specified' | 'error.merchant-not-specified' | 'error.invalid-order-type' | 'error.transaction-step' | 'error.payment-method-already-exists' | 'error.payment-method-not-found' | 'error.order-customer-id-is-not-set' | 'error.payment-method-not-permitted-for-merchant' | 'error.webhook-not-found' | 'error.verification-not-permitted' | 'error.customer-already-exists' | 'error.unknown-authorisation' | 'error.submerchant-not-found' | 'error.submerchant-incorrect-notification' | 'error.3ds-incorrect-notification' | 'error.authentication-challenge-not-found' | 'error.mpi-provider' | 'error.payment-gateway' | 'error.invalid-provider-response' | 'error.unexpected-mpi-provider' | 'error.terminal-not-found' | 'error.submerchant-not-onboarded' ``` ## Properties | Property | Description | Type | Required | | --------- | -------------------------------------------------------- | -------------------------- | -------- | | `name` | Always set to `'RevolutCheckout'` to identify SDK errors | `'RevolutCheckout'` | Yes | | `type` | Specific error type identifier | `RevolutCheckoutErrorType` | Yes | | `code` | HTTP status code when applicable | `number` | No | | `message` | Human-readable error description | `string` | Yes | ## Common errors | Error type | Description | Customer action | Merchant action | | ------------------------------- | -------------------------------------------- | ------------------------------------ | -------------------------------------------- | | `error.declined` | Payment declined by card issuer | Try different card or payment method | Display error message, offer alternatives | | `error.insufficient-funds` | Insufficient funds in account | Try different payment method | Display error message, suggest other options | | `error.3ds-failed` | 3D Secure authentication failed | Contact bank or try different card | Display error message, log for analysis | | `error.expired-card` | Card has expired | Use different card | Display clear expiry error | | `error.incorrect-cvv-code` | CVV/CVC code is incorrect | Re-enter CVV | Display field-specific error | | `error.order-not-found` | Order token provided but order doesn't exist | Refresh page and try again | Regenerate order token | | `error.order-already-completed` | Order was already paid | - | Don't retry payment, check webhook | | `error.invalid-email` | Email format is invalid | Correct email address | Validate email format client-side | | `error.invalid-postcode` | Postcode format is invalid | Correct postcode | Validate postcode format | | `error.unknown` | Unexpected error occurred | Try again later | Log error, contact support | ## Complete error type reference ### Payment errors | Error type | Description | | ---------------------------------- | -------------------------------------------------------- | | `error.declined` | Payment declined by card issuer or payment provider | | `error.do-not-honour` | Payment declined by issuer with 'do not honour' response | | `error.insufficient-funds` | Insufficient funds in customer's account | | `error.expired-card` | Card has expired | | `error.incorrect-cvv-code` | CVV/CVC security code is incorrect | | `error.3ds-failed` | 3D Secure authentication failed or was not completed | | `error.3ds-incorrect-notification` | Received incorrect 3D Secure notification from provider | ### Validation errors | Error type | Description | | ------------------------ | ----------------------------------------- | | `error.invalid-email` | Email address format is invalid | | `error.invalid-name` | Name format is invalid or incomplete | | `error.invalid-address` | Address details are invalid or incomplete | | `error.invalid-postcode` | Postcode/ZIP code format is invalid | ### Order errors | Error type | Description | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------ | | `error.order-not-found` | The order token was provided but no corresponding order was found | | `error.order-already-completed` | Order has already been successfully paid | | `error.order-is-cancelled` | Order has been cancelled and cannot be paid | | `error.invalid-order-type` | Order type is not valid for the requested operation | | `error.order-customer-id-is-not-set` | Customer ID is required to save payment method but not set on order. Set `order.customer.id` during order creation/update before accepting the payment | | `error.email-is-not-specified` | Email is required but not provided on order or in widget | ### Authentication errors | Error type | Description | | ------------------------------------------ | ---------------------------------------------------------------------- | | `error.unauthenticated-access` | Request requires authentication but credentials are invalid or missing | | `error.token-not-found` | No order token was provided to the SDK | | `error.verification-not-permitted` | Payment verification is not permitted for this transaction | | `error.unknown-authorisation` | Authorisation attempt is not recognised | | `error.authentication-challenge-not-found` | Authentication challenge (e.g., 3DS) not found | ### Merchant configuration errors | Error type | Description | | --------------------------------------- | -------------------------------------------- | | `error.deactivated-merchant` | Merchant account has been deactivated | | `error.merchant-not-specified` | Merchant identifier is missing from request | | `error.trusted-principal-not-specified` | Trusted principal (API key) is not specified | :::info[Sub-merchant errors] The following errors apply to PSP (Payment Service Provider) and marketplace integrations where a parent merchant (e.g., Adyen) delegates payment processing to end merchants (sub-merchants or Merchants of Record). ::: | Error type | Description | | ------------------------------------------ | ------------------------------------------------------------ | | `error.submerchant-not-found` | Sub-merchant configuration not found | | `error.submerchant-not-onboarded` | Sub-merchant has not completed the onboarding process | | `error.submerchant-incorrect-notification` | Received incorrect notification for sub-merchant transaction | ### Payment method errors | Error type | Description | | ------------------------------------------------- | ------------------------------------------------- | | `error.payment-method-already-exists` | Payment method is already saved for this customer | | `error.payment-method-not-found` | Saved payment method not found | | `error.payment-method-not-permitted-for-merchant` | Payment method is not enabled for this merchant | ### Technical errors | Error type | Description | | --------------------------------- | -------------------------------------------------- | | `error.payment-gateway` | Payment gateway error occurred during processing | | `error.mpi-provider` | Error from MPI (3D Secure) provider | | `error.invalid-provider-response` | Received invalid response from payment provider | | `error.unexpected-mpi-provider` | Unexpected or unsupported MPI provider encountered | ### Transaction errors | Error type | Description | | --------------------------------- | -------------------------------------------------------------- | | `error.transaction-invalid-state` | Transaction is in an invalid state for the requested operation | | `error.transaction-step` | Error occurred during transaction processing step | ### Other errors | Error type | Description | | ------------------------------- | -------------------------------------------- | | `error.webhook-not-found` | Webhook configuration not found | | `error.terminal-not-found` | Terminal configuration not found | | `error.customer-already-exists` | Customer with this identifier already exists | | `error.unknown` | Unknown or unexpected error occurred | ## Error handling Examples of handling `RevolutCheckoutError` in different scenarios. ### Basic error handling ```typescript import RevolutCheckout from '@revolut/checkout' try { const { destroy } = await RevolutCheckout.embeddedCheckout({ publicToken: 'pk_...', environment: 'prod', // ... configuration }) } catch (error) { if (error.name === 'RevolutCheckout') { // Handle SDK-specific errors console.error(`Checkout error [${error.type}]:`, error.message) // Display user-friendly message alert(`Payment initialisation failed: ${error.message}`) } else { // Handle network/system errors console.error('Failed to initialize checkout:', error) } } ``` ### Error handling in callbacks ```typescript const { destroy } = await RevolutCheckout.embeddedCheckout({ publicToken: 'pk_...', environment: 'prod', target: document.getElementById('checkout'), createOrder: async () => { const response = await fetch('/api/create-order') const order = await response.json() return { publicId: order.token } }, onError: ({ error, orderId }) => { // error is RevolutCheckoutError console.error('Payment failed:', { type: error.type, message: error.message, code: error.code, orderId, }) // Handle specific error types switch (error.type) { case 'error.declined': showMessage('Your card was declined. Please try a different card.') break case 'error.insufficient-funds': showMessage( 'Insufficient funds. Please use a different payment method.', ) break case 'error.3ds-failed': showMessage('Authentication failed. Please contact your bank.') break default: showMessage(`Payment failed: ${error.message}`) } }, }) ``` ## Validation errors For form field validation errors, see: [ValidationError](/docs/sdks/merchant-web-sdk/types/validation-error) Validation errors have a different interface and are specific to card field validation: ```typescript interface ValidationError extends Error { name: 'Validation' type: ValidationErrorType // e.g., 'validation.card.number.invalid' } ``` ## See also - [ValidationError](/docs/sdks/merchant-web-sdk/types/validation-error) - Form field validation errors - [Embedded checkout callbacks](/docs/sdks/merchant-web-sdk/payment-methods/embedded-checkout#callback-events)