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​

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

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​

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​

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

Validation errors have a different interface and are specific to card field validation:

interface ValidationError extends Error {
  name: 'Validation'
  type: ValidationErrorType // e.g., 'validation.card.number.invalid'
}

See also​

• ValidationError - Form field validation errors
• Embedded checkout callbacks