Payment and Transaction Failure Reasons

When payments or transactions fail, you’ll receive an object containing the failure reason. Depending on when the failure occurs, this information is returned in the synchronous (API) or asynchronous (webhook) response. The following sections outline the reasons that each of these components might fail.

Payments

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.

The payment failure notification includes a failure reason (listed below) and a failure code containing more specific information about the failure. The failure code provides information about how to resolve the issue and create a new payment.

Failure reason	Description
TRAVEL_RULE_FAILED	The travel rule information included with the payment was rejected
BANK_VERIFICATION_FAILED	The bank information included with the payment was rejected
RFI_VERIFICATION_FAILED	The payment failed due to issues related to RFI handling or verification
EXISTING_RFI_PENDING	An RFI exists on the customer in a non-terminal state
ONCHAIN_SETTLEMENT_FAILED	The payment couldn’t be processed due to an issue with the onchain settlement
FIAT_SETTLEMENT_FAILED	The payment couldn’t be completed due to routing or bank settlement issues
COMPLIANCE_CHECK_FAILED	The payment was rejected due a compliance check failure
CANCELLED	The payment is canceled by the originator
PAYMENT_EXPIRED	The payment is expired and not able to provide further action.
OTHER	General payment failure not covered by other reasons

Transactions

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 in its valid time frame.
SIGNED_TRANSACTION_EXPIRED	(Solana only) The signed transaction is expired. Solana requires you to submit a signed transaction in 150 blocks (~1 min). Resolution: Initiate a new transaction and submit it in the appropriate time frame.
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 aren’t able to perform any further actions. Resolution: Initiate a new transaction.