Skip to main content
GET
/
v1
/
cpn
/
payments
List payments
curl --request GET \
  --url https://api.circle.com/v1/cpn/payments \
  --header 'Authorization: Bearer <token>'
{
  "data": [
    {
      "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
      "quoteId": "custom_ref_id",
      "paymentMethodType": "SPEI",
      "blockchain": "ETH-SEPOLIA",
      "senderAddress": "0xe01be9cdd9e744ae6a709794bfe531ec3ec0671c",
      "refCode": "custom_ref_id",
      "customerRefId": "custom_ref_id",
      "expireDate": "2023-01-01T12:04:05Z",
      "createDate": "2023-01-01T12:04:05Z",
      "status": "COMPLETED",
      "useCase": "B2B",
      "reasonForPayment": "PMT001",
      "sourceAmount": {
        "amount": "110.270000",
        "currency": "USDC"
      },
      "destinationAmount": {
        "amount": "183.24",
        "currency": "MXN"
      },
      "fees": {
        "breakdown": [
          {
            "amount": {
              "amount": "0.240000",
              "currency": "USDC"
            },
            "type": "BFI_TRANSACTION_FEE"
          }
        ],
        "totalAmount": {
          "amount": "110.270000",
          "currency": "USDC"
        }
      },
      "beneficiaryRefId": "custom_ref_id",
      "fiatNetworkPaymentRef": "custom_ref_id",
      "failureReason": "CANCELLED",
      "failureCode": "PM01001",
      "activeRfi": {
        "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
        "paymentId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
        "status": "APPROVED",
        "level": "LEVEL_1",
        "expireDate": "2023-01-01T12:04:05Z",
        "certificate": {
          "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
          "certPem": "LS0tLS1CRUdJT...",
          "domain": "api.circle.com",
          "jwk": {
            "crv": "P-256",
            "kid": "263521881931753643998528753619816524468853605762",
            "kty": "EC",
            "x": "KnxBe8fb2mL_Ve9-tqjGSkGgE9f0yohMkAvH_InaFtE",
            "y": "D41cVUpiKcey4LJKNFtUtmVHDWRmhjZapPLfryX5b1o"
          }
        },
        "fieldRequirements": {
          "version": 1,
          "schema": {
            "type": "object",
            "$defs": {
              "address": {
                "type": "object",
                "required": [
                  "street",
                  "city",
                  "country"
                ],
                "properties": {
                  "city": {
                    "type": "string",
                    "description": "City name"
                  },
                  "street": {
                    "type": "string",
                    "description": "Street address"
                  },
                  "country": {
                    "type": "string",
                    "pattern": "^[A-Z]{2}$",
                    "description": "Country code (e.g., US, GB)"
                  },
                  "postalCode": {
                    "type": "string",
                    "description": "Postal or ZIP code"
                  },
                  "stateProvince": {
                    "type": "string",
                    "description": "State or province"
                  }
                },
                "description": "Full address"
              },
              "individual": {
                "type": "object",
                "required": [
                  "name",
                  "address",
                  "dateOfBirth"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Individual's full name"
                  },
                  "address": {
                    "ref": "#/$defs/address"
                  },
                  "dateOfBirth": {
                    "type": "string",
                    "format": "date",
                    "description": "Individual's date of birth (YYYY-MM-DD)"
                  }
                },
                "description": "Individual's RFI data"
              },
              "beneficiaryOwner": {
                "type": "object",
                "required": [
                  "name",
                  "address",
                  "dateOfBirth",
                  "percentage"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Individual's full name"
                  },
                  "address": {
                    "ref": "#/$defs/address"
                  },
                  "percentage": {
                    "type": "number",
                    "description": "Company ownership percentage"
                  },
                  "dateOfBirth": {
                    "type": "string",
                    "format": "date",
                    "description": "Individual's date of birth (YYYY-MM-DD)"
                  }
                },
                "description": "Beneficiary owner's RFI data"
              },
              "intermediaryBeneficiaryOwner": {
                "type": "object",
                "required": [
                  "name",
                  "address",
                  "dateOfFormation",
                  "countryOfFormation",
                  "percentage"
                ],
                "properties": {
                  "name": {
                    "type": "string",
                    "description": "Business legal name"
                  },
                  "address": {
                    "ref": "#/$defs/address"
                  },
                  "percentage": {
                    "type": "number",
                    "description": "Company ownership percentage"
                  },
                  "dateOfFormation": {
                    "type": "string",
                    "format": "date",
                    "description": "Company formation date (YYYY-MM-DD)"
                  },
                  "countryOfFormation": {
                    "type": "string",
                    "pattern": "^[A-Z]{2}$",
                    "description": "Entity formation country"
                  }
                },
                "description": "Intermediary beneficiary owner's RFI data"
              }
            },
            "title": "RFI Requirements",
            "$schema": "https://json-schema.org/draft/2020-12/schema",
            "required": [
              "SOURCE_OF_FUNDS",
              "METHOD_OF_VERIFICATION",
              "NAME",
              "TRADE_NAME",
              "NATIONAL_IDENTIFICATION_NUMBER",
              "DATE_OF_FORMATION",
              "COUNTRY_OF_FORMATION",
              "ENTITY_TYPE",
              "INDUSTRY_TYPE",
              "ADDRESS",
              "AUTHORIZED_SIGNATORIES",
              "BENEFICIARY_OWNERSHIP"
            ],
            "properties": {
              "NAME": {
                "type": "string",
                "description": "Business legal registered name"
              },
              "EMAIL": {
                "type": "string",
                "description": "Business contact email address"
              },
              "PHONE": {
                "type": "string",
                "description": "Business contact phone number"
              },
              "ADDRESS": {
                "ref": "#/$defs/address"
              },
              "WEBSITE": {
                "type": "string",
                "description": "Business website URL"
              },
              "TRADE_NAME": {
                "type": "string",
                "description": "Business trade name or DBA (Doing Business As)"
              },
              "ENTITY_TYPE": {
                "type": "string",
                "description": "Business structure type (Corporation, LLC, Partnership, etc.)"
              },
              "INDUSTRY_TYPE": {
                "type": "string",
                "description": "Business activity classification"
              },
              "SOURCE_OF_FUNDS": {
                "type": "string",
                "description": "Transaction source of funds"
              },
              "DATE_OF_FORMATION": {
                "type": "string",
                "format": "date",
                "description": "Company formation date (YYYY-MM-DD)"
              },
              "BENEFICIARY_OWNERS": {
                "ref": "#/$defs/beneficiaryOwner"
              },
              "COUNTRY_OF_FORMATION": {
                "type": "string",
                "pattern": "^[A-Z]{2}$",
                "description": "Entity formation country"
              },
              "BENEFICIARY_OWNERSHIP": {
                "type": "boolean",
                "description": "Whether any individuals or intermediaries own 25% or more of the company"
              },
              "AUTHORIZED_SIGNATORIES": {
                "ref": "#/$defs/individual"
              },
              "METHOD_OF_VERIFICATION": {
                "type": "string",
                "description": "Verification method used"
              },
              "NATIONAL_IDENTIFICATION_NUMBER": {
                "type": "string",
                "description": "Business identification number (e.g., Tax ID)"
              },
              "INTERMEDIARY_BENEFICIARY_OWNERS": {
                "ref": "#/$defs/intermediaryBeneficiaryOwner"
              }
            },
            "description": "RFI Data Requirements"
          }
        },
        "fileRequirements": [
          "FORMATION_DOCUMENT"
        ]
      },
      "rfis": [
        {
          "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
          "status": "APPROVED"
        }
      ],
      "onChainTransactions": [
        {
          "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
          "status": "PENDING"
        }
      ],
      "fiatSettlementTime": {
        "max": "3",
        "min": "1",
        "unit": "DAYS"
      },
      "refunds": [
        {
          "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
          "status": "CREATED",
          "amount": {
            "amount": "110.270000",
            "currency": "USDC"
          },
          "transactionHash": "<string>"
        }
      ],
      "metadata": {},
      "statusAddendum": "IN_MANUAL_REVIEW"
    }
  ]
}

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.

Query Parameters

​
status
enum<string>

Filter by the payment status. If specified, it will only return the payments with the specified status. Otherwise, it will return payments including all the possible statues The current status of a payment

Available options:
CREATED,
CRYPTO_FUNDS_PENDING,
FIAT_PAYMENT_INITIATED,
COMPLETED,
FAILED
Example:

"COMPLETED"

​
customerRefId
string

Filter by the customer reference ID from OFI. If specified, it will return the payments associated with this customer. Otherwise, it will return payments including all customers. Reference or description used to identify the object.

Example:

"custom_ref_id"

​
refCode
string

Filter by the payment ref code. If specified it will return the payments associated with this refcode. Otherwise, it will return payments across all ref codes. Reference or description used to identify the object.

Example:

"custom_ref_id"

​
from
string<date-time>

Queries items created since the specified date-time (inclusive) in ISO 8601 format.

Example:

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

​
to
string<date-time>

Queries items created before the specified date-time (inclusive) in ISO 8601 format.

Example:

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

​
pageAfter
string<uuid>

A collection ID value used for pagination.

It marks the exclusive begin of a page. When provided, the collection resource will return the next n items after the id, with n being specified by pageSize.

The items will be returned in the natural order of the collection.

The resource will return the first page if neither pageAfter nor pageBefore are specified.

SHOULD NOT be used in conjunction with pageBefore.

​
pageBefore
string<uuid>

A collection ID value used for pagination.

It marks the exclusive end of a page. When provided, the collection resource will return the next n items before the id, with n being specified by pageSize.

The items will be returned in the natural order of the collection.

The resource will return the first page if neither pageAfter nor pageBefore are specified.

SHOULD NOT be used in conjunction with pageAfter.

​
pageSize
integer
default:50

Limits the number of items to be returned.

Some collections have a strict upper bound that will disregard this value. In case the specified value is higher than the allowed limit, the collection limit will be used.

If avoided, the collection will determine the page size itself.

Required range: 1 <= x <= 200

Response

Payments found.

​
data
object[]
required

Array of payments containing all payment details including source and destination amounts, fees, status, and related transactions