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

# List Payouts

> List all payouts with pagination and status filtering — initiated, completed, or failed. GET /payouts.

## Overview

Retrieve a paginated list of payouts with optional filtering.

## Query Parameters

| Parameter   | Type    | Description                                   |
| ----------- | ------- | --------------------------------------------- |
| `page`      | integer | Page number (default: 1)                      |
| `limit`     | integer | Items per page (default: 20, max: 100)        |
| `status`    | string  | Filter by status (PENDING, COMPLETED, FAILED) |
| `reference` | string  | Search by reference (partial match)           |
| `recipient` | string  | Search by recipient (client ID or name)       |
| `dateFrom`  | string  | Filter from date (YYYY-MM-DD)                 |
| `dateTo`    | string  | Filter to date (YYYY-MM-DD)                   |

## Response

| Field        | Type   | Description            |
| ------------ | ------ | ---------------------- |
| `payouts`    | array  | List of payout objects |
| `pagination` | object | Pagination info        |

### Payout Object (Summary)

| Field       | Type   | Description                     |
| ----------- | ------ | ------------------------------- |
| `payoutId`  | string | Unique payout identifier        |
| `reference` | string | Your reference                  |
| `recipient` | object | Recipient info (clientId, name) |
| `amount`    | number | Payout amount                   |
| `fee`       | number | Processing fee                  |
| `currency`  | string | Currency code                   |
| `status`    | string | Payout status                   |
| `createdAt` | string | Creation time                   |

## Example Usage

<CodeGroup>
  ```php PHP theme={null}
  <?php
  // Get this month's payouts
  $params = http_build_query([
      'dateFrom' => date('Y-m-01'),
      'dateTo' => date('Y-m-d'),
      'status' => 'COMPLETED',
      'limit' => 100
  ]);

  $response = file_get_contents(
      "https://api.fyatu.com/api/v3/payouts?{$params}",
      false,
      stream_context_create([
          'http' => [
              'method' => 'GET',
              'header' => 'Authorization: Bearer ' . $accessToken
          ]
      ])
  );

  $result = json_decode($response, true);

  $totalPaidOut = 0;
  $totalFees = 0;

  foreach ($result['data']['payouts'] as $payout) {
      $totalPaidOut += $payout['amount'];
      $totalFees += $payout['fee'];
      echo "{$payout['reference']}: {$payout['amount']} to {$payout['recipient']['name']} - {$payout['status']}\n";
  }

  echo "\nTotal paid out: $totalPaidOut USD\n";
  echo "Total fees: $totalFees USD\n";
  echo "Total debited: " . ($totalPaidOut + $totalFees) . " USD\n";
  ```

  ```javascript Node.js theme={null}
  // Get this month's payouts
  const now = new Date();
  const params = new URLSearchParams({
    dateFrom: `${now.getFullYear()}-${String(now.getMonth() + 1).padStart(2, '0')}-01`,
    dateTo: now.toISOString().split('T')[0],
    status: 'COMPLETED',
    limit: '100'
  });

  const response = await fetch(
    `https://api.fyatu.com/api/v3/payouts?${params}`,
    {
      headers: {
        'Authorization': `Bearer ${accessToken}`
      }
    }
  );

  const result = await response.json();

  let totalPaidOut = 0;
  let totalFees = 0;

  for (const payout of result.data.payouts) {
    totalPaidOut += payout.amount;
    totalFees += payout.fee;
    console.log(`${payout.reference}: ${payout.amount} to ${payout.recipient.name} - ${payout.status}`);
  }

  console.log(`\nTotal paid out: ${totalPaidOut} USD`);
  console.log(`Total fees: ${totalFees} USD`);
  console.log(`Total debited: ${totalPaidOut + totalFees} USD`);
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Payouts retrieved successfully",
  "data": {
    "payouts": [
      {
        "payoutId": "pay_a1b2c3d4e5f6",
        "reference": "PAY-0001",
        "recipient": {
          "clientId": "clt_a1b2c3d4e5f6",
          "name": "Alice Example"
        },
        "amount": 100.00,
        "fee": 0.50,
        "currency": "USD",
        "status": "COMPLETED",
        "createdAt": "2026-01-08T10:30:00+00:00"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "itemsPerPage": 20,
      "totalItems": 45,
      "totalPages": 3
    }
  },
  "meta": {
    "requestId": "req_paylist123",
    "timestamp": "2026-01-08T12:00:00+00:00"
  }
}
```

## Filtering Examples

### By Recipient

```
GET /payouts?recipient=clt_a1b2c3d4e5f6
```

### Failed Payouts

```
GET /payouts?status=FAILED
```

### Search by Reference

```
GET /payouts?reference=PAY-20260108
```

### Date Range

```
GET /payouts?dateFrom=2026-01-01&dateTo=2026-01-31
```

## Export for Accounting

Use date filtering and pagination to export payout data for reconciliation:

```php theme={null}
<?php
// Export all payouts for a month
$allPayouts = [];
$page = 1;

do {
    $params = http_build_query([
        'dateFrom' => '2026-01-01',
        'dateTo' => '2026-01-31',
        'status' => 'COMPLETED',
        'page' => $page,
        'limit' => 100
    ]);

    $response = file_get_contents(
        "https://api.fyatu.com/api/v3/payouts?{$params}",
        false,
        stream_context_create([
            'http' => [
                'method' => 'GET',
                'header' => 'Authorization: Bearer ' . $accessToken
            ]
        ])
    );

    $result = json_decode($response, true);
    $allPayouts = array_merge($allPayouts, $result['data']['payouts']);
    $page++;

} while ($page <= $result['data']['pagination']['totalPages']);

// Now $allPayouts contains all payouts for the month
```

<Tip>
  Use payout reports for payroll reconciliation, tax reporting, and financial audits.
</Tip>


## OpenAPI

````yaml v3/openapi.json GET /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:
    get:
      tags:
        - Payouts
      summary: List Payouts
      description: Retrieve a paginated list of payouts with optional filtering.
      operationId: listPayouts
      parameters:
        - name: page
          in: query
          schema:
            type: integer
            default: 1
        - name: limit
          in: query
          schema:
            type: integer
            default: 20
            maximum: 100
        - name: status
          in: query
          schema:
            type: string
            enum:
              - PENDING
              - COMPLETED
              - FAILED
        - name: reference
          in: query
          schema:
            type: string
          description: Search by reference (partial match)
        - name: recipient
          in: query
          schema:
            type: string
          description: Search by recipient (client ID or name)
        - name: dateFrom
          in: query
          schema:
            type: string
            format: date
          description: Filter from date (YYYY-MM-DD)
        - name: dateTo
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Payouts retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PayoutsListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - BearerAuth: []
components:
  schemas:
    PayoutsListResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
        data:
          type: object
          properties:
            payouts:
              type: array
              items:
                $ref: '#/components/schemas/PayoutSummary'
            pagination:
              $ref: '#/components/schemas/PaginationAlt'
        meta:
          $ref: '#/components/schemas/Meta'
    PayoutSummary:
      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
        currency:
          type: string
        status:
          type: string
        createdAt:
          type: string
          format: date-time
    PaginationAlt:
      type: object
      properties:
        currentPage:
          type: integer
        itemsPerPage:
          type: integer
        totalItems:
          type: integer
        totalPages:
          type: integer
    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
    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'
    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:
    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'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: JWT access token obtained from /auth/token

````