Skip to main content
POST
/
v1
/
payouts
Create one or multiple payouts
curl --request POST \
  --url https://api.example.com/v1/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": "100.50",
  "beneficiary": {
    "id": "cc82fa1d-fc7a-478c-a734-d3bce40464e7"
  },
  "clientRef": "PAYOUT-REF-12345",
  "currency": "EUR",
  "route": "sepa_inst",
  "comment": "Monthly salary payment",
  "description": "Payment for services rendered",
  "externalSenderId": "SENDER-123",
  "inputCurrency": "EUR",
  "invoiceId": "INV-2024-001",
  "purpose": "salary",
  "purposeOfPaymentDocumentKey": "pop-documents/cc82fa1d-fc7a-478c-a734-d3bce40464e7/9f1c.../invoice.pdf",
  "quoteId": "123e4567-e89b-12d3-a456-426614174000",
  "reference": "PAYOUT-2024-001",
  "senderInfo": {
    "address": "123 Main Street",
    "city": "New York",
    "companyName": "Acme Trading Ltd",
    "country": "US",
    "dateOfBirth": "1990-01-01",
    "firstName": "John",
    "lastName": "Doe",
    "phoneNumber": "+237650000000",
    "postalCode": "12345",
    "registrationNumber": "12345678",
    "type": "individual"
  }
}
'
import requests

url = "https://api.example.com/v1/payouts"

payload = {
    "amount": "100.50",
    "beneficiary": { "id": "cc82fa1d-fc7a-478c-a734-d3bce40464e7" },
    "clientRef": "PAYOUT-REF-12345",
    "currency": "EUR",
    "route": "sepa_inst",
    "comment": "Monthly salary payment",
    "description": "Payment for services rendered",
    "externalSenderId": "SENDER-123",
    "inputCurrency": "EUR",
    "invoiceId": "INV-2024-001",
    "purpose": "salary",
    "purposeOfPaymentDocumentKey": "pop-documents/cc82fa1d-fc7a-478c-a734-d3bce40464e7/9f1c.../invoice.pdf",
    "quoteId": "123e4567-e89b-12d3-a456-426614174000",
    "reference": "PAYOUT-2024-001",
    "senderInfo": {
        "address": "123 Main Street",
        "city": "New York",
        "companyName": "Acme Trading Ltd",
        "country": "US",
        "dateOfBirth": "1990-01-01",
        "firstName": "John",
        "lastName": "Doe",
        "phoneNumber": "+237650000000",
        "postalCode": "12345",
        "registrationNumber": "12345678",
        "type": "individual"
    }
}
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({
    amount: '100.50',
    beneficiary: {id: 'cc82fa1d-fc7a-478c-a734-d3bce40464e7'},
    clientRef: 'PAYOUT-REF-12345',
    currency: 'EUR',
    route: 'sepa_inst',
    comment: 'Monthly salary payment',
    description: 'Payment for services rendered',
    externalSenderId: 'SENDER-123',
    inputCurrency: 'EUR',
    invoiceId: 'INV-2024-001',
    purpose: 'salary',
    purposeOfPaymentDocumentKey: 'pop-documents/cc82fa1d-fc7a-478c-a734-d3bce40464e7/9f1c.../invoice.pdf',
    quoteId: '123e4567-e89b-12d3-a456-426614174000',
    reference: 'PAYOUT-2024-001',
    senderInfo: {
      address: '123 Main Street',
      city: 'New York',
      companyName: 'Acme Trading Ltd',
      country: 'US',
      dateOfBirth: '1990-01-01',
      firstName: 'John',
      lastName: 'Doe',
      phoneNumber: '+237650000000',
      postalCode: '12345',
      registrationNumber: '12345678',
      type: 'individual'
    }
  })
};

fetch('https://api.example.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.example.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([
    'amount' => '100.50',
    'beneficiary' => [
        'id' => 'cc82fa1d-fc7a-478c-a734-d3bce40464e7'
    ],
    'clientRef' => 'PAYOUT-REF-12345',
    'currency' => 'EUR',
    'route' => 'sepa_inst',
    'comment' => 'Monthly salary payment',
    'description' => 'Payment for services rendered',
    'externalSenderId' => 'SENDER-123',
    'inputCurrency' => 'EUR',
    'invoiceId' => 'INV-2024-001',
    'purpose' => 'salary',
    'purposeOfPaymentDocumentKey' => 'pop-documents/cc82fa1d-fc7a-478c-a734-d3bce40464e7/9f1c.../invoice.pdf',
    'quoteId' => '123e4567-e89b-12d3-a456-426614174000',
    'reference' => 'PAYOUT-2024-001',
    'senderInfo' => [
        'address' => '123 Main Street',
        'city' => 'New York',
        'companyName' => 'Acme Trading Ltd',
        'country' => 'US',
        'dateOfBirth' => '1990-01-01',
        'firstName' => 'John',
        'lastName' => 'Doe',
        'phoneNumber' => '+237650000000',
        'postalCode' => '12345',
        'registrationNumber' => '12345678',
        'type' => 'individual'
    ]
  ]),
  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.example.com/v1/payouts"

	payload := strings.NewReader("{\n  \"amount\": \"100.50\",\n  \"beneficiary\": {\n    \"id\": \"cc82fa1d-fc7a-478c-a734-d3bce40464e7\"\n  },\n  \"clientRef\": \"PAYOUT-REF-12345\",\n  \"currency\": \"EUR\",\n  \"route\": \"sepa_inst\",\n  \"comment\": \"Monthly salary payment\",\n  \"description\": \"Payment for services rendered\",\n  \"externalSenderId\": \"SENDER-123\",\n  \"inputCurrency\": \"EUR\",\n  \"invoiceId\": \"INV-2024-001\",\n  \"purpose\": \"salary\",\n  \"purposeOfPaymentDocumentKey\": \"pop-documents/cc82fa1d-fc7a-478c-a734-d3bce40464e7/9f1c.../invoice.pdf\",\n  \"quoteId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"reference\": \"PAYOUT-2024-001\",\n  \"senderInfo\": {\n    \"address\": \"123 Main Street\",\n    \"city\": \"New York\",\n    \"companyName\": \"Acme Trading Ltd\",\n    \"country\": \"US\",\n    \"dateOfBirth\": \"1990-01-01\",\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"phoneNumber\": \"+237650000000\",\n    \"postalCode\": \"12345\",\n    \"registrationNumber\": \"12345678\",\n    \"type\": \"individual\"\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.example.com/v1/payouts")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": \"100.50\",\n  \"beneficiary\": {\n    \"id\": \"cc82fa1d-fc7a-478c-a734-d3bce40464e7\"\n  },\n  \"clientRef\": \"PAYOUT-REF-12345\",\n  \"currency\": \"EUR\",\n  \"route\": \"sepa_inst\",\n  \"comment\": \"Monthly salary payment\",\n  \"description\": \"Payment for services rendered\",\n  \"externalSenderId\": \"SENDER-123\",\n  \"inputCurrency\": \"EUR\",\n  \"invoiceId\": \"INV-2024-001\",\n  \"purpose\": \"salary\",\n  \"purposeOfPaymentDocumentKey\": \"pop-documents/cc82fa1d-fc7a-478c-a734-d3bce40464e7/9f1c.../invoice.pdf\",\n  \"quoteId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"reference\": \"PAYOUT-2024-001\",\n  \"senderInfo\": {\n    \"address\": \"123 Main Street\",\n    \"city\": \"New York\",\n    \"companyName\": \"Acme Trading Ltd\",\n    \"country\": \"US\",\n    \"dateOfBirth\": \"1990-01-01\",\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"phoneNumber\": \"+237650000000\",\n    \"postalCode\": \"12345\",\n    \"registrationNumber\": \"12345678\",\n    \"type\": \"individual\"\n  }\n}")
  .asString();
require 'uri'
require 'net/http'

url = URI("https://api.example.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  \"amount\": \"100.50\",\n  \"beneficiary\": {\n    \"id\": \"cc82fa1d-fc7a-478c-a734-d3bce40464e7\"\n  },\n  \"clientRef\": \"PAYOUT-REF-12345\",\n  \"currency\": \"EUR\",\n  \"route\": \"sepa_inst\",\n  \"comment\": \"Monthly salary payment\",\n  \"description\": \"Payment for services rendered\",\n  \"externalSenderId\": \"SENDER-123\",\n  \"inputCurrency\": \"EUR\",\n  \"invoiceId\": \"INV-2024-001\",\n  \"purpose\": \"salary\",\n  \"purposeOfPaymentDocumentKey\": \"pop-documents/cc82fa1d-fc7a-478c-a734-d3bce40464e7/9f1c.../invoice.pdf\",\n  \"quoteId\": \"123e4567-e89b-12d3-a456-426614174000\",\n  \"reference\": \"PAYOUT-2024-001\",\n  \"senderInfo\": {\n    \"address\": \"123 Main Street\",\n    \"city\": \"New York\",\n    \"companyName\": \"Acme Trading Ltd\",\n    \"country\": \"US\",\n    \"dateOfBirth\": \"1990-01-01\",\n    \"firstName\": \"John\",\n    \"lastName\": \"Doe\",\n    \"phoneNumber\": \"+237650000000\",\n    \"postalCode\": \"12345\",\n    \"registrationNumber\": \"12345678\",\n    \"type\": \"individual\"\n  }\n}"

response = http.request(request)
puts response.read_body
{
  "amount": "100.50",
  "beneficiary": {
    "accounts": [
      {
        "createdAt": "2024-01-15T10:30:00Z",
        "currency": "EUR",
        "data": {
          "bic": "DEUTDEFF",
          "iban": "DE89370400440532013000"
        },
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "status": "active",
        "type": "iban",
        "updatedAt": "2024-01-15T10:35:00Z"
      }
    ],
    "createdAt": "2024-01-15T10:30:00Z",
    "email": "john.doe@example.com",
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "name": "John Doe",
    "status": "active",
    "updatedAt": "2024-01-15T10:35:00Z"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "currency": "EUR",
  "fee": "2.50",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "route": "international",
  "status": "processing",
  "type": "fiat",
  "updatedAt": "2024-01-15T10:35:00Z",
  "balanceAfter": "98.87",
  "clientRef": "PAYOUT-REF-12345",
  "completedAt": "2024-01-15T10:40:00Z",
  "description": "Payment for services rendered",
  "failureCategory": "payment_not_approved",
  "failureReason": "Insufficient funds",
  "fxRate": "970.87378641",
  "inputAmount": "1.13",
  "inputCurrency": "EUR",
  "payoutAccountData": {
    "account": 123456789,
    "bankCode": "044",
    "crAccount": "0123456789"
  },
  "payoutAccountId": "123e4567-e89b-12d3-a456-426614174000",
  "processedAt": "2024-01-15T10:32:00Z",
  "providerReference": "TXN123456789",
  "reference": "January invoice",
  "txHash": "0x3a1f9c2b4d5e6f70819a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70",
  "uetr": "4afd0a57-03af-4138-9341-373a78891ea9"
}
{
  "details": [
    {
      "field": "accounts.0.data.crAccount",
      "message": "crAccount must be exactly 10 digits for Nigerian accounts",
      "value": "12345678901"
    }
  ],
  "error": "BAD_REQUEST",
  "message": "Validation failed",
  "path": "/v1/beneficiaries",
  "statusCode": 400,
  "timestamp": "2024-01-15T10:30:00.000Z"
}

Authorizations

​
Authorization
string
header
required

Enter Auth0 JWT token

Headers

​
Idempotency-Key
string

Client-generated key scoped per workspace. A repeat with the same key and the same request body replays the original response without creating a second payout. A repeat with the same key and a different body is rejected (422). A repeat while the first request is still in flight returns a retryable 409. Keys expire 24 hours after the original request completes; a repeat after expiry is treated as a new request.

Body

application/json

Single payout object or array of payout objects

​
amount
string
required

Amount to be paid out (as string to avoid floating-point precision issues)

Pattern: ^[0-9]+(.[0-9]{1,8})?$
Example:

"100.50"

​
beneficiary
object
required

Beneficiary information. RECOMMENDED: Reference an existing beneficiary by providing just the ID (e.g., {"id": "uuid"}). Alternatively, provide the full beneficiary object with account details to create a new one inline.

Example:
{
  "id": "cc82fa1d-fc7a-478c-a734-d3bce40464e7"
}
​
clientRef
string
required

Client reference for idempotency (max 100 characters)

Maximum string length: 100
Example:

"PAYOUT-REF-12345"

​
currency
enum<string>
required

Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies.

Available options:
EUR,
USD,
GBP,
USDC,
USDT,
EURC,
NGN,
XOF,
XAF,
GHS,
ZMW,
MZN,
MWK,
EGP
Example:

"EUR"

​
route
enum<string>
required

Payment route to use

Available options:
sepa_inst,
sepa_credit,
bank_transfer,
ach,
fedwire,
swift,
crypto,
mobile_money
Example:

"sepa_inst"

​
comment
string

Comment for the payout

Maximum string length: 500
Example:

"Monthly salary payment"

​
description
string

Optional description of the payout (max 500 characters)

Maximum string length: 500
Example:

"Payment for services rendered"

​
externalSenderId
string

External sender (originator) reference. Used as the crypto Travel Rule originator id; defaults to your client id when omitted.

Maximum string length: 100
Example:

"SENDER-123"

​
inputCurrency
enum<string>

Input currency to debit from (optional). If provided, this currency will be used as the source for the payout. If not provided, the system will automatically select the currency with the largest available balance (balance minus pending transactions). Defaults to USD if no balances are found. Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies.

Available options:
EUR,
USD,
GBP,
USDC,
USDT,
EURC,
NGN,
XOF,
XAF,
GHS
Example:

"EUR"

​
invoiceId
string

Invoice ID associated with the payout

Maximum string length: 100
Example:

"INV-2024-001"

​
purpose
string

Purpose of the payout

Maximum string length: 100
Example:

"salary"

​
purposeOfPaymentDocumentKey
string

S3 key of the uploaded purpose-of-payment document. REQUIRED for SWIFT payouts. Obtain it from POST /v1/payouts/pop-documents/upload-url.

Maximum string length: 512
Example:

"pop-documents/cc82fa1d-fc7a-478c-a734-d3bce40464e7/9f1c.../invoice.pdf"

​
quoteId
string<uuid>

Cross-rate FX quote ID. Required for cross-currency payouts in supported corridors (e.g., NGN->GBP). Optional for same-currency payouts.

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
reference
string

Optional reference for the payout (max 140 characters)

Maximum string length: 140
Example:

"PAYOUT-2024-001"

​
senderInfo
object

Sender (originator) information. Used as the originator identity for the crypto Travel Rule, and required for card payouts. If omitted, the workspace (your account) is used as the business originator — so supply this only when paying out on behalf of a distinct third party.

Response

Multiple payouts created

Single payout created

​
amount
string
required

Amount of the payout (as string to avoid floating-point precision issues)

Example:

"100.50"

​
beneficiary
object
required

Beneficiary information

Example:
{
  "accounts": [
    {
      "createdAt": "2024-01-15T10:30:00Z",
      "currency": "EUR",
      "data": {
        "bic": "DEUTDEFF",
        "iban": "DE89370400440532013000"
      },
      "id": "123e4567-e89b-12d3-a456-426614174000",
      "status": "active",
      "type": "iban",
      "updatedAt": "2024-01-15T10:35:00Z"
    }
  ],
  "createdAt": "2024-01-15T10:30:00Z",
  "email": "john.doe@example.com",
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "name": "John Doe",
  "status": "active",
  "updatedAt": "2024-01-15T10:35:00Z"
}
​
createdAt
string<date-time>
required

Creation timestamp

Example:

"2024-01-15T10:30:00Z"

​
currency
enum<string>
required

Currency code (ISO 4217). Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies.

Available options:
EUR,
USD,
GBP,
USDC,
USDT,
EURC,
NGN,
XOF,
XAF,
GHS
Example:

"EUR"

​
fee
string
required

Fee charged for the payout (as string to avoid floating-point precision issues)

Example:

"2.50"

​
id
string<uuid>
required

Unique identifier for the payout

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
route
string
required

Client-facing payment rail. Provider names are never exposed; a provider-routed transfer reads as a generic rail (e.g. international).

Example:

"international"

​
status
enum<string>
required

Current status of the payout

Available options:
created,
queued,
processing,
paid,
failed,
cancelled
Example:

"processing"

​
type
enum<string>
required

Type of payout

Available options:
fiat,
crypto
Example:

"fiat"

​
updatedAt
string<date-time>
required

Last update timestamp

Example:

"2024-01-15T10:35:00Z"

​
balanceAfter
string

Account balance after this transaction (in input currency, e.g., EUR)

Example:

"98.87"

​
clientRef
string

Client-supplied idempotency reference provided at payout creation. Stable across retries and the natural lookup key for support / reconciliation. Absent on provider-synthesized DTOs (e.g. webhook callbacks) where the original client ref is not in scope.

Maximum string length: 100
Example:

"PAYOUT-REF-12345"

​
completedAt
string<date-time>

Completion timestamp

Example:

"2024-01-15T10:40:00Z"

​
description
string

Description of the payout

Example:

"Payment for services rendered"

​
failureCategory
enum<string>

Category of failure for client-facing display

Available options:
payment_not_approved,
recipient_details,
amount_issue,
technical_error
Example:

"payment_not_approved"

​
failureReason
string

Reason for failure if payout failed

Example:

"Insufficient funds"

​
fxRate
string

FX rate applied (rate with markup charged to the client, e.g., 970.87 NGN per EUR)

Example:

"970.87378641"

​
inputAmount
string

Input amount (total amount charged to the client including fee, in input currency)

Example:

"1.13"

​
inputCurrency
enum<string>

Input currency (the currency debited from the client account). This is determined by the inputCurrency provided in the request, or automatically selected as the currency with the largest available balance, or defaults to USD. For example, EUR when paying out NGN. Default enabled currencies: EUR, USD, GBP, USDC, EURC, NGN. Contact your account manager to enable additional currencies.

Available options:
EUR,
USD,
GBP,
USDC,
USDT,
EURC,
NGN,
XOF,
XAF,
GHS
Example:

"EUR"

​
payoutAccountData
object

Payout account data (JSONB)

Example:
{
  "account": 123456789,
  "bankCode": "044",
  "crAccount": "0123456789"
}
​
payoutAccountId
string<uuid>

Payout account ID

Example:

"123e4567-e89b-12d3-a456-426614174000"

​
processedAt
string<date-time>

Processing start timestamp

Example:

"2024-01-15T10:32:00Z"

​
providerReference
string

Reference from the payment provider

Example:

"TXN123456789"

​
reference
string

Optional free-text memo/narration that appears on the recipient side. Use clientRef for idempotency / support lookups.

Example:

"January invoice"

​
txHash
string | null

On-chain transaction hash for crypto payouts, once the transfer is broadcast to the network. Null for non-crypto payouts or before broadcast.

Example:

"0x3a1f9c2b4d5e6f70819a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70"

​
uetr
string | null

SWIFT UETR (Unique End-to-end Transaction Reference) for SWIFT payouts, once the provider exposes it. Null otherwise.

Example:

"4afd0a57-03af-4138-9341-373a78891ea9"