When payments or transactions fail, you'll receive a webhook notification containing the failure reason. The following sections outline the reasons that each of these components might fail.
When a payment fails in CPN there are no further actions you can take with that payment ID. You should restart the payment workflow by requesting a new quote and accepting it to create a new payment.
| Failure reason | Description |
|---|---|
PAYMENT_EXPIRED | The payment is expired and not able to provide further action. Resolution: Create a new payment. |
INCOMPLETE_TRANSACTION | The onchain transaction was initiated for the payment but a complete transaction was not finalized before the payment expired. Resolution: Create a new payment and ensure that the onchain transaction is completed within its valid timeframe. |
COMPLIANCE_CHECK_FAILED | The payment was rejected due a compliance check failure. Resolution: Verify and correct your compliance information, then create a new payment. |
RFI_REJECTED | After evaluating additional information through the RFI process, the BFI rejected the payment for compliance reasons. |
RFI_PENDING | An RFI exists on the customer that is in a non-terminal state. Resolution: Create a new payment and submit the corresponding RFI before it expires. |
MANUAL_REVIEW_FAILED | The BFI received a request for additional compliance information from the recipient's bank. That information is manually collected before the fiat transfer can be processed. If the manual review is unsuccessful, a refund is initiated. |
CANCELLED | The payment is canceled through a support ticket. Resolution: Create a new payment or contact support. |
BFI_FULFILL_FAILED | The BFI was not able to complete the fiat transfer; a refund is initiated. Resolution: Once the refund is processed and the webhook is received, handle it accordingly and create a new payment. |
UNKNOWN | The payment has failed due to an internal server error. Resolution: Open a support ticket with all the relevant details for further investigation. |
If an onchain transaction fails or becomes stuck, you can create a new transaction or attempt to replace or accelerate the transaction. You may continue to troubleshoot onchain transactions until the payment expires. Note that only one transaction can be associated with a given payment, so you must wait until the current transaction fails or attempt to replace it if you need to update the transaction.
| Failure reason | Description |
|---|---|
CPN_PAYMENT_EXPIRED | The payment corresponding to this transaction is expired. Resolution: Create a new payment and ensure the onchain transaction is completed within its valid timeframe. |
SIGNED_TRANSACTION_EXPIRED | (Solana only) The signed transaction is expired. Solana requires you to submit a signed transaction within 150 blocks (~1 min). Resolution: Initiate a new transaction and submit it within the appropriate timeframe. |
NONCE_TOO_LOW | The nonce of the signed transaction is lower than the current wallet nonce. Resolution: Submit a new transaction using the latest nonce value for the wallet. |
INSUFFICIENT_GAS_BALANCE | Not enough native tokens were available in the wallet to cover the gas fee for the transaction. Resolution: Fund the wallet with the appropriate amount of native tokens and initiate a new transaction. |
GAS_PRICE_TOO_LOW | The specified gas fee is too low, which may prevent the transaction from being included in a block. Resolution: Create a new transaction with a higher gas fee. |
INSUFFICIENT_TOKEN_BALANCE | The wallet does not have enough USDC in it for the transfer amount. Resolution: Fund the wallet with the appropriate amount of USDC for the payment, then initiate a new transaction. |
OUT_OF_GAS | For EVM chains, the gas limit for the signed transaction is insufficient to cover the execution cost. For Solana, the allocated compute budget falls short of the transaction's requirements, preventing successful execution. Resolution: Create a new transaction with a higher gas limit. |
TX_REPLACEMENT_FAILED | The transaction replacement failed because another transaction with the same nonce (and higher fee) is already the mempool or was mined first. If the replacement fails, the original transaction submitted to the blockchain is still executed. |
SOL_TX_ALREADY_IN_CACHE | (Solana only) The transaction has already been broadcast and is present in the network's cache. Resolution: Wait for the current transaction's confirmation or failure before proceeding. |
TX_ALREADY_CONFIRMED | The transaction was confirmed onchain before the current broadcast attempt. Resolution: If this was unexpected, open a support ticket for further investigation. |
FAILED_ONCHAIN | The transaction failed execution on the blockchain. Resolution: Review the onchain error, correct any issues, and submit a new transaction. |
SOL_BLOCKHASH_EXPIRED | (Solana only) The Solana blockhash assigned to the transaction has expired. Resolution: Initiate a new transaction. |
TRANSACTION_EXPIRED | The transaction is expired and you are not able to perform any further actions. Resolution: Initiate a new transaction. |
Did this page help you?
© 2023-2025 Circle Technology Services, LLC. All rights reserved.
