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:
            // Google Pay not available on this device, the button won't render
            break;
        case 1005:
            // Payment authorization or processing failure, inspect additionalInfo
            break;
        case 1010:
            // paymentData drift, make sure the values you return from
            // onBeforeProcessPayment match the ones passed at init()
            break;
        default:
            console.error('Google 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: the SDK falls back to `['VISA', 'MASTERCARD']` in normal setups, so this only surfaces when the terminal configuration explicitly returns an empty list of card networks.	Contact DNA Payments support if you encounter this.
`1002`	Failed to initialize the Google Pay button	Reserved for future use: currently the SDK does not throw this code at runtime. Treat as an unexpected initialization failure if you ever see it.	Inspect `additionalInfo` and contact DNA Payments support.
`1003`	Failed to validate the Google Pay session	Google Pay is not available on the device or browser. No button is rendered.	Hide your Google Pay placeholder and offer a different payment method. Most common causes: WebView (cannot run Google Pay at all), unsupported browser.
`1004`	Failed to authorize the Google Pay payment	The Google Pay sheet failed to return an authorized payment (user cancellation is routed to `onCancel` instead).	Inspect `additionalInfo` for the underlying status code and message. Offer the user a retry.
`1005`	Failed to process the Google Pay payment	Either an exception thrown inside your `onBeforeProcessPayment` callback, or a network / backend exception during the payment execution call to DNA Payments, or a payment that came back with `success === false` from the acquirer.	Inspect `additionalInfo` to identify the cause. If it is your `onBeforeProcessPayment`, wrap its body in `try/catch` and surface a friendly message. If it is a backend issue, log it for diagnosis and offer the user a retry.
`1006`	The paymentData is missing	`paymentData` was not provided at `init()`.	Provide a valid `paymentData` at `init()`. See paymentData reference.
`1007`	The authentication token is missing.	Reached payment execution with no access token on the SDK client: token was neither provided at `init()` nor returned from `onBeforeProcessPayment`.	Provide a valid `access_token` to `init()`, or return one from `onBeforeProcessPayment` for the CMS pattern. See Authentication.
`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 `onBeforeProcessPayment` to add server-side fields such as `invoiceId`, not to change the displayed total. If the cart amount can change, re-initialize the component instead.

Notes

Always show the user a friendly message rather than the raw error text: the messages above are intended for developers, not end customers.
1003 is by far the most common code merchants see in production. It usually means the device or browser cannot run Google Pay (WebView, unsupported browser, no card in the wallet). Treat it as an availability signal, not a bug.
1010 is the security guard for the CMS flow. Use onBeforeProcessPayment to add server-side fields like invoiceId, not to change amount or currency.

Error code reference​

Notes​

Error code reference

Notes