CheckoutImplementation OverviewErrors

⚠️ Common Errors

Common Checkout Errors

Error MessageDescriptionCode
User is blockedOccurs when a customer has raised or is about to raise a chargeback using the same card—either on your account or with any merchant in the Coinflow ecosystem. This helps prevent repeated fraud or misuse across the platform and is triggered by both formal chargebacks and pre-chargeback notifications.400
No Customer Associated with Customer IDExpected for a first-time payer. Coinflow creates a customer record after the payer completes their first purchase. The payment method is saved, so the next time the customer returns, their payment method will be automatically available for a faster checkout. A returning customer who has already made a purchase through Coinflow will not encounter this error.400
Invalid merchant configuration - credit settlement not supportedAppears when a purchase for Credits doesn’t align with the merchant’s setup. Confirm you’re intending to buy Credits, and ensure you’re passing the correct headers for your settlement configuration. See authentication headers for the headers required by your settlement setup.400
Please sign a message and get a JWT token to use this endpointA signed JWT is required to authorize access to saved payment methods. Use the Get Session Key endpoint and pass the returned sessionKey to the CoinflowPurchase component (as a prop) or in the x-coinflow-auth-session-key header. Note: Ensure you’re passing the correct headers for your use case when generating a session key.400

Error MessageDescriptionCode
Address: call to non-contractTypically returned when merchants are settling revenue to an EVM contract on a sandbox environment. Make sure transactionData.transaction.to is set to your testnet contract address—not your mainnet address if you are testing in sandbox.400
Insufficient allowanceTypically returned when a contract other than the one whitelisted is trying to pull the funds from coinflow contract. Ensure you’ve whitelisted your contract and are passing the correct address to transactionData.transaction.to.400
Insufficient USDC allowance / Transfer amount exceeds allowanceTypically returned when a merchant contract is trying to pull more USDC from our contract than what Coinflow’s contract approved for it to spend.400

Invalid Configuration Errors

Payments not configured correctly, please contact merchant

This error appears when an invalid combination of checkout parameters is used. Common causes include:

  • Using authOnly with a transaction: Authorization-only purchases (authOnly: true) cannot be combined with a redemption transaction. When authOnly is enabled, the payment is only authorized but not captured, which means credits are not minted until the payment is captured. However, the redemption flow expects credits to be available immediately after the card payment.

    Solution: Either remove the transaction parameter and handle redemption separately after capturing the payment, or remove authOnly to capture the payment immediately.

  • Using a transaction with non-Credits settlement: Redemption transactions can only be used with settlementType: "Credits". The transaction parameter triggers a credit redemption flow where credits are issued to the user and then redeemed via your custom redemption flow. This flow is incompatible with USDC or Bank settlement types.

    Solution: Set settlementType to "Credits" when using a transaction, or remove the transaction parameter if you need a different settlement type.

Error MessageCode
Payments not configured correctly, please contact merchant400

Rate Limiting & Velocity Errors

These errors are triggered by repeated failed attempts on the same account, card, or session in a short window.

Error MessageDescriptionCode
Failed checkout attempts exceeded limit (N), please try again laterReturned when an account has exceeded the allowed number of failed checkout attempts. Wait for the cooldown period to pass, then retry.429
Payment attempts with multiple cards have failed. For security, please wait 1 hour before trying again.Returned when a customer has attempted payment with several different cards that all failed. For security, the customer must wait one hour before trying again.429
This account has reached its card limit for the past 30 days. Please use a card you have used before or try again later.Returned when an account has attempted payment with too many distinct cards within a rolling 30 day window. Use a previously used card, or wait before adding a new one.429
We are unable to process your payment at this time.A generic decline returned when a payment is rejected by Coinflow’s velocity checks. Retrying after some time, or with a different payment method, may succeed.429
This Visa card has reached its maximum number of retry attempts (N) over the past 30 days. Please try a different card or payment method.Returned when a specific Visa card has been declined too many times in the past 30 days. Use a different card or payment method.400 (auth code 100)

Card Reuse Errors

Error MessageDescriptionCode
Card already exists for another user, please use a different cardReturned when a customer attempts to save a card that is already associated with a different customer record.400
This card has already been used by another customer and cannot be reusedReturned when a card has already been used by another customer and card reuse is not permitted for this merchant.403

3D Secure (3DS) Errors

Error MessageDescriptionCode
Challenge requiredReturned when the issuer requires the customer to complete a 3DS challenge before the payment can proceed. The response includes transactionId, url, and creq fields needed to render the challenge.412
Card rejected by issuerReturned when the issuing bank rejects the 3DS authentication request outright.400 (auth code 998)
(varies — issuer-supplied challenge failure message)Returned when the customer starts but fails to complete the 3DS challenge (for example, entering an incorrect one-time code). The customer should retry the purchase or try a different card.400 (auth code 997)

CVV Revalidation Error

Error MessageDescriptionCode
Validation for this card has expired. Revalidate the CVV for this card, and make a new purchase using the /api/checkout/card/token in order to begin using this endpoint again.Returned when a previously validated card’s CVV validation has expired. Revalidate the CVV via /api/checkout/card/token before reusing this payment method.410

Sandbox Errors

Error MessageDescriptionCode
Purchases are limited to $N in the sandbox environmentReturned when a purchase in the sandbox environment exceeds the fixed sandbox purchase limit. This limit does not apply in production.400