Create a Payout Intent
curl --request POST \
--url https://api.usecleff.com/v1/payouts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount_minor": 123,
"currency": "<string>",
"destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotency_key": "<string>",
"external_ref": "<string>",
"validator_strategy": "manual",
"replaces_payout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"via": {}
}
'import requests
url = "https://api.usecleff.com/v1/payouts"
payload = {
"beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount_minor": 123,
"currency": "<string>",
"destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotency_key": "<string>",
"external_ref": "<string>",
"validator_strategy": "manual",
"replaces_payout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"via": {}
}
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({
beneficiary_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
amount_minor: 123,
currency: '<string>',
destination_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
bank_account_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
idempotency_key: '<string>',
external_ref: '<string>',
validator_strategy: 'manual',
replaces_payout_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
via: {}
})
};
fetch('https://api.usecleff.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.usecleff.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([
'beneficiary_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'amount_minor' => 123,
'currency' => '<string>',
'destination_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'bank_account_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'idempotency_key' => '<string>',
'external_ref' => '<string>',
'validator_strategy' => 'manual',
'replaces_payout_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'via' => [
]
]),
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.usecleff.com/v1/payouts"
payload := strings.NewReader("{\n \"beneficiary_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount_minor\": 123,\n \"currency\": \"<string>\",\n \"destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"bank_account_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\",\n \"external_ref\": \"<string>\",\n \"validator_strategy\": \"manual\",\n \"replaces_payout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"via\": {}\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.usecleff.com/v1/payouts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"beneficiary_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount_minor\": 123,\n \"currency\": \"<string>\",\n \"destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"bank_account_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\",\n \"external_ref\": \"<string>\",\n \"validator_strategy\": \"manual\",\n \"replaces_payout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"via\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usecleff.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 \"beneficiary_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount_minor\": 123,\n \"currency\": \"<string>\",\n \"destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"bank_account_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\",\n \"external_ref\": \"<string>\",\n \"validator_strategy\": \"manual\",\n \"replaces_payout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"via\": {}\n}"
response = http.request(request)
puts response.read_body{
"payout": {
"id": "<string>",
"state": "pending_approval",
"status": "needs_approval",
"delivered_at": "2023-11-07T05:31:56Z",
"beneficiary_id": "<string>",
"destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"destination_kind": "bank",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount_minor": 123,
"purpose_of_payment": "advertising",
"currency": "<string>",
"external_ref": "<string>",
"idempotency_key": "<string>",
"validator_strategy": "manual",
"environment": "sandbox",
"provider": "<string>",
"provider_payout_id": "<string>",
"rail": "ach",
"rail_ref": "<string>",
"replaces_payout_id": "<string>",
"failure_code": "insufficient_funds",
"failure_detail": "<string>",
"fault": "business",
"replaceable": true,
"created_at": "2023-11-07T05:31:56Z",
"beneficiary_name": {},
"beneficiary_type": "person",
"via": {}
}
}{
"error": {
"code": "validation_failed",
"message": "Request validation failed",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"details": [
{
"field": "amount_minor",
"code": "not_positive_integer",
"message": "amount_minor must be a positive number"
}
],
"docs_url": "https://docs.usecleff.com/errors#validation_failed"
}
}{
"error": {
"code": "unauthorized",
"message": "Unauthorized",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": null,
"docs_url": "https://docs.usecleff.com/errors#unauthorized"
}
}{
"error": {
"code": "forbidden",
"message": "Forbidden resource",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_read_only",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#forbidden"
}
}{
"error": {
"code": "BANK_ACCOUNT_NOT_FOUND",
"message": "BankAccount 9b2f4c1e-5d7a-4e8b-a3c6-1f0d2e4b6a8c not found",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#bank_account_not_found"
}
}{
"error": {
"code": "IDEMPOTENCY_CONFLICT",
"message": "idempotency_key was already used for a request describing something else; send a new idempotency_key or resend the original request unchanged",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#idempotency_conflict"
}
}{
"error": {
"code": "SANDBOX_WALLET_UNFUNDED",
"message": "Your sandbox wallet has no balance. Complete your business profile to fund it with test money.",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#sandbox_wallet_unfunded"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Slow down and retry after the window.",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": null,
"docs_url": "https://docs.usecleff.com/errors#rate_limited"
}
}Payouts
Create a Payout
Creates a Payout in pending_approval, where it waits for a Decision. Every request carries an idempotency key, so a retry returns the original Payout instead of creating a second one; see Idempotency. Each refusal and how to resolve it is listed on Errors.
POST
/
v1
/
payouts
Create a Payout Intent
curl --request POST \
--url https://api.usecleff.com/v1/payouts \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '
{
"beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount_minor": 123,
"currency": "<string>",
"destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotency_key": "<string>",
"external_ref": "<string>",
"validator_strategy": "manual",
"replaces_payout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"via": {}
}
'import requests
url = "https://api.usecleff.com/v1/payouts"
payload = {
"beneficiary_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount_minor": 123,
"currency": "<string>",
"destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"idempotency_key": "<string>",
"external_ref": "<string>",
"validator_strategy": "manual",
"replaces_payout_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"via": {}
}
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({
beneficiary_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
amount_minor: 123,
currency: '<string>',
destination_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
bank_account_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
idempotency_key: '<string>',
external_ref: '<string>',
validator_strategy: 'manual',
replaces_payout_id: '3c90c3cc-0d44-4b50-8888-8dd25736052a',
via: {}
})
};
fetch('https://api.usecleff.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.usecleff.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([
'beneficiary_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'amount_minor' => 123,
'currency' => '<string>',
'destination_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'bank_account_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'idempotency_key' => '<string>',
'external_ref' => '<string>',
'validator_strategy' => 'manual',
'replaces_payout_id' => '3c90c3cc-0d44-4b50-8888-8dd25736052a',
'via' => [
]
]),
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.usecleff.com/v1/payouts"
payload := strings.NewReader("{\n \"beneficiary_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount_minor\": 123,\n \"currency\": \"<string>\",\n \"destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"bank_account_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\",\n \"external_ref\": \"<string>\",\n \"validator_strategy\": \"manual\",\n \"replaces_payout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"via\": {}\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.usecleff.com/v1/payouts")
.header("Authorization", "Bearer <token>")
.header("Content-Type", "application/json")
.body("{\n \"beneficiary_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount_minor\": 123,\n \"currency\": \"<string>\",\n \"destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"bank_account_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\",\n \"external_ref\": \"<string>\",\n \"validator_strategy\": \"manual\",\n \"replaces_payout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"via\": {}\n}")
.asString();require 'uri'
require 'net/http'
url = URI("https://api.usecleff.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 \"beneficiary_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"amount_minor\": 123,\n \"currency\": \"<string>\",\n \"destination_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"bank_account_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"idempotency_key\": \"<string>\",\n \"external_ref\": \"<string>\",\n \"validator_strategy\": \"manual\",\n \"replaces_payout_id\": \"3c90c3cc-0d44-4b50-8888-8dd25736052a\",\n \"via\": {}\n}"
response = http.request(request)
puts response.read_body{
"payout": {
"id": "<string>",
"state": "pending_approval",
"status": "needs_approval",
"delivered_at": "2023-11-07T05:31:56Z",
"beneficiary_id": "<string>",
"destination_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"destination_kind": "bank",
"bank_account_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"amount_minor": 123,
"purpose_of_payment": "advertising",
"currency": "<string>",
"external_ref": "<string>",
"idempotency_key": "<string>",
"validator_strategy": "manual",
"environment": "sandbox",
"provider": "<string>",
"provider_payout_id": "<string>",
"rail": "ach",
"rail_ref": "<string>",
"replaces_payout_id": "<string>",
"failure_code": "insufficient_funds",
"failure_detail": "<string>",
"fault": "business",
"replaceable": true,
"created_at": "2023-11-07T05:31:56Z",
"beneficiary_name": {},
"beneficiary_type": "person",
"via": {}
}
}{
"error": {
"code": "validation_failed",
"message": "Request validation failed",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"details": [
{
"field": "amount_minor",
"code": "not_positive_integer",
"message": "amount_minor must be a positive number"
}
],
"docs_url": "https://docs.usecleff.com/errors#validation_failed"
}
}{
"error": {
"code": "unauthorized",
"message": "Unauthorized",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": null,
"docs_url": "https://docs.usecleff.com/errors#unauthorized"
}
}{
"error": {
"code": "forbidden",
"message": "Forbidden resource",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_read_only",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#forbidden"
}
}{
"error": {
"code": "BANK_ACCOUNT_NOT_FOUND",
"message": "BankAccount 9b2f4c1e-5d7a-4e8b-a3c6-1f0d2e4b6a8c not found",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#bank_account_not_found"
}
}{
"error": {
"code": "IDEMPOTENCY_CONFLICT",
"message": "idempotency_key was already used for a request describing something else; send a new idempotency_key or resend the original request unchanged",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#idempotency_conflict"
}
}{
"error": {
"code": "SANDBOX_WALLET_UNFUNDED",
"message": "Your sandbox wallet has no balance. Complete your business profile to fund it with test money.",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": {
"user_id": "usr_...",
"membership_id": "mem_...",
"role": "business_admin",
"environment": "sandbox"
},
"docs_url": "https://docs.usecleff.com/errors#sandbox_wallet_unfunded"
}
}{
"error": {
"code": "RATE_LIMITED",
"message": "Rate limit exceeded. Slow down and retry after the window.",
"request_id": "req_abc123",
"occurred_at": "2026-07-07T12:00:00.000Z",
"actor": null,
"docs_url": "https://docs.usecleff.com/errors#rate_limited"
}
}Agents: fetch this page as plain markdown at
https://docs.usecleff.com/api-reference/payouts-create.md.Authorizations
Cleff API key, created in the dashboard under Settings → API keys
Headers
Idempotency key for this Payout, scoped to (Business, environment) for 24h. Recommended over the idempotency_key body field; one of the two is required, and if both are sent they must match.
Body
application/json
Amount in minor units (e.g. cents). Max 9007199254740991 (2^53−1) to preserve JS integer precision.
Required range:
x <= 9007199254740991ISO 4217 currency code
Why the funds are being sent. Routefusion requires a purpose-of-payment on every transfer. Provisional corridor-agnostic set; coded values live behind the purpose-of-payment seam.
Available options:
advertising, advisor_fees, charity, education, family_support, investment, loan_repayment, medical, other, payroll, purchase_of_goods, purchase_of_services, real_estate, royalties, taxes, treasury, travel The Beneficiary's payout destination — a bank account or a card. Omit it to pay the destination the Beneficiary declared, or their only payout-usable one. Name one of the Beneficiary's destinations to pay that one instead, whether or not it is the declared one; the declaration does not change. A destination that cannot be paid is refused, never replaced by the declared one.
Deprecated spelling of destination_id, still accepted. If both are sent they must match.
Alternative to the Idempotency-Key header, which is recommended; one of the two is required, and if both are sent they must match. Scoped to (Business, environment); 24h short-circuit window. Resending the same request inside the window replays the original Payout (HTTP 200); reusing the key for a request naming different money is rejected with IDEMPOTENCY_CONFLICT (409).
Business-supplied reference (e.g. tradeId/jobId).
Override the per-Business default validator strategy for this Intent.
Available options:
manual Self-link to a previously-failed Payout this Intent is replacing. The predecessor must be in failed state, belong to the same Business, and not have been replaced already.
Channel metadata. The recorded channel always comes from the credential (session→dashboard, API key→api). Clients may declare { channel: 'sdk', sdkVersion? } or { channel: 'cli', cliVersion? }, which does not change the recorded channel; other channels are rejected.
Response
Show child attributes
Show child attributes