CPN

How-to: Create an Onchain Transaction

When a payment is in the CRYPTO_FUNDS_PENDING state, the OFI must initiate an onchain transaction to fulfill the payment in USDC. CPN provides an API to help prepare and validate the onchain transaction call data, and to broadcast the transaction and monitor its state.

There are two versions of the Transactions API: V1 and V2. This guide provides information on both versions. Note that your quote must match the version of the API that you are using.

Before you begin, ensure that you have:

  • Created a quote through the CPN API. If you are following the Transactions V2 example, your quote should be created with the transactionVersion parameter set to VERSION_2.
  • USDC in your sender wallet
  • (Transactions V1 only) Native tokens in your sender wallet
  • (Transactions V2 only) Granted a USDC allowance to the Permit2 contract. See How-to: Grant USDC Allowance to Permit2 for more information.

Use the following steps to create and broadcast a USDC transfer to the blockchain:

Call the create transaction endpoint to get an unsigned message object. Note that transaction objects differ between EVM blockchains and Solana.

For Transactions V2, call the create transaction V2 endpoint to get an unsigned message object. Transactions V2 supports EVM chains only.

The API call must include the sender wallet information (which must be an EOA wallet). The rest of the transaction data such as amount, chain, destination address, and other information is populated automatically by CPN using the payment record.

Review the unsigned message object and ensure that it matches your expectations for the crypto transaction. Depending on the blockchain, the signing process varies.

  • Transactions V1
  • Transactions V2

When the unsigned data has been confirmed, you must sign it in accordance with EIP-712. Next, you construct an EIP-3009 transaction from the signed data:

  1. Extract the signature. Extract the signature components (v, r, s) from the signed typed data.
  2. Encode the function call. Using the ERC-20 smart contract's ABI for the TransferWithAuthorization function, encode the function call with the required parameters: sender address (from), recipient address (to), validAfter, validBefore, nonce, and the signature components, v, r, s. This encoding creates the data field for the raw transaction.
  3. Construct the transaction object. Build a raw transaction object that includes the target contract address (USDC), the encoded function call data, and other necessary parameters such as nonce, gas limit, max fee per gas, max priority fee per gas, and chain ID.
  4. Serialize the transaction. Serialize the transaction object into the proper RLP-encoded format so that it can be signed.

The following is an example of the transaction object in EIP-1559 format, for EIP-3009 TransferWithAuthorization contract execution.

JSON
{
  "to": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
  "value": "0x0",
  "gasLimit": "0x5208",
  "maxPriorityFeePerGas": "0x59682f00",
  "maxFeePerGas": "0x59682f00",
  "nonce": "0x8",
  "chainId": 1,
  "type": "0x2",
  "data": "0xe3ee160e000000000000000000000000a9d56270e9fd76be802ac4d45ef4be4322fdadbc0000000000000000000000006840c9f894b6b8264292e22b8abb2c57ae3946a700000000000000000000000000000000000000000000000000000000000f424000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000067ca8f131e790e4b5e8d2f801f12bdd8e8a9fcab490305f17a59a1620549791985617c36000000000000000000000000000000000000000000000000000000000000001cc8973666e8460a153a5a073a7a2878a4e6f42be09ffe012a04d342f2a729019b769e46ab7fefb0dadf8a6d0dd83a687d6dfcdfaf1c56af190eaaff8252e5929e"
}

Sign this transaction data and move on to the next step.

On Solana, the transfer data follows Solana's Ed2559 transaction format. After confirming the unsigned data, a transaction object is constructed with the transfer data. You sign the transaction object and submit it to the API.

Call the submit transaction endpoint to submit the signed transaction data to CPN. For Transactions V2, use the submit transaction V2 endpoint. CPN broadcasts the transaction and provides a webhook to notify you of the transaction status. This webhook is also provided to the BFI.

Once the BFI confirms that they have received the desired amount for the payment, the BFI initiates the fiat payment.

If a transaction fails and the payment is still valid (for example, it has not expired), you can address the issues with the transaction and initiate a new transaction. For example, in a V1 transaction, if there was not enough gas to cover the transaction, you could deposit additional gas tokens to the wallet, and try again. In a V2 transaction, this is less likely to be an issue as gas fees in native tokens are paid from a Circle-controlled wallet. You can use a similar approach to address other onchain failure.

Only one active transaction is allowed at a time per payment, so you can only initiate a new transaction once the previous one has failed.

Did this page help you?
© 2023-2025 Circle Technology Services, LLC. All rights reserved.