_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:

### Primary 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.

### Methods and Instruments

Wire Account Object Wallet Object - balances managed by Circle

### Additional Resources

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

### Nested Resources

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

# Primary Resources

## Payment Object

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

### Example Payment Object



### Payment Attributes




**`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.

## Payout Object

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

### Example Payout Object



### Payout Attributes




**`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.

## Transfer Object

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.

### Example Transfer Object



### Transfer Attributes




**`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.




# Methods and Instruments

## Wire Account Object



## Wallet Object

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.



# Additional Resources

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.

## Cancel Object

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`.



## Refund Object

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`.



# Nested Resources

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

## Source and Destination 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`



## Money Object

Monetary amounts across our APIs are represented as Money objects, which consist of an `amount` and a `currency`. The only supported currency at the moment is `USD`, and the amount is denominated in dollars as a string with fractional cents. In the example below, the amount being represented is $3.14.



## Blockchain Addresses



## Merchants