⚠️ Common Errors

Common Checkout Errors

Error Message	Description	Code
`User is blocked`	Occurs 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 ID`	Expected 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 supported`	Appears 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 endpoint`	A 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

Advanced: Settling to an EVM Contract

Error Message	Description	Code
`Address: call to non-contract`	Typically 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 allowance`	Typically 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 allowance`	Typically 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 Message	Code
`Payments not configured correctly, please contact merchant`	400

Rate Limiting & Velocity Errors

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

Error Message	Description	Code
`Failed checkout attempts exceeded limit (N), please try again later`	Returned 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 Message	Description	Code
`Card already exists for another user, please use a different card`	Returned 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 reused`	Returned 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 Message	Description	Code
`Challenge required`	Returned 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 issuer`	Returned 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 Message	Description	Code
`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 Message	Description	Code
`Purchases are limited to $N in the sandbox environment`	Returned when a purchase in the sandbox environment exceeds the fixed sandbox purchase limit. This limit does not apply in production.	400