This page is a ZenPay-styled copy of the Zenith Payments developer documentation. View the original docs

Plugin Errors and Troubleshooting

Troubleshooting Checklist#

If the plugin launch is not behaving as expected, check:

• Frontend is calling your backend bootstrap endpoint
• Backend is returning all required fields
• displayMode is what you expect
• Fingerprint was generated server-side
• Timestamp format is correct (YYYY-MM-DDTHH:mm:ss UTC, no milliseconds)
• merchantUniquePaymentId is fresh per attempt
• redirectUrl and optional callbackUrl are correctly configured
• You are not treating redirect alone as final payment success
• You are using the correct Hosted Checkout Page URL for the environment

Error Codes#

Common Error Codes#

E08 — incorrect credentials or fingerprint#

Common causes:

• Wrong username, password, or apiKey — all are case-sensitive; check for trailing spaces
• Wrong timestamp format — must be UTC YYYY-MM-DDTHH:mm:ss, no timezone suffix, no milliseconds
• Amount in dollars instead of cents — the fingerprint uses cents ($100.50 → 10050)
• Wrong hashing algorithm — must be SHA3-512, not SHA-256 or SHA-512

E03 — expired fingerprint#

Fingerprint expired (15-minute window). See Generating the Fingerprint.

Other initialisation errors#

"We have been unable to verify you. Please refresh the page, re-enter your payment account details, and submit the form again."

Typically caused by a failed reCAPTCHA verification. Since reCAPTCHA is managed by Google, there are various reasons it may fail. Usually resolved by:

• Refreshing the page and trying again
• Clearing the browser cache and cookies
• Opening the payment page in a private/incognito browser window
• Trying a different browser or device

This is generally a client-side issue, so one of the above steps will usually resolve it.

Other common error codes (upstream, not initialisation)#

Most other errors originate from systems upstream of Zenith Payments and relate to the customer's card, bank, or financial institution — the primary exception being session timeout (payment sessions expire after 30 minutes; once expired, the payment can no longer be processed).

Common upstream scenarios:

• 3DS validation errors — the cardholder did not successfully complete identity verification with their bank or card issuer
• Insufficient funds — the account does not have sufficient funds available
• Do Not Honour — the bank has declined the transaction, e.g. for fraud prevention or suspicious activity
• Card validation errors — incorrect card number, CVV, expiry date, or other security-related information
• 2003 – Transaction Declined — a generic bank decline code; the payer will usually need to contact their bank
• E206 – Refer to Customer — typically indicates insufficient funds or that the account has exceeded transaction or payment limits

There are many additional error codes depending on payment method and the customer's bank/issuer policies. See the 18-entry error code table above for the full list.

When to contact the financial institution: when an error originates from the card scheme, bank, or payment issuer, Zenith Payments is often unable to determine the specific reason for the decline. Recommend the customer contact their financial institution's Technical Support Team specifically — frontline customer service reps often have limited visibility into transaction-level decline reasons.