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.

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

{
  "type": "PAYMENT_SETTLEMENT_CONTRACT_V1_0_PAYMENT_INTENT",
  "types": {
    "EIP712Domain": [
      {
        "name": "name",
        "type": "string"
      },
      {
        "name": "chainId",
        "type": "uint256"
      },
      {
        "name": "verifyingContract",
        "type": "address"
      }
    ],
    "PaymentIntent": [
      {
        "name": "from",
        "type": "address"
      },
      {
        "name": "to",
        "type": "address"
      },
      {
        "name": "value",
        "type": "uint256"
      },
      {
        "name": "validAfter",
        "type": "uint256"
      },
      {
        "name": "validBefore",
        "type": "uint256"
      },
      {
        "name": "nonce",
        "type": "bytes32"
      },
      {
        "name": "beneficiary",
        "type": "address"
      },
      {
        "name": "maxFee",
        "type": "uint256"
      },
      {
        "name": "requirePayeeSign",
        "type": "bool"
      },
      {
        "name": "attester",
        "type": "address"
      }
    ],
    "TokenPermissions": [
      {
        "name": "token",
        "type": "address"
      },
      {
        "name": "amount",
        "type": "uint256"
      }
    ],
    "PermitWitnessTransferFrom": [
      {
        "name": "permitted",
        "type": "TokenPermissions"
      },
      {
        "name": "spender",
        "type": "address"
      },
      {
        "name": "nonce",
        "type": "uint256"
      },
      {
        "name": "deadline",
        "type": "uint256"
      },
      {
        "name": "witness",
        "type": "PaymentIntent"
      }
    ]
  },
  "domain": {
    "name": "Permit2",
    "chainId": "11155111",
    "verifyingContract": "0x000000000022D473030F116dDEE9F6B43aC78BA3"
  },
  "message": {
    "nonce": "25668617285137697861288274946631174355105919960416755114569514179393151588120",
    "spender": "0xe2B17D0C1736dc7C462ABc4233C91BDb9F27DD1d",
    "witness": {
      "to": "0xc75c3e371d617b3e60db1b6f3fa2f0689562e5a7",
      "fee": "0",
      "from": "0x57414adbBbc4BBA36f1dE26b2dc1648b28ae7799",
      "nonce": "0x38bfec2b230187932870d575132e8ae1f83b34c10e3bf6d64c377f0c13245718",
      "value": 14174474,
      "attester": "0x768919ef04853b5fd444ccff48cea154768a0291",
      "validAfter": "1757358106",
      "beneficiary": "0x4f1c3a0359A7fAd8Fa8E9E872F7C06dAd97C91Fd",
      "validBefore": "1757361726",
      "requirePayeeSign": false
    },
    "deadline": "1757362866",
    "permitted": {
      "token": "0x1c7D4B196Cb0C7B01d743Fbc6116a902379C7238",
      "amount": "14174474"
    }
  },
  "primaryType": "PermitWitnessTransferFrom"
}

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.