Skip to main content
POST
/
payouts
Create Payout
curl --request POST \
  --url https://api.fyatu.com/api/v3/payouts \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "clientId": "F12345678",
  "amount": 100,
  "currency": "USD",
  "description": "January 2026 Salary",
  "reference": "PAY-20260108-001"
}
'
{
  "success": true,
  "status": 201,
  "message": "<string>",
  "data": {
    "payoutId": "<string>",
    "reference": "<string>",
    "recipient": {
      "clientId": "<string>",
      "name": "<string>"
    },
    "amount": 123,
    "fee": 123,
    "totalDebited": 123,
    "currency": "<string>",
    "status": "PENDING",
    "createdAt": "2023-11-07T05:31:56Z"
  },
  "meta": {
    "requestId": "req_abc123def456",
    "timestamp": "2023-11-07T05:31:56Z"
  }
}

​
Overview

Send money to a Fyatu account holder. The payout is processed instantly - funds are debited from your business wallet and credited to the recipient.

​
Request Body

FieldTypeRequiredDescription
clientIdstringYesRecipient’s Fyatu client ID (e.g., F12345678)
amountnumberYesPayout amount in USD
currencystringNoCurrency code (default: USD). Only USD supported, other values are ignored
descriptionstringYesDescription shown to recipient (max 100 chars)
referencestringNoYour unique reference for tracking (max 100 chars)
metadataobjectNoCustom data to attach

​
Response

FieldTypeDescription
payoutIdstringUnique payout identifier
referencestringYour reference (if provided)
recipientobjectRecipient information
amountnumberPayout amount
feenumberProcessing fee
totalDebitednumberTotal debited (amount + fee)
currencystringCurrency code
statusstringCOMPLETED
createdAtstringPayout timestamp

​
Example Usage

<?php
$clientId = 'F12345678';
$amount = 100.00;

// Step 1: Verify the account first
$verifyResponse = file_get_contents(
    "https://api.fyatu.com/api/v3/accounts/{$clientId}",
    false,
    stream_context_create([
        'http' => [
            'method' => 'GET',
            'header' => 'Authorization: Bearer ' . $accessToken
        ]
    ])
);

$account = json_decode($verifyResponse, true);

if (!$account['success'] || !$account['data']['canReceive']) {
    die('Cannot send to this account');
}

// Step 2: Create the payout
$response = file_get_contents(
    'https://api.fyatu.com/api/v3/payouts',
    false,
    stream_context_create([
        'http' => [
            'method' => 'POST',
            'header' => [
                'Content-Type: application/json',
                'Authorization: Bearer ' . $accessToken
            ],
            'content' => json_encode([
                'clientId' => $clientId,
                'amount' => $amount,
                'description' => 'January 2026 Salary',
                'reference' => 'PAY-' . date('Ymd') . '-001',
                'metadata' => [
                    'employeeId' => 'EMP-123',
                    'payPeriod' => '2026-01'
                ]
            ])
        ]
    ])
);

$result = json_decode($response, true);

if ($result['success']) {
    echo "Payout successful!\n";
    echo "Payout ID: {$result['data']['payoutId']}\n";
    echo "Recipient: {$result['data']['recipient']['name']}\n";
    echo "Amount: {$result['data']['amount']} USD\n";
    echo "Fee: {$result['data']['fee']} USD\n";
    echo "Total Debited: {$result['data']['totalDebited']} USD\n";
} else {
    echo "Payout failed: {$result['message']}\n";
}

​
Example Response

{
  "success": true,
  "status": 201,
  "message": "Payout processed successfully",
  "data": {
    "payoutId": "PAY678A1B2C3D4E5F6",
    "reference": "PAY-20260108-001",
    "recipient": {
      "clientId": "F12345678",
      "name": "John Doe"
    },
    "amount": 100.00,
    "fee": 0.50,
    "totalDebited": 100.50,
    "currency": "USD",
    "status": "COMPLETED",
    "createdAt": "2026-01-08T10:30:00+00:00"
  },
  "meta": {
    "requestId": "req_payout123",
    "timestamp": "2026-01-08T10:30:00+00:00"
  }
}

​
Fee Calculation

Payout Amount$100.00
Payout Fee+$0.50
Total Debited$100.50
The fee is added on top of the payout amount. Your business wallet is debited for the total (amount + fee).

​
Error Responses

Error CodeHTTPDescription
RESOURCE_NOT_FOUND404Recipient account not found
RECIPIENT_INACTIVE400Recipient account is not active
DUPLICATE_REFERENCE409Reference already used
INSUFFICIENT_BALANCE402Business wallet balance too low
PAYOUT_LIMIT_EXCEEDED400Daily or monthly limit exceeded
VALIDATION_ERROR400Invalid request data

​
Payout Limits

Your app may have daily and monthly payout limits configured. If exceeded, the request returns PAYOUT_LIMIT_EXCEEDED.
Payouts are instant and irreversible. Always verify the recipient account before sending.

​
Best Practices

  1. Verify First: Always call /accounts/{clientId} before creating a payout
  2. Use References: Use unique references for your records and reconciliation
  3. Store Payout ID: Keep the payoutId for support and auditing
  4. Check Balance: Ensure sufficient wallet balance before bulk payouts
  5. Idempotency: Use the same reference to prevent duplicate payouts
For bulk payouts, batch your requests and include unique references for each to track individual payments.

Authorizations

​
Authorization
string
header
required

JWT access token obtained from /auth/token

Body

application/json
​
clientId
string
required

Recipient's Fyatu client ID

Example:

"F12345678"

​
amount
number
required

Payout amount in USD

Required range: x >= 1
Example:

100

​
description
string
required

Description shown to recipient (max 100 chars)

Maximum string length: 100
Example:

"January salary payment"

​
currency
string
default:USD

Currency code (only USD supported, other values ignored)

​
reference
string

Your unique reference for tracking

Maximum string length: 100
​
metadata
object

Custom data to attach

Response

Payout created successfully

​
success
boolean
Example:

true

​
status
integer
Example:

201

​
message
string
​
data
object
​
meta
object