> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fyatu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Payout

> Create an instant payout to a Fyatu user. Specify amount, recipient, and reference for reconciliation. POST /payouts.

## 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

| Field         | Type   | Required | Description                                                                |
| ------------- | ------ | -------- | -------------------------------------------------------------------------- |
| `clientId`    | string | Yes      | Recipient's Fyatu client ID                                                |
| `amount`      | number | Yes      | Payout amount in USD                                                       |
| `currency`    | string | No       | Currency code (default: USD). Only USD supported, other values are ignored |
| `description` | string | Yes      | Description shown to recipient (max 100 chars)                             |
| `reference`   | string | No       | Your unique reference for tracking (max 100 chars)                         |
| `metadata`    | object | No       | Custom data to attach                                                      |

## Response

| Field          | Type   | Description                  |
| -------------- | ------ | ---------------------------- |
| `payoutId`     | string | Unique payout identifier     |
| `reference`    | string | Your reference (if provided) |
| `recipient`    | object | Recipient information        |
| `amount`       | number | Payout amount                |
| `fee`          | number | Processing fee               |
| `totalDebited` | number | Total debited (amount + fee) |
| `currency`     | string | Currency code                |
| `status`       | string | `COMPLETED`                  |
| `createdAt`    | string | Payout timestamp             |

## Example Usage

<CodeGroup>
  ```php PHP theme={null}
  <?php
  $clientId = 'clt_a1b2c3d4e5f6';
  $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' => 'Staff Payment',
                  'reference' => 'PAY-0001',
                  'metadata' => [
                      'reference' => 'PAYROLL-001'
                  ]
              ])
          ]
      ])
  );

  $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";
  }
  ```

  ```javascript Node.js theme={null}
  const clientId = 'clt_a1b2c3d4e5f6';
  const amount = 100.00;

  // Step 1: Verify the account first
  const verifyResponse = await fetch(
    `https://api.fyatu.com/api/v3/accounts/${clientId}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  const account = await verifyResponse.json();

  if (!account.success || !account.data.canReceive) {
    throw new Error('Cannot send to this account');
  }

  // Step 2: Create the payout
  const response = await fetch('https://api.fyatu.com/api/v3/payouts', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${accessToken}`
    },
    body: JSON.stringify({
      clientId,
      amount,
      description: 'Staff Payment',
      reference: 'PAY-0001',
      metadata: {
        reference: 'PAYROLL-001'
      }
    })
  });

  const result = await response.json();

  if (result.success) {
    console.log('Payout successful!');
    console.log(`Payout ID: ${result.data.payoutId}`);
    console.log(`Recipient: ${result.data.recipient.name}`);
    console.log(`Amount: ${result.data.amount} USD`);
    console.log(`Fee: ${result.data.fee} USD`);
    console.log(`Total Debited: ${result.data.totalDebited} USD`);
  } else {
    console.log(`Payout failed: ${result.message}`);
  }
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "success": true,
  "status": 201,
  "message": "Payout processed successfully",
  "data": {
    "payoutId": "pay_a1b2c3d4e5f6",
    "reference": "PAY-0001",
    "recipient": {
      "clientId": "clt_a1b2c3d4e5f6",
      "name": "Alice Example"
    },
    "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 Code              | HTTP | Description                     |
| ----------------------- | ---- | ------------------------------- |
| `RESOURCE_NOT_FOUND`    | 404  | Recipient account not found     |
| `RECIPIENT_INACTIVE`    | 400  | Recipient account is not active |
| `DUPLICATE_REFERENCE`   | 409  | Reference already used          |
| `INSUFFICIENT_BALANCE`  | 402  | Business wallet balance too low |
| `PAYOUT_LIMIT_EXCEEDED` | 400  | Daily or monthly limit exceeded |
| `VALIDATION_ERROR`      | 400  | Invalid request data            |

## Payout Limits

Your app may have daily and monthly payout limits configured. If exceeded, the request returns `PAYOUT_LIMIT_EXCEEDED`.

<Warning>
  Payouts are instant and irreversible. Always verify the recipient account before sending.
</Warning>

## 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

<Tip>
  For bulk payouts, batch your requests and include unique references for each to track individual payments.
</Tip>


## OpenAPI

````yaml v3/openapi.json POST /payouts
openapi: 3.1.0
info:
  title: FYATU API v3
  description: >-
    FYATU API v3 with JWT authentication for Collections, Payouts, and Card
    Issuing.
  version: 3.0.0
  contact:
    name: FYATU Support
    url: https://fyatu.com
    email: support@fyatu.com
servers:
  - url: https://api.fyatu.com/api/v3
    description: Production
security: []
tags:
  - name: Authentication
    description: JWT token management endpoints
  - name: Account
    description: Business account, wallet, and address management
  - name: Collections
    description: Accept payments from customers via checkout sessions
  - name: Refunds
    description: Issue refunds for completed collections
  - name: Payouts
    description: Send money to Fyatu account holders
  - name: Cardholders
    description: Cardholder management for card issuing programs
  - name: Cards
    description: Issue, fund, freeze, and manage virtual cards
  - name: Webhooks
    description: Webhook configuration and management
paths:
  /payouts:
    post:
      tags:
        - Payouts
      summary: Create Payout
      description: >-
        Send money to a Fyatu account holder. Always verify the account first
        using GET /accounts/{clientId}.
      operationId: createPayout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PayoutRequest'
            example:
              clientId: clt_a1b2c3d4e5f6
              amount: 100
              currency: USD
              description: January 2026 Salary
              reference: PAY-20260108-001
      responses:
        '201':
          description: Payout created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutResponse'
        '400':
          $ref: '#/components/responses/ValidationError'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '402':
          description: Insufficient balance
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - BearerAuth: []
components:
  schemas:
    PayoutRequest:
      type: object
      required:
        - clientId
        - amount
        - description
      properties:
        clientId:
          type: string
          description: Recipient's Fyatu client ID
          example: clt_a1b2c3d4e5f6
        amount:
          type: number
          minimum: 1
          description: Payout amount in USD
          example: 100
        currency:
          type: string
          default: USD
          description: Currency code (only USD supported, other values ignored)
        description:
          type: string
          maxLength: 100
          description: Description shown to recipient (max 100 chars)
          example: January salary payment
        reference:
          type: string
          maxLength: 100
          description: Your unique reference for tracking
        metadata:
          type: object
          description: Custom data to attach
    PayoutResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 201
        message:
          type: string
        data:
          $ref: '#/components/schemas/PayoutData'
        meta:
          $ref: '#/components/schemas/Meta'
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          example: false
        status:
          type: integer
          example: 401
        message:
          type: string
          example: Invalid credentials
        error:
          $ref: '#/components/schemas/Error'
        meta:
          $ref: '#/components/schemas/Meta'
    PayoutData:
      type: object
      properties:
        payoutId:
          type: string
          description: Unique payout identifier
        reference:
          type: string
        recipient:
          type: object
          properties:
            clientId:
              type: string
            name:
              type: string
        amount:
          type: number
        fee:
          type: number
        totalDebited:
          type: number
        currency:
          type: string
        status:
          type: string
          enum:
            - PENDING
            - COMPLETED
            - FAILED
        createdAt:
          type: string
          format: date-time
    Meta:
      type: object
      properties:
        requestId:
          type: string
          description: Unique request ID for tracking
          example: req_abc123def456
        timestamp:
          type: string
          format: date-time
          description: ISO 8601 timestamp of the response
    Error:
      type: object
      properties:
        code:
          type: string
          description: Error code for programmatic handling
          example: AUTH_INVALID_CREDENTIALS
        details:
          type: array
          items:
            $ref: '#/components/schemas/ValidationError'
          description: Validation error details (for VALIDATION_ERROR)
    ValidationError:
      type: object
      properties:
        field:
          type: string
          description: Field that failed validation
          example: appId
        message:
          type: string
          description: Validation error message
          example: AppId is required
  responses:
    ValidationError:
      description: Validation failed
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            status: 400
            message: Validation failed
            error:
              code: VALIDATION_ERROR
              details:
                - field: currency
                  message: Currency is required
            meta:
              requestId: req_abc123
              timestamp: '2026-01-05T10:30:00+00:00'
    Unauthorized:
      description: Authentication required or token invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            status: 401
            message: Unable to identify business
            error:
              code: AUTH_TOKEN_INVALID
            meta:
              requestId: req_abc123
              timestamp: '2026-01-05T10:30:00+00:00'
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            success: false
            status: 404
            message: Wallet not found
            error:
              code: RESOURCE_NOT_FOUND
            meta:
              requestId: req_abc123
              timestamp: '2026-01-05T10:30:00+00:00'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from /auth/token

````