Get a payment

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

string<uuid>

required

Universally unique identifier (UUID v4) of a resource.

Example:

"b3d9d2d5-4c12-4946-a09d-953e82fae2b0"

Response

Successfully retrieved a payment.

data

object

Option 1
Option 2

Show child attributes

data.id

string<uuid>

required

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.type

enum<string>

required

Type of the payment object.

Available options:

payment,

refund,

cancel

data.merchantId

string<uuid>

required

Unique system generated identifier for the merchant.

Example:

"fc988ed5-c129-4f70-a064-e5beb7eb8e32"

data.amount

object

required

Show child attributes

data.amount.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.amount.currency

enum<string>

required

Currency code.

Available options:

USD

data.source

object

required

The payment source.

Show child attributes

data.source.id

string<uuid>

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.source.type

enum<string>

Type of the source.

Available options:

card,

ach,

wire,

sepa

data.status

enum<string>

required

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). action_required means that additional steps are required to process this payment; refer to requiredAction for more details. Terminal states are paid and failed.

Available options:

pending,

confirmed,

paid,

failed,

action_required

data.merchantWalletId

string

Unique system generated identifier for the wallet of the merchant.

Maximum string length: 36

Example:

"212000"

data.fromAmount

object

Show child attributes

data.fromAmount.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.fromAmount.currency

enum<string>

required

Currency code.

Available options:

USD,

EUR,

MXN,

SGD,

BRL

data.description

enum<string>

Enumerated description of the payment.

Available options:

Payment

data.requiredAction

object

When the payment status is action_required, this object summarizes the required additional steps.

Show child attributes

data.requiredAction.type

enum<string>

required

The type of action that is required to proceed with the payment. Currently only one type is supported.

Available options:

three_d_secure_required

data.requiredAction.redirectUrl

string

required

The URL to bring the user to in order to complete the payment.

Example:

"https://example.org"

data.verification

object

Indicates the status of the payment verification. This property will be present once the payment is confirmed.

Show child attributes

data.verification.avs

string

required

Status of the AVS check. Raw AVS response, expressed as an upper-case letter. not_requested indicates check was not made. pending is pending/processing.

Example:

"D"

data.verification.cvv

enum<string>

required

Enumerated status of the check. 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.

Available options:

not_requested,

pass,

fail,

unavailable,

pending

data.verification.threeDSecure

enum<string>

Enumerated status of the check. pass indicates successful 3DS authentication. fail indicates failed 3DS authentication.

Available options:

pass,

fail

data.verification.eci

enum<string>

ECI (electronic commerce indicator) value returned by Directory Servers (namely Visa, MasterCard, JCB, and American Express) indicating the outcome of authentication attempted on transactions enforced by 3DS.

Available options:

00,

01,

02,

05,

06,

07

data.originalPayment

object

Status information of the related payment. This property is only present on refund or cancel items.

Show child attributes

data.originalPayment.id

string<uuid>

required

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.originalPayment.type

enum<string>

required

Type of the payment object.

Available options:

payment

data.originalPayment.merchantId

string<uuid>

required

Unique system generated identifier for the merchant.

Example:

"fc988ed5-c129-4f70-a064-e5beb7eb8e32"

data.originalPayment.amount

object

required

Show child attributes

data.originalPayment.amount.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.originalPayment.amount.currency

enum<string>

required

Currency code.

Available options:

USD

data.originalPayment.source

object

required

The payment source.

Show child attributes

data.originalPayment.source.id

string<uuid>

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.originalPayment.source.type

enum<string>

Type of the source.

Available options:

card,

ach,

wire,

sepa

data.originalPayment.status

enum<string>

required

Available options:

pending,

confirmed,

paid,

failed,

action_required

data.originalPayment.merchantWalletId

string

Unique system generated identifier for the wallet of the merchant.

Maximum string length: 36

Example:

"212000"

data.originalPayment.fromAmount

object

Show child attributes

data.originalPayment.fromAmount.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.originalPayment.fromAmount.currency

enum<string>

required

Currency code.

Available options:

USD,

EUR,

MXN,

SGD,

BRL

data.originalPayment.description

enum<string>

Enumerated description of the payment.

Available options:

Payment

data.originalPayment.captured

boolean

Determines if a payment has successfully been captured. This property is only present for payments that did not use auto capture.

data.originalPayment.captureAmount

object

Show child attributes

data.originalPayment.captureAmount.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.originalPayment.captureAmount.currency

enum<string>

required

Currency code.

Available options:

USD

data.originalPayment.captureDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.originalPayment.requiredAction

object

When the payment status is action_required, this object summarizes the required additional steps.

Show child attributes

data.originalPayment.requiredAction.type

enum<string>

required

The type of action that is required to proceed with the payment. Currently only one type is supported.

Available options:

three_d_secure_required

data.originalPayment.requiredAction.redirectUrl

string

required

The URL to bring the user to in order to complete the payment.

Example:

"https://example.org"

data.originalPayment.cancel

object

Status information of the related cancel. This property is only present on canceled payment or refund items.

Show child attributes

data.originalPayment.cancel.id

string<uuid>

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.originalPayment.cancel.type

enum<string>

Type of the payment object.

Available options:

cancel

data.originalPayment.cancel.description

enum<string> | null

Enumerated description of the payment item.

Available options:

Payment

data.originalPayment.cancel.status

enum<string>

Available options:

pending,

confirmed,

paid,

failed

data.originalPayment.cancel.createDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.originalPayment.refunds

object[]

Show child attributes

data.originalPayment.refunds.id

string<uuid>

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.originalPayment.refunds.type

enum<string>

Type of the payment object.

Available options:

payment,

refund

data.originalPayment.refunds.amount

object

Show child attributes

data.originalPayment.refunds.amount.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.originalPayment.refunds.amount.currency

enum<string>

required

Currency code.

Available options:

USD

data.originalPayment.refunds.description

enum<string> | null

Enumerated description of the payment item.

Available options:

Payment

data.originalPayment.refunds.status

enum<string>

Available options:

pending,

confirmed,

paid,

failed,

action_required

data.originalPayment.refunds.requiredAction

object

When the payment status is action_required, this object summarizes the required additional steps.

Show child attributes

data.originalPayment.refunds.requiredAction.type

enum<string>

required

The type of action that is required to proceed with the payment. Currently only one type is supported.

Available options:

three_d_secure_required

data.originalPayment.refunds.requiredAction.redirectUrl

string

required

The URL to bring the user to in order to complete the payment.

Example:

"https://example.org"

data.originalPayment.refunds.fees

object

Show child attributes

data.originalPayment.refunds.fees.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.originalPayment.refunds.fees.currency

enum<string>

required

Currency code.

Available options:

USD

data.originalPayment.refunds.createDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.originalPayment.fees

object

Show child attributes

data.originalPayment.fees.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.originalPayment.fees.currency

enum<string>

required

Currency code.

Available options:

USD

data.originalPayment.channel

string<uuid>

The channel identifier that can be set for the payment. When not provided, the default channel is used.

Example:

"ba943ff1-ca16-49b2-ba55-1057e70ca5c7"

data.originalPayment.createDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.originalPayment.updateDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.cancel

object

Status information of the related cancel. This property is only present on canceled payment or refund items.

Show child attributes

data.cancel.id

string<uuid>

required

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.cancel.type

enum<string>

required

Type of the payment object.

Available options:

cancel

data.cancel.merchantId

string<uuid>

required

Unique system generated identifier for the merchant.

Example:

"fc988ed5-c129-4f70-a064-e5beb7eb8e32"

data.cancel.amount

object

required

Show child attributes

data.cancel.amount.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.cancel.amount.currency

enum<string>

required

Currency code.

Available options:

USD

data.cancel.source

object

required

The payment source.

Show child attributes

data.cancel.source.id

string<uuid>

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.cancel.source.type

enum<string>

Type of the source.

Available options:

card,

ach,

wire,

sepa

data.cancel.status

enum<string>

required

Available options:

pending,

confirmed,

paid,

failed

data.cancel.merchantWalletId

string

Unique system generated identifier for the wallet of the merchant.

Maximum string length: 36

Example:

"212000"

data.cancel.description

enum<string>

Enumerated description of the payment.

Available options:

Payment

data.cancel.originalPayment

object

Status information of the related payment. This property is only present on refund or cancel items.

Show child attributes

data.cancel.originalPayment.id

string<uuid>

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.cancel.originalPayment.type

enum<string>

Type of the payment object.

Available options:

payment,

refund

data.cancel.originalPayment.amount

object

Show child attributes

data.cancel.originalPayment.amount.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.cancel.originalPayment.amount.currency

enum<string>

required

Currency code.

Available options:

USD

data.cancel.originalPayment.description

enum<string> | null

Enumerated description of the payment item.

Available options:

Payment

data.cancel.originalPayment.status

enum<string>

Available options:

pending,

confirmed,

paid,

failed,

action_required

data.cancel.originalPayment.requiredAction

object

When the payment status is action_required, this object summarizes the required additional steps.

Show child attributes

data.cancel.originalPayment.requiredAction.type

enum<string>

required

The type of action that is required to proceed with the payment. Currently only one type is supported.

Available options:

three_d_secure_required

data.cancel.originalPayment.requiredAction.redirectUrl

string

required

The URL to bring the user to in order to complete the payment.

Example:

"https://example.org"

data.cancel.originalPayment.fees

object

Show child attributes

data.cancel.originalPayment.fees.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.cancel.originalPayment.fees.currency

enum<string>

required

Currency code.

Available options:

USD

data.cancel.originalPayment.createDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.cancel.fees

object

Show child attributes

data.cancel.fees.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.cancel.fees.currency

enum<string>

required

Currency code.

Available options:

USD

data.cancel.channel

string<uuid>

The channel identifier that can be set for the payment. When not provided, the default channel is used.

Example:

"ba943ff1-ca16-49b2-ba55-1057e70ca5c7"

data.cancel.createDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.cancel.updateDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.refunds

object[] | null

Show child attributes

data.refunds.id

string<uuid>

required

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.refunds.type

enum<string>

required

Type of the payment object.

Available options:

refund

data.refunds.merchantId

string<uuid>

required

Unique system generated identifier for the merchant.

Example:

"fc988ed5-c129-4f70-a064-e5beb7eb8e32"

data.refunds.amount

object

required

Show child attributes

data.refunds.amount.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.refunds.amount.currency

enum<string>

required

Currency code.

Available options:

USD

data.refunds.source

object

required

The payment source.

Show child attributes

data.refunds.source.id

string<uuid>

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.refunds.source.type

enum<string>

Type of the source.

Available options:

card,

ach,

wire,

sepa

data.refunds.status

enum<string>

required

Available options:

pending,

confirmed,

paid,

failed

data.refunds.merchantWalletId

string

Unique system generated identifier for the wallet of the merchant.

Maximum string length: 36

Example:

"212000"

data.refunds.description

enum<string>

Enumerated description of the payment.

Available options:

Payment

data.refunds.originalPayment

object

Status information of the related payment. This property is only present on refund or cancel items.

Show child attributes

data.refunds.originalPayment.id

string<uuid>

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.refunds.originalPayment.type

enum<string>

Type of the payment object.

Available options:

payment,

refund

data.refunds.originalPayment.amount

object

Show child attributes

data.refunds.originalPayment.amount.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.refunds.originalPayment.amount.currency

enum<string>

required

Currency code.

Available options:

USD

data.refunds.originalPayment.description

enum<string> | null

Enumerated description of the payment item.

Available options:

Payment

data.refunds.originalPayment.status

enum<string>

Available options:

pending,

confirmed,

paid,

failed,

action_required

data.refunds.originalPayment.requiredAction

object

When the payment status is action_required, this object summarizes the required additional steps.

Show child attributes

data.refunds.originalPayment.requiredAction.type

enum<string>

required

The type of action that is required to proceed with the payment. Currently only one type is supported.

Available options:

three_d_secure_required

data.refunds.originalPayment.requiredAction.redirectUrl

string

required

The URL to bring the user to in order to complete the payment.

Example:

"https://example.org"

data.refunds.originalPayment.fees

object

Show child attributes

data.refunds.originalPayment.fees.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.refunds.originalPayment.fees.currency

enum<string>

required

Currency code.

Available options:

USD

data.refunds.originalPayment.createDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.refunds.cancel

object

Status information of the related cancel. This property is only present on canceled payment or refund items.

Show child attributes

data.refunds.cancel.id

string<uuid>

Unique system generated identifier for the entity.

Example:

"b8627ae8-732b-4d25-b947-1df8f4007a29"

data.refunds.cancel.type

enum<string>

Type of the payment object.

Available options:

cancel

data.refunds.cancel.description

enum<string> | null

Enumerated description of the payment item.

Available options:

Payment

data.refunds.cancel.status

enum<string>

Available options:

pending,

confirmed,

paid,

failed

data.refunds.cancel.createDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.refunds.fees

object

Show child attributes

data.refunds.fees.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.refunds.fees.currency

enum<string>

required

Currency code.

Available options:

USD

data.refunds.channel

string<uuid>

The channel identifier that can be set for the payment. When not provided, the default channel is used.

Example:

"ba943ff1-ca16-49b2-ba55-1057e70ca5c7"

data.refunds.createDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.refunds.updateDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.fees

object

Show child attributes

data.fees.amount

string

required

Magnitude of the amount, in units of the currency, with a ..

Example:

"3.14"

data.fees.currency

enum<string>

required

Currency code.

Available options:

USD

data.trackingRef

string | null

Payment tracking reference. Will be present once known.

Example:

"24910599141085313498894"

data.externalRef

string

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

Examples:

Input/Output Message Accountability Data (IMAD/OMAD): unique number given to each FedWire payment when using the Federal Reserve Bank Service which can be used to investigate and track wire transfers.

Example:

"YYYYMMDDXXXXXXXX012345"

data.errorCode

enum<string> | null

Indicates the failure reason of a payment. Only present for payments in failed state. Possible values are [payment_failed, payment_fraud_detected, payment_denied, payment_not_supported_by_issuer, payment_not_funded, payment_unprocessable, payment_stopped_by_issuer, payment_canceled, payment_returned, payment_failed_balance_check, card_failed, card_invalid, card_address_mismatch, card_zip_mismatch, card_cvv_invalid, card_expired, card_limit_violated, card_not_honored, card_cvv_required, credit_card_not_allowed, card_account_ineligible, card_network_unsupported, channel_invalid, unauthorized_transaction, bank_account_ineligible, bank_transaction_error, invalid_account_number, invalid_wire_rtn, invalid_ach_rtn, vendor_inactive]'

Available options:

payment_failed,

payment_fraud_detected,

payment_denied,

payment_not_supported_by_issuer,

payment_not_funded,

payment_unprocessable,

payment_stopped_by_issuer,

payment_canceled,

payment_returned,

payment_failed_balance_check,

card_failed,

card_invalid,

card_address_mismatch,

card_zip_mismatch,

card_cvv_invalid,

card_expired,

card_limit_violated,

card_not_honored,

card_cvv_required,

card_restricted,,

card_account_ineligible,

card_network_unsupported,

channel_invalid,

unauthorized_transaction,

bank_account_ineligible,

bank_transaction_error,

invalid_account_number,

invalid_wire_rtn,

invalid_ach_rtn,

ref_id_invalid,

account_name_mismatch,

account_number_mismatch,

account_ineligible,

wallet_address_mismatch,

customer_name_mismatch,

institution_name_mismatch,

vendor_inactive

data.metadata

object

Show child attributes

data.metadata.email

string

required

Email of the user.

Maximum string length: 1024

Example:

"satoshi@circle.com"

data.metadata.phoneNumber

string

Phone number of the user in E.164 format. We recommend using a library such as libphonenumber to parse and validate phone numbers.

Maximum string length: 16

Example:

"+14155555555"

data.channel

string<uuid>

The channel identifier that can be set for the payment. When not provided, the default channel is used.

Example:

"ba943ff1-ca16-49b2-ba55-1057e70ca5c7"

data.riskEvaluation

object

Results of risk evaluation. Only present if the payment is denied by Circle's risk service.

Show child attributes

data.riskEvaluation.decision

enum<string>

Enumerated decision of the account.

Available options:

approved,

denied,

review

data.riskEvaluation.reason

string | null

Risk reason for the definitive decision outcome.

Example:

"3000"

data.createDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

data.updateDate

string

ISO-8601 UTC date/time format.

Example:

"2020-04-10T02:13:30.000Z"

Core API

API Overview

Crypto Deposits API

Crypto Payouts API

Cross-Currency API

Reserve Management API

Authorizations

Path Parameters

Response