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

> List all payment collections with pagination and status filtering. GET /collections.

## Overview

Retrieve a paginated list of your collections 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, REFUNDED) |
| `orderId`   | string  | Search by order ID (partial match)                      |
| `reference` | string  | Search by reference (partial match)                     |
| `dateFrom`  | string  | Filter from date (YYYY-MM-DD)                           |
| `dateTo`    | string  | Filter to date (YYYY-MM-DD)                             |

## Response

| Field         | Type   | Description                |
| ------------- | ------ | -------------------------- |
| `collections` | array  | List of collection objects |
| `pagination`  | object | Pagination info            |

### Collection Object (Summary)

| Field          | Type   | Description              |
| -------------- | ------ | ------------------------ |
| `collectionId` | string | Unique identifier        |
| `reference`    | string | Human-readable reference |
| `orderId`      | string | Your order ID            |
| `amount`       | number | Payment amount           |
| `fee`          | number | Processing fee           |
| `netAmount`    | number | Net amount received      |
| `currency`     | string | Currency code            |
| `status`       | string | Payment status           |
| `payerEmail`   | string | Payer's email            |
| `payerName`    | string | Payer's name             |
| `completedAt`  | string | Completion time          |
| `createdAt`    | string | Creation time            |

### Pagination Object

| Field          | Type    | Description           |
| -------------- | ------- | --------------------- |
| `currentPage`  | integer | Current page number   |
| `itemsPerPage` | integer | Items per page        |
| `totalItems`   | integer | Total number of items |
| `totalPages`   | integer | Total number of pages |

## Example Usage

<CodeGroup>
  ```php PHP theme={null}
  <?php
  // Get completed collections from the last 7 days
  $params = http_build_query([
      'status' => 'COMPLETED',
      'dateFrom' => date('Y-m-d', strtotime('-7 days')),
      'dateTo' => date('Y-m-d'),
      'limit' => 50
  ]);

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

  $result = json_decode($response, true);

  foreach ($result['data']['collections'] as $collection) {
      echo "{$collection['reference']}: {$collection['amount']} {$collection['currency']} - {$collection['status']}\n";
  }

  // Pagination info
  $pagination = $result['data']['pagination'];
  echo "Page {$pagination['currentPage']} of {$pagination['totalPages']}\n";
  ```

  ```javascript Node.js theme={null}
  // Get completed collections from the last 7 days
  const params = new URLSearchParams({
    status: 'COMPLETED',
    dateFrom: new Date(Date.now() - 7 * 24 * 60 * 60 * 1000).toISOString().split('T')[0],
    dateTo: new Date().toISOString().split('T')[0],
    limit: '50'
  });

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

  const result = await response.json();

  for (const collection of result.data.collections) {
    console.log(`${collection.reference}: ${collection.amount} ${collection.currency} - ${collection.status}`);
  }

  // Pagination info
  const { currentPage, totalPages } = result.data.pagination;
  console.log(`Page ${currentPage} of ${totalPages}`);
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Collections retrieved successfully",
  "data": {
    "collections": [
      {
        "collectionId": "col_a1b2c3d4e5f6",
        "reference": "A2B4C6D8E0F2",
        "orderId": "ORD-0001",
        "amount": 25.00,
        "fee": 0.75,
        "netAmount": 24.25,
        "currency": "USD",
        "status": "COMPLETED",
        "payerEmail": "alice@example.com",
        "payerName": "Alice Example",
        "completedAt": "2026-01-08T11:35:00+00:00",
        "createdAt": "2026-01-08T11:30:00+00:00"
      }
    ],
    "pagination": {
      "currentPage": 1,
      "itemsPerPage": 20,
      "totalItems": 156,
      "totalPages": 8
    }
  },
  "meta": {
    "requestId": "req_list123abc",
    "timestamp": "2026-01-08T12:00:00+00:00"
  }
}
```

## Filtering Tips

### By Date Range

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

### Pending Payments

```
GET /collections?status=PENDING
```

### Search by Order ID

```
GET /collections?orderId=INV-001
```

### Paginate Large Results

```
GET /collections?page=1&limit=100
GET /collections?page=2&limit=100
```

<Tip>
  Use date filtering to reduce response size and improve performance when you have many collections.
</Tip>


## OpenAPI

````yaml v3/openapi.json GET /collections
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:
  /collections:
    get:
      tags:
        - Collections
      summary: List Collections
      description: Retrieve a paginated list of collections with optional filtering.
      operationId: listCollections
      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
              - EXPIRED
              - FAILED
              - REFUNDED
              - PARTIALLY_REFUNDED
        - name: orderId
          in: query
          schema:
            type: string
        - name: dateFrom
          in: query
          schema:
            type: string
            format: date
        - name: dateTo
          in: query
          schema:
            type: string
            format: date
      responses:
        '200':
          description: Collections retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionsListResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
      security:
        - BearerAuth: []
components:
  schemas:
    CollectionsListResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
        data:
          type: object
          properties:
            collections:
              type: array
              items:
                $ref: '#/components/schemas/CollectionSummary'
            pagination:
              $ref: '#/components/schemas/PaginationAlt'
        meta:
          $ref: '#/components/schemas/Meta'
    CollectionSummary:
      type: object
      properties:
        collectionId:
          type: string
        reference:
          type: string
        orderId:
          type: string
        amount:
          type: number
        fee:
          type: number
        netAmount:
          type: number
        currency:
          type: string
        status:
          type: string
        payerClientId:
          type: string
          description: Payer's Fyatu client ID
        payerName:
          type: string
          description: Payer's full name
        completedAt:
          type: string
          format: date-time
        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

````