Skip to main content
POST
/
v1
/
payouts
Create a payout
curl --request POST \
  --url https://api-sandbox.circle.com/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
  "destination": {
    "type": "address_book",
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
  },
  "amount": {
    "amount": "3.14"
  },
  "purposeOfTransfer": "PMT001",
  "metadata": {
    "customerExternalRef": "INV-2024-001234"
  }
}
'
import requests

url = "https://api-sandbox.circle.com/v1/payouts"

payload = {
"idempotencyKey": "ba943ff1-ca16-49b2-ba55-1057e70ca5c7",
"destination": {
"type": "address_book",
"id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
},
"amount": { "amount": "3.14" },
"purposeOfTransfer": "PMT001",
"metadata": { "customerExternalRef": "INV-2024-001234" }
}
headers = {
"Authorization": "Bearer <token>",
"Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)
const options = {
method: 'POST',
headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
body: JSON.stringify({
idempotencyKey: 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
destination: {type: 'address_book', id: 'b8627ae8-732b-4d25-b947-1df8f4007a29'},
amount: {amount: '3.14'},
purposeOfTransfer: 'PMT001',
metadata: {customerExternalRef: 'INV-2024-001234'}
})
};

fetch('https://api-sandbox.circle.com/v1/payouts', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));
<?php

$curl = curl_init();

curl_setopt_array($curl, [
CURLOPT_URL => "https://api-sandbox.circle.com/v1/payouts",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => json_encode([
'idempotencyKey' => 'ba943ff1-ca16-49b2-ba55-1057e70ca5c7',
'destination' => [
'type' => 'address_book',
'id' => 'b8627ae8-732b-4d25-b947-1df8f4007a29'
],
'amount' => [
'amount' => '3.14'
],
'purposeOfTransfer' => 'PMT001',
'metadata' => [
'customerExternalRef' => 'INV-2024-001234'
]
]),
CURLOPT_HTTPHEADER => [
"Authorization: Bearer <token>",
"Content-Type: application/json"
],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
package main

import (
"fmt"
"strings"
"net/http"
"io"
)

func main() {

url := "https://api-sandbox.circle.com/v1/payouts"

payload := strings.NewReader("{\n \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n \"destination\": {\n \"type\": \"address_book\",\n \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n },\n \"amount\": {\n \"amount\": \"3.14\"\n },\n \"purposeOfTransfer\": \"PMT001\",\n \"metadata\": {\n \"customerExternalRef\": \"INV-2024-001234\"\n }\n}")

req, _ := http.NewRequest("POST", url, payload)

req.Header.Add("Authorization", "Bearer <token>")
req.Header.Add("Content-Type", "application/json")

res, _ := http.DefaultClient.Do(req)

defer res.Body.Close()
body, _ := io.ReadAll(res.Body)

fmt.Println(string(body))

}
HttpResponse<String> response = Unirest.post("https://api-sandbox.circle.com/v1/payouts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n \"destination\": {\n \"type\": \"address_book\",\n \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n },\n \"amount\": {\n \"amount\": \"3.14\"\n },\n \"purposeOfTransfer\": \"PMT001\",\n \"metadata\": {\n \"customerExternalRef\": \"INV-2024-001234\"\n }\n}")
.asString();
require 'uri'
require 'net/http'

url = URI("https://api-sandbox.circle.com/v1/payouts")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n \"idempotencyKey\": \"ba943ff1-ca16-49b2-ba55-1057e70ca5c7\",\n \"destination\": {\n \"type\": \"address_book\",\n \"id\": \"b8627ae8-732b-4d25-b947-1df8f4007a29\"\n },\n \"amount\": {\n \"amount\": \"3.14\"\n },\n \"purposeOfTransfer\": \"PMT001\",\n \"metadata\": {\n \"customerExternalRef\": \"INV-2024-001234\"\n }\n}"

response = http.request(request)
puts response.read_body
{
  "data": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "sourceWalletId": "53535335",
    "destination": {
      "type": "address_book",
      "id": "b8627ae8-732b-4d25-b947-1df8f4007a29"
    },
    "amount": {
      "amount": "3.14",
      "currency": "USD"
    },
    "toAmount": {
      "amount": "3.14",
      "currency": "ETH"
    },
    "fees": {
      "amount": "3.14",
      "currency": "USD"
    },
    "networkFees": {
      "amount": "0.14",
      "currency": "USD"
    },
    "purposeOfTransfer": "PMT001",
    "customerExternalRef": "customer-ref-123",
    "status": "pending",
    "errorCode": "transaction_denied",
    "riskEvaluation": {
      "decision": "denied",
      "reason": "4000"
    },
    "createDate": "2020-04-10T02:13:30.000Z",
    "updateDate": "2020-04-10T02:13:30.000Z"
  }
}
{
"code": 400,
"message": "Bad request."
}
{
"code": 401,
"message": "Malformed authorization."
}

Authorizations

Authorization
string
header
required

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

Body

application/json

For Circle entities other than CIRCLE_SG.

idempotencyKey
string<uuid>
required

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

Example:

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

destination
object
required

The destination.

amount
object
required
source
object

A source wallet location.

toAmount
object
purposeOfTransfer
enum<string>

Payment reason code for the payout. Aligned with Circle payment reason codes for Crypto Payouts. Do not use PMT006. See Crypto Payouts payment reason codes.

Invalid values can return error code 5020.

Available options:
PMT000,
PMT001,
PMT002,
PMT003,
PMT004,
PMT005,
PMT007,
PMT008,
PMT009,
PMT010,
PMT011,
PMT012,
PMT013,
PMT014,
PMT015,
PMT016,
PMT017,
PMT018,
PMT019,
PMT020,
PMT021,
PMT022,
PMT023,
PMT024,
PMT025,
PMT026,
PMT027,
PMT028,
PMT029,
PMT030
Example:

"PMT001"

metadata
object

Additional properties related to the crypto payout.

Response

Successfully created a payout.

data
object

Payout resource returned by create and get operations. Includes purposeOfTransfer when it was provided at create time (required for CIRCLE_SG entities).