Handling Error Codes

Every error raised by the component is delivered to your onError handler as a plain object:

{
    code: number,
    message: string,
    additionalInfo?: any
}

additionalInfo carries the underlying cause when available (the original exception, or the response body from the DNA Payments backend), useful for logging and debugging.

Hook it up once and branch on code:

function onError(error) {
    switch (error.code) {
        case 1003:
            // Domain not registered or session validation failed
            break;
        case 1007:
            // Token missing: refresh and retry
            break;
        // ... add other cases as needed
        default:
            console.error('Apple Pay error:', error);
    }
}

Error code reference

Code	Message	When it fires	Recommended action
`1001`	There are no card networks configured for this terminal	Rare edge case: fires only if the terminal configuration explicitly returns an empty list of card networks. In normal setups the SDK falls back to `['VISA', 'MASTERCARD']` and this error does not fire.	Contact DNA Payments support if you encounter this.
`1002`	Failed to initialize the Apple Pay button	Apple Pay is not available on the device, or `canMakePayments()` returns `false`.	Gate `init()` behind `isAvailable()` so non-supported devices never attempt rendering.
`1003`	Could not validate Apple Pay session	Merchant validation against Apple failed, most commonly because the domain is not registered in the relevant portal.	Add the domain in `Settings → Online payment methods → Apple Pay → Add new domain` in test-portal (sandbox) or portal (production). See Prerequisites → Domain registration.
`1004`	Failed to authorize the Apple Pay payment	The acquirer returned a failed authorization.	Show the user the failure and offer retry. Inspect the API logs in the portal for the underlying decline reason.
`1005`	Failed to process the Apple Pay payment	Either an exception thrown inside your `onBeforeProcessPayment` callback, or a network/backend exception during the payment execution call to DNA Payments.	Inspect `additionalInfo` to identify the cause. If the source is your `onBeforeProcessPayment`, wrap its body in `try/catch` and surface a friendly message. If the source is a network/backend issue, log it for diagnosis and offer the user a retry.
`1007`	The authentication token is missing.	Reached payment execution with no access token on the SDK client. In practice this means token was not supplied at `init()`.	Provide a valid `access_token` to `init()`. See Authentication.
`1008`	The paymentData is missing	The user clicked the button but `paymentData` was not provided to `init()`. Fires before the Apple Pay sheet opens.	Provide a valid `paymentData` to `init()`. See paymentData reference.
`1010`	The payment data provided in the onBeforeProcessPayment event does not match the initial payment data. Mismatched fields: `<list>`	The `paymentData` returned from `onBeforeProcessPayment` differs from the `init()` values on one of the locked fields: `amount`, `currency`, or the delivery address (`postalCode` + `addressLine1` + `addressLine2`). This is a security guard against silently tampering with the value the user just approved on screen.	Keep `amount`, `currency` and the delivery address identical to the `init()` values when constructing the returned `paymentData`. Use the hook to add server-side fields such as `invoiceId` (typical CMS pattern), not to change the displayed total.

Notes

Always show the user a friendly message rather than the raw error text: the messages above are intended for developers, not end customers.
Domain-related issues (1003) are by far the most common source of integration tickets. Double-check that the host the page actually serves from is the one you registered, with no www. mismatch and no stale ngrok URL.

Error code reference​

Notes​

Error code reference

Notes