List payments
curl --request GET \
--url https://api.circle.com/v1/cpn/payments \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.circle.com/v1/cpn/payments"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.circle.com/v1/cpn/payments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.circle.com/v1/cpn/payments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.circle.com/v1/cpn/payments"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.circle.com/v1/cpn/payments")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.circle.com/v1/cpn/payments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"type": "payment",
"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.000000",
"currency": "USDC"
},
"type": "TAX_FEE"
},
{
"amount": {
"amount": "0.240000",
"currency": "USDC"
},
"type": "BFI_TRANSACTION_FEE"
},
{
"amount": {
"amount": "0.100000",
"currency": "USDC"
},
"type": "CPN_FEE"
},
{
"amount": {
"amount": "0.010000",
"currency": "USDC"
},
"type": "BLOCKCHAIN_GAS_FEE"
}
],
"totalAmount": {
"amount": "0.350000",
"currency": "USDC"
}
},
"refundAddress": "0x7d9f3f9c2b7e4c0a5a9f3e8b4d2c1a0f5e6d7c8b",
"beneficiaryRefId": "custom_ref_id",
"fiatNetworkPaymentRef": "custom_ref_id",
"fiatNetworkTrackingEvent": {
"type": "SWIFT_GPI",
"status": "ACSP",
"reasonCode": "G000",
"statusDescription": "Payment transferred to next gpi bank",
"eventDate": "2026-05-19T09:15:20.000Z",
"bankName": "The Hongkong and Shanghai Banking Corporation Limited",
"bankCode": "HSBCHKHHHKH"
},
"transactionCutoff": "2025-03-24T17:20:34.254Z",
"failureReason": "CANCELLED",
"failureCode": "PM01001",
"activeRfi": {
"type": "rfi",
"id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
"paymentId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
"status": "APPROVED",
"level": "LEVEL_1",
"expireDate": "2023-01-01T12:04:05Z",
"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",
"TRANSACTION_PURPOSE",
"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"
},
"TRANSACTION_PURPOSE": {
"type": "string",
"description": "Purpose of the transaction"
},
"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"
},
"RELATIONSHIP_TO_REMITTER": {
"type": "string",
"description": "Sender's relationship to the remitter"
},
"NATIONAL_IDENTIFICATION_NUMBER": {
"type": "string",
"description": "Business identification number (e.g., Tax ID)"
},
"INTERMEDIARY_BENEFICIARY_OWNERS": {
"ref": "#/$defs/intermediaryBeneficiaryOwner"
}
},
"description": "RFI Data Requirements"
}
},
"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"
}
},
"fileRequirements": [
{
"fileName": "FORMATION_DOCUMENT",
"required": false
}
]
},
"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"
}
]
}{
"code": 400,
"message": "Bad request."
}{
"code": 401,
"message": "Malformed authorization."
}{
"code": 3,
"message": "Forbidden"
}List payments
Returns a list of all payments that fit the specified parameters.
GET
/
v1
/
cpn
/
payments
List payments
curl --request GET \
--url https://api.circle.com/v1/cpn/payments \
--header 'Authorization: Bearer <token>'import requests
url = "https://api.circle.com/v1/cpn/payments"
headers = {"Authorization": "Bearer <token>"}
response = requests.get(url, headers=headers)
print(response.text)const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
fetch('https://api.circle.com/v1/cpn/payments', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));<?php
$curl = curl_init();
curl_setopt_array($curl, [
CURLOPT_URL => "https://api.circle.com/v1/cpn/payments",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "GET",
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>"
],
]);
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}package main
import (
"fmt"
"net/http"
"io"
)
func main() {
url := "https://api.circle.com/v1/cpn/payments"
req, _ := http.NewRequest("GET", url, nil)
req.Header.Add("Authorization", "Bearer <token>")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.get("https://api.circle.com/v1/cpn/payments")
.header("Authorization", "Bearer <token>")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.circle.com/v1/cpn/payments")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'
response = http.request(request)
puts response.read_body{
"data": [
{
"type": "payment",
"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.000000",
"currency": "USDC"
},
"type": "TAX_FEE"
},
{
"amount": {
"amount": "0.240000",
"currency": "USDC"
},
"type": "BFI_TRANSACTION_FEE"
},
{
"amount": {
"amount": "0.100000",
"currency": "USDC"
},
"type": "CPN_FEE"
},
{
"amount": {
"amount": "0.010000",
"currency": "USDC"
},
"type": "BLOCKCHAIN_GAS_FEE"
}
],
"totalAmount": {
"amount": "0.350000",
"currency": "USDC"
}
},
"refundAddress": "0x7d9f3f9c2b7e4c0a5a9f3e8b4d2c1a0f5e6d7c8b",
"beneficiaryRefId": "custom_ref_id",
"fiatNetworkPaymentRef": "custom_ref_id",
"fiatNetworkTrackingEvent": {
"type": "SWIFT_GPI",
"status": "ACSP",
"reasonCode": "G000",
"statusDescription": "Payment transferred to next gpi bank",
"eventDate": "2026-05-19T09:15:20.000Z",
"bankName": "The Hongkong and Shanghai Banking Corporation Limited",
"bankCode": "HSBCHKHHHKH"
},
"transactionCutoff": "2025-03-24T17:20:34.254Z",
"failureReason": "CANCELLED",
"failureCode": "PM01001",
"activeRfi": {
"type": "rfi",
"id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
"paymentId": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
"status": "APPROVED",
"level": "LEVEL_1",
"expireDate": "2023-01-01T12:04:05Z",
"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",
"TRANSACTION_PURPOSE",
"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"
},
"TRANSACTION_PURPOSE": {
"type": "string",
"description": "Purpose of the transaction"
},
"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"
},
"RELATIONSHIP_TO_REMITTER": {
"type": "string",
"description": "Sender's relationship to the remitter"
},
"NATIONAL_IDENTIFICATION_NUMBER": {
"type": "string",
"description": "Business identification number (e.g., Tax ID)"
},
"INTERMEDIARY_BENEFICIARY_OWNERS": {
"ref": "#/$defs/intermediaryBeneficiaryOwner"
}
},
"description": "RFI Data Requirements"
}
},
"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"
}
},
"fileRequirements": [
{
"fileName": "FORMATION_DOCUMENT",
"required": false
}
]
},
"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"
}
]
}{
"code": 400,
"message": "Bad request."
}{
"code": 401,
"message": "Malformed authorization."
}{
"code": 3,
"message": "Forbidden"
}Authorizations
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
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"
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"
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"
Queries items created since the specified date-time (inclusive) in ISO 8601 format.
Example:
"2023-01-01T12:04:05Z"
Queries items created before the specified date-time (inclusive) in ISO 8601 format.
Example:
"2023-01-01T12:04:05Z"
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.
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.
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 <= 200Response
Payments found.
Array of payments containing all payment details including source and destination amounts, fees, status, and related transactions
Show child attributes
Show child attributes
Was this page helpful?