Troubleshooting Payment Issues

💳 Resolving Payment Failures

Before digging into specific error codes, have your user try these first:

Turn off active VPNs: VPNs frequently trigger automated fraud blocks at the card issuer level.
Check pop-up blockers: Make sure the browser allows pop-ups so bank authentication challenges can load properly.
Use Google Chrome: Other browsers can sometimes interfere with the checkout flow — Chrome tends to work best.

If those steps don't help, you can look up the specific error code via the API or your dashboard.

Error codes can be programmatically retrieved from our orders API or from the order_failed webhook event. Webhook failure events can also be reviewed directly in your partner dashboard. The orders API requires an API key; tracking webhooks requires an active server endpoint configured to receive incoming events.

To help you quickly diagnose these errors, we've grouped the most common failure reasons below with their bank codes, explanations, and next steps.

🚫 Bank & Card Restrictions

Error Code 4002 / 4012: Declined by Card Issuer

What happened: The issuing bank rejected the payment. This is common with fiat-to-crypto transactions due to automated fraud rules or Merchant Category Code (MCC) restrictions.

How to fix: Ask the user to contact their card issuer, confirm they're making a legitimate purchase, and request that future transactions with Wert are explicitly authorised.

Error Code 4005: Card Limit Exceeded

What happened: The transaction exceeds the user's daily, monthly, or per-transaction spending limit set by their bank.

How to fix: The user can complete the purchase with a different card or request a temporary limit increase from their bank.

Error Code 4013: Risk Review

What happened: Wert's fraud prevention flagged and blocked the transaction.

How to fix: Ask the user to complete full identity verification (KYC). If they're already verified, escalate to Wert support.

❌ Incorrect Card & Account Details

Error Code 4001: Card CVV Invalid

What happened: The 3 or 4-digit card verification code was entered incorrectly or failed bank verification.

How to fix: Ask the user to re-enter their payment details and double-check the CVV against their physical card.

Error Code 4003 / 4011: Incorrect Card Details or Validation Failed

What happened: The card is expired, inactive, or the card number or expiration date was entered incorrectly.

How to fix: The user should check their card details or retry with a valid card.

Error Code 4004: Insufficient Balance

What happened: The issuing bank declined the transaction due to insufficient funds.

How to fix: The user needs to fund their account or switch to a different payment method.

Error Code 4014: Name Mismatch

What happened: The name on the funding card or bank account doesn't match the name submitted during KYC.

How to fix: Direct the user to Wert support so our team can help sort out the discrepancy.

⏱️ Security & Timeout Errors

Error Code 4010: 3DS Authentication Failure

What happened: The transaction failed 3-Domain Secure (3DS) authentication — this can happen if the OTP wasn't completed in time, the session timed out, or the provider doesn't support 3DS.

How to fix: Make sure the user has disabled any active VPNs, has a stable mobile signal for incoming SMS challenges, and completes the bank's security prompt promptly.

Error Code 4000: General Rejection / Technical Glitch

What happened: A temporary network timeout or routing interruption occurred between the payment gateway and the issuing bank.

How to fix: Ask the user to wait two minutes and try again.

Error Code 4015 / 4016 / 4017: Timing & Amount Issues

What happened: The checkout session expired, or the network detected a mismatch in the asset or amount.

How to fix: Ask the user to clear the widget session and restart checkout. If funds were charged before the timeout (Error 4016), a refund will be processed automatically — let the user know it's on its way.

Error Code 4018: Payment Cancelled

What happened: The user manually closed the session. No funds were captured.

How to fix: Nothing to action on your end. The user can restart the purchase flow in the widget whenever they're ready.

📬 Still Stuck?

If this guide doesn't get them unblocked, reach out through any of these:

🤝 Partner Chat: Your dedicated partner channel.
💬 Live Chat: Bottom-right corner of this page.
📧 Email: [email protected]