API Reference

Create a payout

posthttps://api-sandbox.circle.com/v1/payouts

Reference
Playground

Create a crypto payout.

The following table includes the supported pairs of amount.currency and toAmount.currency for address book payouts:

amount.currency	toAmount.currency
USD	USD
EUR	EUR

amount.currency

toAmount.currency

USD

EUR

Body parameters

amount

object

Required

Show 2 properties

amount

string

Required

The numeric value of the amount, expressed in units of the specified currency. Use a period (.) as the decimal separator.

currency

string

Required

The ISO 4217 currency code for the amount.

Allowed valuesUSDEUR

destination

object

Required

The destination.

Show 2 properties

type

string

Required

The destination type.

Allowed valuesaddress_book

string

Required

Unique system generated identifier for the entity.

idempotencyKey

string

Required

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

source

object

A source wallet location.

Show 3 properties

type

string

Required

Allowed valueswallet

string

Required

The id of the wallet.

identities

array of objects

Show 3 properties

type

string

Required

The type of identity for the originator.

individual - A uniquely distinguishable individual.
business - Any entity other than a natural person that can establish a permanent customer relationship with an affected entity or otherwise own property. This can include companies, foundations, anstalt, partnerships, associations and other relevantly similar entities.

Allowed valuesindividualbusiness

name

string

Required

Full name of the identity.

addresses

array of objects

Required

Show 6 properties

line1

string

Required

Line one of the street address.

line2

string

Line two of the street address.

city

string

Required

City portion of the address.

district

string

Required

State / County / Province / Region portion of the address. If the country is US or Canada, then district is required and should use the two-letter code for the subdivision.

postalCode

string

Required

Postal / ZIP code of the address.

country

string

Required

Country portion of the address. Formatted as a two-letter country code specified in ISO 3166-1 alpha-2.

toAmount

object

Show 2 properties

amount

string

Required

The numeric value of the amount, expressed in units of the specified currency. Use a period (.) as the decimal separator.

currency

string

Required

The ISO 4217 currency code for the amount.

Allowed valuesUSDEUR

Response

201CreatePayoutResponse

Response Body

object

data

object

Show 12 properties

string

Unique system generated identifier for the entity.

sourceWalletId

string

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

destination

object

The destination.

Show 2 properties

type

string

Required

The destination type.

Allowed valuesaddress_book

string

Required

Unique system generated identifier for the entity.

amount

object

Show 2 properties

amount

string

Required

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

currency

string

Required

Currency code for the amount.

Allowed valuesUSDEURBTCETHMTCFLWMAN

toAmount

object

Show 2 properties

amount

string

Required

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

currency

string

Required

Currency code for the amount.

Allowed valuesUSDEURBTCETHMTCFLWMAN

fees

object

Show 2 properties

amount

string

Required

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

currency

string

Required

Currency code for the amount.

Allowed valuesUSDEURBTCETHMTCFLWMAN

networkFees

object

Show 2 properties

amount

string

Required

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

currency

string

Required

Currency code for the amount.

Allowed valuesUSDEURBTCETHMTCFLWMAN

status

string

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

Allowed valuespendingcompletefailed

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, transaction_returned, bank_transaction_error, fiat_account_limit_exceeded, invalid_bank_account_number, invalid_ach_rtn, invalid_wire_rtn, vendor_inactive]'

Allowed valuesinsufficient_fundstransaction_deniedtransaction_failedtransaction_returnedbank_transaction_errorfiat_account_limit_exceededinvalid_bank_account_numberinvalid_ach_rtninvalid_wire_rtnvendor_inactive

riskEvaluation

object

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

Show 2 properties

decision

string

Enumerated decision of the account.

Allowed valuesapproveddeniedreview

reason

string

Risk reason for the definitive decision outcome.

createDate

string

ISO-8601 UTC date/time format.

updateDate

string

ISO-8601 UTC date/time format.

400BadRequest

401NotAuthorized

RequestChoose a language

ResponseChoose an example

1{
2  "data": {
3    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
4    "sourceWalletId": "53535335",
5    "destination": {
6      "type": "address_book",
7      "id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
8    },
9    "amount": {
10      "amount": "3.14",
11      "currency": "USD"
12    },
13    "toAmount": {
14      "amount": "3.14",
15      "currency": "USD"
16    },
17    "fees": {
18      "amount": "3.14",
19      "currency": "USD"
20    },
21    "networkFees": {
22      "amount": "3.14",
23      "currency": "USD"
24    },
25    "status": "pending",
26    "errorCode": "insufficient_funds",
27    "riskEvaluation": {
28      "decision": "approved",
29      "reason": "3000"
30    },
31    "createDate": "2020-04-10T02:13:30.000Z",
32    "updateDate": "2020-04-10T02:13:30.000Z"
33  }
34}

Did this page help you?

Developer Terms Service Terms Privacy Policy Acceptable Use Your Privacy Choices

Cookie Policy