createPayment

Circle Mint

Core Functionality

Balances

Payouts

Wires

CBIT

PIX

Transfers

Addresses

Deposits

Accounts API

Wallets

Transfers

API Overview

Health

Management

Encryption

Subscriptions

Stablecoins

Channels

Payments API

Payments

Pull Crypto Payments

Crypto Payment Intents

Cards

Payment Tokens

Settlements

Chargebacks

Balances

Checkout Sessions

Payouts API

Payouts

Crypto Address Book

Crypto Exchange Rates

Create a payment

POSThttps://api.circle.com/v1/payments

Body parameters

source

object

Required

verification

string

Required

Indicates the verification method for this payment.

amount

object

Required

metadata

object

Required

idempotencyKey

uuid

Required

Universally unique identifier (UUID v4) idempotency key. This key is utilized to ensure exactly-once execution of mutating requests.

keyId

uuid

Universally unique identifier (UUID v4) of the public key used in encryption. NOTE the sandbox environment uses the default value of key1. For this reason the example supplied is key1 rather than a UUID.

autoCapture

boolean

Triggers the automatic capture of the full payment amount. If set to false the payment will only be authorized but not captured.

verificationSuccessUrl

url

The URL to redirect users to after successful 3DS authentication.

verificationFailureUrl

url

The URL to redirect users to after failed 3DS authentication.

description

string

Description of the payment with length restriction of 240 characters.

encryptedData

byte

PGP encrypted base64 encoded string. Contains CVV.

CVV (Card Verification Number): Three or four digit security code. Only required if verification is cvv.

channel

uuid

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

Response

201CreatePaymentResponse

Response Body

object

data

object

Show 23 properties

string

Required

Unique system generated identifier for the entity.

type

string

Required

Type of the payment object.

merchantId

string

Required

Unique system generated identifier for the merchant.

merchantWalletId

string

Unique system generated identifier for the wallet of the merchant.

amount

object

Required

Show 2 properties

source

object

Required

The payment source.

Show 2 properties

description

string

Enumerated description of the payment.

status

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.

captured

boolean

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

captureAmount

object

Show 2 properties

captureDate

string

ISO-8601 UTC date/time format.

requiredAction

object

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

Show 2 properties

verification

object

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

Show 4 properties

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.

cvv

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.

threeDSecure

string

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

eci

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.

cancel

object

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

Show 13 properties

string

Required

Unique system generated identifier for the entity.

type

string

Required

Type of the payment object.

merchantId

string

Required

Unique system generated identifier for the merchant.

merchantWalletId

string

Unique system generated identifier for the wallet of the merchant.

amount

object

Required

Show 2 properties

source

object

Required

The payment source.

Show 2 properties

description

string

Enumerated description of the payment.

status

string

Required

originalPayment

object

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

Show 8 properties

string

Unique system generated identifier for the entity.

type

string

Type of the payment object.

amount

object

Show 2 properties

description

string

Enumerated description of the payment item.

status

string

requiredAction

object

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

Show 2 properties

fees

object

Show 2 properties

createDate

string

ISO-8601 UTC date/time format.

fees

object

Show 2 properties

channel

string

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

createDate

string

ISO-8601 UTC date/time format.

updateDate

string

ISO-8601 UTC date/time format.

refunds

array of objects

Show 14 properties

string

Required

Unique system generated identifier for the entity.

type

string

Required

Type of the payment object.

merchantId

string

Required

Unique system generated identifier for the merchant.

merchantWalletId

string

Unique system generated identifier for the wallet of the merchant.

amount

object

Required

Show 2 properties

source

object

Required

The payment source.

Show 2 properties

description

string

Enumerated description of the payment.

status

string

Required

originalPayment

object

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

Show 8 properties

string

Unique system generated identifier for the entity.

type

string

Type of the payment object.

amount

object

Show 2 properties

description

string

Enumerated description of the payment item.

status

string

requiredAction

object

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

Show 2 properties

fees

object

Show 2 properties

createDate

string

ISO-8601 UTC date/time format.

cancel

object

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

Show 5 properties

string

Unique system generated identifier for the entity.

type

string

Type of the payment object.

description

string

Enumerated description of the payment item.

status

string

createDate

string

ISO-8601 UTC date/time format.

fees

object

Show 2 properties

channel

string

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

createDate

string

ISO-8601 UTC date/time format.

updateDate

string

ISO-8601 UTC date/time format.

fees

object

Show 2 properties

trackingRef

string

Payment tracking reference. Will be present once known.

errorCode

string

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]'

metadata

object

Show 2 properties

riskEvaluation

object

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

Show 2 properties

channel

string

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

createDate

string

ISO-8601 UTC date/time format.

updateDate

string

ISO-8601 UTC date/time format.

400BadRequest

401NotAuthorized

404NotFound

RequestChoose a language

ResponseChoose an example

1{
2  "data": {
3    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
4    "type": "payment",
5    "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
6    "merchantWalletId": "212000",
7    "amount": {
8      "amount": "3.14",
9      "currency": "USD"
10    },
11    "source": {
12      "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
13      "type": "card"
14    },
15    "description": "Payment",
16    "status": "pending",
17    "captured": false,
18    "captureAmount": {
19      "amount": "3.14",
20      "currency": "USD"
21    },
22    "captureDate": "2020-04-10T02:13:30.000Z",
23    "requiredAction": {
24      "type": "three_d_secure_required",
25      "redirectUrl": "https://example.org"
26    },
27    "verification": {
28      "avs": "D",
29      "cvv": "not_requested",
30      "threeDSecure": "pass",
31      "eci": "00"
32    },
33    "cancel": {
34      "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
35      "type": "cancel",
36      "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
37      "merchantWalletId": "212000",
38      "amount": {
39        "amount": "3.14",
40        "currency": "USD"
41      },
42      "source": {
43        "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
44        "type": "card"
45      },
46      "description": "Payment",
47      "status": "pending",
48      "originalPayment": {
49        "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
50        "type": "payment",
51        "amount": {
52          "amount": "3.14",
53          "currency": "USD"
54        },
55        "description": "Payment",
56        "status": "pending",
57        "requiredAction": {
58          "type": "three_d_secure_required",
59          "redirectUrl": "https://example.org"
60        },
61        "fees": {
62          "amount": "3.14",
63          "currency": "USD"
64        },
65        "createDate": "2020-04-10T02:13:30.000Z"
66      },
67      "fees": {
68        "amount": "3.14",
69        "currency": "USD"
70      },
71      "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
72      "createDate": "2020-04-10T02:13:30.000Z",
73      "updateDate": "2020-04-10T02:13:30.000Z"
74    },
75    "refunds": [
76      {
77        "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
78        "type": "refund",
79        "merchantId": "fc988ed5-c129-4f70-a064-e5beb7eb8e32",
80        "merchantWalletId": "212000",
81        "amount": {
82          "amount": "3.14",
83          "currency": "USD"
84        },
85        "source": {
86          "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
87          "type": "card"
88        },
89        "description": "Payment",
90        "status": "pending",
91        "originalPayment": {
92          "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
93          "type": "payment",
94          "amount": {
95            "amount": "3.14",
96            "currency": "USD"
97          },
98          "description": "Payment",
99          "status": "pending",
100          "requiredAction": {
101            "type": "three_d_secure_required",
102            "redirectUrl": "https://example.org"
103          },
104          "fees": {
105            "amount": "3.14",
106            "currency": "USD"
107          },
108          "createDate": "2020-04-10T02:13:30.000Z"
109        },
110        "cancel": {
111          "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
112          "type": "cancel",
113          "description": "Payment",
114          "status": "pending",
115          "createDate": "2020-04-10T02:13:30.000Z"
116        },
117        "fees": {
118          "amount": "3.14",
119          "currency": "USD"
120        },
121        "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
122        "createDate": "2020-04-10T02:13:30.000Z",
123        "updateDate": "2020-04-10T02:13:30.000Z"
124      }
125    ],
126    "fees": {
127      "amount": "3.14",
128      "currency": "USD"
129    },
130    "trackingRef": "24910599141085313498894",
131    "errorCode": "payment_failed",
132    "metadata": {
133      "email": "[email protected]",
134      "phoneNumber": "+14155555555"
135    },
136    "riskEvaluation": {
137      "decision": "approved",
138      "reason": "3000"
139    },
140    "channel": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
141    "createDate": "2020-04-10T02:13:30.000Z",
142    "updateDate": "2020-04-10T02:13:30.000Z"
143  }
144}

Did this page help you?

Developer Terms Service Terms Privacy Policy Acceptable Use Your Privacy Choices

Cookie Policy