⚠️ Common Errors

Common Checkout Errors

User is blocked

This error 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.

No Customer Associated with Customer ID

This error is 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.

Invalid merchant configuration - credit settlement not supported

This error 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 a valid blockchain wallet in the headers—Credits can’t be purchased without a wallet on the desired blockchain.

Please sign a message and get a JWT token to use this endpoint

This error occurs because 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.

Common Errors for Merchants Settling to an EVM Contract

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.

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.

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.

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 minted to the user and then redeemed through your contract. 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.