Create a transaction (V2)

curl --request POST \
  --url https://api.circle.com/v2/cpn/payments/{paymentId}/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "metadata": {}
}
'

{
  "data": {
    "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "paymentId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "status": "PENDING",
    "expireDate": "2023-01-01T12:04:05Z",
    "senderAddress": "0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c",
    "blockchain": "ETH-SEPOLIA",
    "amount": {
      "amount": "110.270000",
      "currency": "USDC"
    },
    "destinationAddress": "0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c",
    "messageType": "PAYMENT_SETTLEMENT_CONTRACT_V1_0_PAYMENT_INTENT",
    "messageToBeSigned": {},
    "metadata": {},
    "failureReason": "FAILED_ONCHAIN",
    "transactionHash": "2vmEDSBThR143WJyJePkpKVQcERVo9KePuCUwYU8fkoJaQjarTMj6sZG7DNnJ4zjhtRz6hDruqEFEkD4wJpGviiW"
  }
}

POST

cpn

payments

{paymentId}

transactions

Create a transaction (V2)

curl --request POST \
  --url https://api.circle.com/v2/cpn/payments/{paymentId}/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11",
  "metadata": {}
}
'

{
  "data": {
    "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "paymentId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "status": "PENDING",
    "expireDate": "2023-01-01T12:04:05Z",
    "senderAddress": "0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c",
    "blockchain": "ETH-SEPOLIA",
    "amount": {
      "amount": "110.270000",
      "currency": "USDC"
    },
    "destinationAddress": "0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c",
    "messageType": "PAYMENT_SETTLEMENT_CONTRACT_V1_0_PAYMENT_INTENT",
    "messageToBeSigned": {},
    "metadata": {},
    "failureReason": "FAILED_ONCHAIN",
    "transactionHash": "2vmEDSBThR143WJyJePkpKVQcERVo9KePuCUwYU8fkoJaQjarTMj6sZG7DNnJ4zjhtRz6hDruqEFEkD4wJpGviiW"
  }
}

Authorizations

Authorization

string

header

required

Circle's API Keys are formatted in the following structure "PREFIX:ID:SECRET". All three parts are requred to make a successful request.

Path Parameters

paymentId

string<uuid>

required

The payment id created previously. System-generated unique identifier of the resource.

Example:

"c4d1da72-111e-4d52-bdbf-2e74a2d803d5"

Body

application/json

Create a V2 transaction for signing

idempotencyKey

string<uuid>

required

Unique identifier to prevent duplicate transaction creation.

Example:

"a0eebc99-9c0b-4ef8-bb6d-6bb9bd380a11"

metadata

object

Key-value pairs for storing reference data. Up to 50 keys allowed, with key names up to 40 characters and values up to 500 characters.

Show child attributes

metadata.{key}

string

Metadata value

Maximum string length: 500

Response

Transaction created successfully or idempotency conflict.

V2 Transaction response wrapper

data

object

required

V2 transaction response schema containing details about the transaction amount, addresses, and status

Show child attributes

data.id

string<uuid>

required

System-generated unique identifier of the resource.

Example:

"c4d1da72-111e-4d52-bdbf-2e74a2d803d5"

data.paymentId

string<uuid>

required

System-generated unique identifier of the resource.

Example:

"c4d1da72-111e-4d52-bdbf-2e74a2d803d5"

data.status

enum<string>

required

Lifecycle status of a transaction

Available options:

CREATED,

PENDING,

BROADCASTED,

COMPLETED,

FAILED

Example:

"PENDING"

data.expireDate

string<date-time>

required

Date and time when the resource expires

Example:

"2023-01-01T12:04:05Z"

data.senderAddress

string

required

A blockchain address that can be used to send or receive transactions on a blockchain network.

Example:

"0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c"

data.blockchain

enum<string>

required

Supported blockchain networks

Available options:

SOL,

MATIC,

ETH,

SOL-DEVNET,

MATIC-AMOY,

ETH-SEPOLIA

Example:

"ETH-SEPOLIA"

data.amount

object

required

Represents an amount of cryptocurrency, including both the numerical amount and the specific cryptocurrency type.

Show child attributes

data.amount.amount

string

Example:

"110.270000"

data.amount.currency

enum<string>

Supported cryptocurrencies

Available options:

USDC

Example:

"USDC"

Example:

{
  "amount": "110.270000",
  "currency": "USDC"
}

data.destinationAddress

string

required

A blockchain address that can be used to send or receive transactions on a blockchain network.

Example:

"0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c"

data.messageType

enum<string>

required

Transaction message type for V2

Available options:

EIP3009,

SOLANA,

PAYMENT_SETTLEMENT_CONTRACT_V1_0_PAYMENT_INTENT

Example:

"PAYMENT_SETTLEMENT_CONTRACT_V1_0_PAYMENT_INTENT"

data.messageToBeSigned

object

required

The message to be signed by OFI for V2 transactions.

data.metadata

object

Key-value pairs for storing reference data. Up to 50 keys allowed, with key names up to 40 characters and values up to 500 characters.

Show child attributes

data.metadata.{key}

string

Metadata value

Maximum string length: 500

data.failureReason

enum<string> | null

Possible reasons for transaction failure

Available options:

CPN_PAYMENT_EXPIRED,

SIGNED_TRANSACTION_EXPIRED,

NONCE_TOO_LOW,

NONCE_TOO_HIGH,

INSUFFICIENT_TOKEN_BALANCE,

INSUFFICIENT_GAS_BALANCE,

GAS_PRICE_TOO_LOW,

OUT_OF_GAS,

TX_REPLACEMENT_FAILED,

SOL_TX_ALREADY_IN_CACHE,

TX_ALREADY_CONFIRMED,

FAILED_ONCHAIN,

SOL_BLOCKHASH_EXPIRED,

TRANSACTION_EXPIRED,

BROADCAST_FAILED,

RELAY_FAILED,

UNKNOWN_REASON

Example:

"FAILED_ONCHAIN"

data.transactionHash

string | null

Unique identifier assigned to a blockchain transaction when it is broadcast to the network

Example:

"2vmEDSBThR143WJyJePkpKVQcERVo9KePuCUwYU8fkoJaQjarTMj6sZG7DNnJ4zjhtRz6hDruqEFEkD4wJpGviiW"

Accelerate a stuck transaction

Get a transaction by ID (V2)

API Overview

Circle Payments Network

Create a transaction (V2)

Authorizations

Path Parameters

Body

Response