Circle's APIs are built around several resources that represent payments, payouts, transfers, and their associated objects.
# 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
## Card Object
## 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.
## Settlement Object
When one or more payments in a batch settle, it means that the funds have cleared, USDC has been minted, and your funds have been made available at the specified `merchantWalletId`. Generally, payments made on the same business day are batched and settle together. Payments that have settled will have a `status` of `paid`.
Settlements can also include debits caused by refunds, reversals, and chargebacks.
The total credits, debits, and fees are all summed into a single settlement object.
## Chargeback Object
Chargebacks apply only to card payments, and occur when a customer requests their bank to return the funds for a purchase or when a customer's bank detects a problem with the transaction.
The `paymentId` points to the original payment that is being charged back, and the `merchantId` is the merchant that the original payment was paid to.
## 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`.
## Return Object
Returns apply to payouts (wires) and represent instances where the receiving bank subsequently rejected/returned a payout.
# 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.