Mint

API Resources

Discover the many resources used by Circle APIs to enable payouts, payments, and transfers.

Circle APIs are a set of functions and procedures that allow you to use USDC for payments, payouts, and transfers. Circle's APIs are built around several resources that represent payments, payouts, transfers, and their associated objects.

This page contains information on the following resources:

Payment Object - a payment from a customer. Can be funded from a card or an incoming wire.
Payout Object - a payout to a customer, vendor, or supplier.
Transfer Object - a transfer of funds from a Circle wallet to a blockchain address, from a blockchain address to a Circle wallet, or between two Circle wallets.

Wire Account Object
Wallet Object - balances managed by Circle

Cancel Object - an attempt at canceling a payment
Refund Object - an attempt at refunding a payment

Source and Destination Objects - indicate where the funds are coming from and where they're going.
Money Object - a monetary quantity represented as an amount and a currency
Blockchain Addresses
Merchants

A payment object represents a payment from a customer and can be funded from a card or an incoming wire.

Payment

JSON

{
  "id": "e665ea6e-3a53-4f93-a85e-45178d48d9ea",
  "type": "payment",
  "merchantId": "c680d087-7b41-40aa-95a2-68febcdddb22",
  "merchantWalletId": "1000002853",
  "amount": {
    "amount": "1.0",
    "currency": "USD"
  },
  "source": {
    "id": "86461e9f-db1a-487f-915b-641138062e7c",
    "type": "card"
  },
  "description": "description",
  "status": "pending",
  "verification": {
    "avs": "not_requested",
    "cvv": "not_requested"
  },
  "cancel": { .. },
  "refunds": [],
  "fees": {
    "amount": "3.0",
    "currency": "USD"
  },
  "trackingRef": "74537600052007895984372",
  "errorCode": "payment_failed",
  "metadata": {
    "email": "[email protected]",
    "phoneNumber": "+14155555555"
  },
  "riskEvaluation": {
    "decision": "denied",
    "reason": "3000"
  },
  "createDate": "2020-04-10T02:29:53.888Z",
  "updateDate": "2020-04-10T02:32:19.421Z"
}

id string
A UUID for the payment.

type string
The type of payment object. Possible values: payment, refund, cancel.

merchantId string
The UUID of the merchant.

merchantWalletId string
The id of the merchant's wallet.

amount object
A Money object representing the total payment amount that is charged to the source.

source object
A Source object representing the payment source.

description string
Description of the payment.

status string
Enumerated status of the payment. pending means the payment is waiting to be processed. confirmed means the payment has been approved by the bank and the merchant can treat it as successful, but settlement funds are not yet available to the merchant. paid means settlement funds have been received and are available to the merchant. failed means something went wrong (most commonly that the payment was denied). Terminal states are paid and failed.

verification object
Status of verification checks. Attributes include avs and cvv.
For avs, the value represents the raw AVS response, expressed as an upper-case letter. not_requested indicates check was not made, and pending is pending/processing.
For cvv, not_requested indicates check was not made. pass indicates value is correct. fail indicates value is incorrect. unavailable indicates card issuer did not do the provided check. pending indicates check is pending/processing.

cancel object
A Cancel object if one exists.

refunds [object]
An array of Refund objects if they exist.

fees [object]
A Money object representing fees associated with this payment.

trackingRef string
Payment tracking reference.

errorCode string
Indicates the failure reason of a payment. Only present for payments in failed state. See Entity Errors for a full list of possible codes.

metadata object
The email and phoneNumber provided during payment creation.

riskEvaluation object
An object with two attributes, decision and reason.

createDate string
ISO-8601 UTC date/time format.

updateDate string
ISO-8601 UTC date/time format.

A payout object represents a payout to a customer, vendor, or supplier.

Payout

JSON

{
  "id": "df3b8e5f-9579-4c1f-9fa9-deac7f4be55c",
  "sourceWalletId": "1000038499",
  "destination": {
    "id": "4d260293-d17c-4309-a8da-fa7850f95c10",
    "type": "wire",
  },
  "amount": {
    "amount": "10.0",
    "currency": "USD"
  },
  "fees": {
    "amount": 3.0,
    "currency": "USD"
  },
  "status": "complete",
  "trackingRef": "95476600046382591768456",
  "errorCode": "insufficient_funds",
  "riskEvaluation": {
    "decision": "denied",
    "reason": "3000"
  },
  "return": { ... },
  "createDate": "2020-12-24T11:19:20.561Z",
  "updateDate": "2020-12-24T12:01:00.523Z",

}

id string
A UUID for the payout.

sourceWalletId string
The identifier of the source wallet used to fund a payout.

destination object
The Destination object the payout is being made to.

amount object
A Money object representing the total amount that is paid to the destination.

toAmount object
A Money object representing the amount that is paid to the destination currency. Only included for crypto payouts.

fees object
A Money object representing fees associated with this payment.

status string
Status of the payout. pending indicates that the payout is in process; complete indicates it finished successfully; failed indicates it failed.

trackingRef string
Payout tracking reference. Only included on fiat payouts.

externalRef string
External network identifier which will be present once provided from the applicable network.

errorCode string
Indicates the failure reason of a payout. Only present for payouts in failed state. Possible values are insufficient_funds, transaction_denied, transaction_failed, and transaction_returned.

riskEvaluation object
An object with two attributes, decision and reason.

return object
A Return object if the payout was returned.

createDate string
ISO-8601 UTC date/time format.

updateDate string
ISO-8601 UTC date/time format.

A transfer object represents a transfer of funds from a Circle wallet to a blockchain address, from a blockchain address to a Circle wallet, or between two Circle wallets.

Transfer

JSON

{
  "id": "0d46b642-3a5f-4071-a747-4053b7df2f99",
  "source": {
    "type": "blockchain",
    "chain": "ETH",
    "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F"
  },
  "destination": {
    "type": "wallet",
    "id": "12345"
  },
  "amount": {
    "amount": "3.14",
    "currency": "USD"
  },
  "transactionHash": "0x4cebf8f90c9243a23c77e4ae20df691469e4b933b295a73376292843968f7a63",
  "status": "pending",
  "riskEvaluation": {
    "decision": "approved",
    "reason": "Circle approved credit card"
  },
  "createDate": "2020-04-10T02:29:53.888Z"
}

id string
A UUID for the transfer.

source object
A Source object representing the source of the transfer.

destination object
A Destination object representing the destination of the transfer.

amount object
A Money object representing the amount transferred between source and destination.

transactionHash string
A hash that uniquely identifies an on-chain transaction. This is only available when either source or destination are of type blockchain.

status string
Status of the transfer. Status pending indicates that the transfer is in the process of running; complete indicates it finished successfully; failed indicates it failed.
createDate string
ISO-8601 UTC date/time format.

Bank Account (Wire)

JSON

{
  "id": "e5e5109d-5a3c-47cd-93ee-9cfe054691bf",
  "type": "wire",
  "status": "complete",
  "description": "WELLS FARGO BANK, NA ****1111",
  "trackingRef": "CIR3EDXL6M",
  "virtualAccountEnabled": false,
  "fingerprint": "6177934f-0830-45ed-beb7-c67d225327a1",
  "billingDetails": {
    "name": "Satoshi Nakamoto",
    "line1": "100 Money Street",
    "line2": "Suite 1",
    "city": "Boston",
    "postalCode": "01234",
    "district": "MA",
    "country": "US"
  },
  "bankAddress": {
    "bankName": "WELLS FARGO BANK, NA",
    "city": "SAN FRANCISCO",
    "district": "CA",
    "country": "US"
  },
  "createDate": "2021-01-12T10:05:54.815Z",
  "updateDate": "2021-01-12T10:05:54.815Z"
}

Wallets represent balances managed by Circle. A single wallet is designed to hold multiple balances, but only one balance per currency. As the only supported currency is "USD", all wallets today have a single balance.

Unlike other resources in our APIs, wallet IDs are shorter numerical strings and are not represented as longer UUIDs.

Wallet

JSON

{
  "walletId": "434000",
  "entityId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
  "type": "end_user_wallet",
  "description": "Treasury Wallet",
  "balances": [
    {
      "amount": "3.14",
      "currency": "USD"
    }
  ]
}

Below is a list of resources that relate to an original payment or payout. They represent subsequent events that happen after the initial creation or settlement of the payment/payout.

A cancel object represents an attempt at canceling a payment. Cancellations apply only to card payments, and its presence doesn't necessarily mean that the cancellation was successful. A successful cancellation has a status of paid.

Cancel

JSON

{
  "id": "b783ad5e-1ace-4b41-8c0d-5bce31ae971b",
  "type": "cancel",
  "merchantId": "b3528f9f-e381-46d0-9405-31d709f95360",
  "merchantWalletId": "1000038499",
  "source": {
    "id": "619c7e7a-f406-427f-bd38-e885895f280a",
    "type": "card"
  },
  "description": "Cancel Payment",
  "amount": {
    "amount": "250.00",
    "currency": "USD"
  },
  "fees": {
    "amount": "0.00",
    "currency": "USD"
  },
  "status": "paid",
  "originalPayment": {
    "id": "765fb559-394b-4d21-972c-0423e937b0d3",
    "type": "payment",
    "status": "paid",
    "createDate": "2020-12-17T15:29:33.701Z",
    "updateDate": "2020-12-17T16:13:11.043Z"
  },
  "reason": "requested_by_customer",
  "createDate": "2020-12-22T19:58:20.722Z",
  "updateDate": "2020-12-22T20:02:15.382Z"
}

A refund object represents an attempt at refunding a payment. Its presence doesn't mean that the refund was successful. A successful refund has a status of paid.

Refund

JSON

{
  "id": "b937c833-b7f3-48fc-bc6f-09d492eb4a47",
  "type": "refund",
  "merchantId": "aef0d056-6119-4fc1-a13a-c7ecd8682999",
  "merchantWalletId": "1000038499",
  "source": {
    "id": "94705f9a-0ae4-4fb1-b77f-6e6042150ce1",
    "type": "card"
  },
  "description": "Refund Payment",
  "amount": {
    "amount": "1.00",
    "currency": "USD"
  },
  "fees": {
    "amount": "0.00",
    "currency": "USD"
  },
  "status": "paid",
  "originalPayment": {
    "id": "5adf260a-c54b-4a4d-a548-4a51ce2280b7",
    "type": "payment",
    "status": "paid",
    "description": "Merchant Payment",
    "amount": {
      "amount": "1.00",
      "currency": "USD"
    },
    "fees": {
      "amount": "0.04",
      "currency": "USD"
    },
    "createDate": "2020-12-17T15:27:17.300Z",
    "updateDate": "2020-12-17T15:40:10.455Z",
    "merchantId": "aef0d056-6119-4fc1-a13a-c7ecd8682999",
    "merchantWalletId": "1000038499",
    "source": {
      "id": "94705f9a-0ae4-4fb1-b77f-6e6042150ce1",
      "type": "card"
    },
    "trackingRef": "11300134136681725782464"
  },
  "reason": "requested_by_customer",
  "createDate": "2021-01-05T10:34:25.797Z",
  "updateDate": "2021-01-05T10:38:16.676Z"
}

Below is a list of resources that are commonly used in other objects.

Payments, payouts, and transfers reference source and destination objects, which as the names suggest, tell you where the funds are coming from and where they're going.

Sources and destinations can have the following types:

card for card payments
wire for wire payments and payouts
blockchain for transfers to/from blockchain addresses
wallet for transfers to/from a Circle wallet

Source and Destination

JSON

// "card",  "wire"
// The "id" represents the UUID of the Card or Wire object.
{
  "type": "card",
  "id": "4d260293-d17c-4309-a8da-fa7850f95c10"
}

// "blockchain"
// A "chain" and "address" together represent the blockchain location.
{
  "type": "blockchain",
  "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
  "chain": "ETH"
}

// "wallet"
// The "id" is the id of the Circle wallet.
{
  "type": "wallet",
  "id": "12345"
}

Monetary amounts across our APIs are represented as Money objects, which consist of an amount and a currency. Two fiat currencies are supported, USD and EUR, with the amount represented as a string containing the whole units and two decimals. In the example below, the amount is represented as 3.14 and the currency as USD.

Money

JSON

{
  "amount": "3.14",
  "currency": "USD"
}

Blockchain Address

JSON

{
  "address": "0x8381470ED67C3802402dbbFa0058E8871F017A6F",
  "currency": "USD",
  "chain": "ETH"
}

Merchant

JSON

{
  "marketplaceId": "1e38dcef-a947-493a-a674-f623e4418ace",
  "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
  "merchantWalletId": "212000",
  "name": "Merchant Inc",
  "createDate": "2020-04-10T02:13:30.000Z"
}

Did this page help you?

API Resources

Primary Resources

Methods and Instruments

Additional Resources

Nested Resources

Primary Resources

Payment Object

Example Payment Object

Payment

Payment Attributes

Payout Object

Example Payout Object

Payout

Payout Attributes

Transfer Object

Example Transfer Object

Transfer

Transfer Attributes

Methods and Instruments

Wire Account Object

Bank Account (Wire)

Wallet Object

Wallet

Additional Resources

Cancel Object

Cancel

Refund Object

Refund

Nested Resources

Source and Destination Objects

Source and Destination

Money Object

Money

Blockchain Addresses

Blockchain Address

Merchants

Merchant