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

# Get Collection

> Get details of a specific payment collection — amount, status, checkout URL, and metadata. GET /collections/{id}.

## Overview

Retrieve details of a specific collection by its ID. Use this to verify payment status.

## Path Parameters

| Parameter      | Type   | Description                  |
| -------------- | ------ | ---------------------------- |
| `collectionId` | string | The collection ID (batch ID) |

## Response

| Field          | Type   | Description                            |
| -------------- | ------ | -------------------------------------- |
| `collectionId` | string | Unique collection identifier           |
| `reference`    | string | Human-readable reference               |
| `orderId`      | string | Your order ID (if provided)            |
| `amount`       | number | Payment amount                         |
| `fee`          | number | Processing fee                         |
| `netAmount`    | number | Amount received (amount - fee)         |
| `currency`     | string | Currency code                          |
| `description`  | string | Payment description                    |
| `status`       | string | Payment status                         |
| `statusReason` | string | Reason for status (if failed/refunded) |
| `payer`        | object | Payer information                      |
| `metadata`     | object | Your custom metadata                   |
| `completedAt`  | string | Completion timestamp                   |
| `expiresAt`    | string | Session expiry time                    |
| `createdAt`    | string | Creation timestamp                     |

### Payer Object

| Field         | Type   | Description             |
| ------------- | ------ | ----------------------- |
| `email`       | string | Payer's email           |
| `name`        | string | Payer's name            |
| `accountName` | string | Fyatu account name      |
| `clientId`    | string | Payer's Fyatu client ID |

## Status Values

| Status               | Description               |
| -------------------- | ------------------------- |
| `PENDING`            | Awaiting payment          |
| `COMPLETED`          | Payment successful        |
| `FAILED`             | Payment failed or expired |
| `REFUNDED`           | Fully refunded            |
| `PARTIALLY_REFUNDED` | Partially refunded        |

## Example Usage

<CodeGroup>
  ```php PHP theme={null}
  <?php
  $collectionId = 'col_a1b2c3d4e5f6';

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

  $result = json_decode($response, true);

  if ($result['success'] && $result['data']['status'] === 'COMPLETED') {
      // Payment confirmed
      $netAmount = $result['data']['netAmount'];
      $payerName = $result['data']['payer']['name'];

      // Fulfill the order
      fulfillOrder($result['data']['orderId']);
  }
  ```

  ```javascript Node.js theme={null}
  const collectionId = 'col_a1b2c3d4e5f6';

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

  const result = await response.json();

  if (result.success && result.data.status === 'COMPLETED') {
    // Payment confirmed
    const { netAmount, orderId } = result.data;
    const payerName = result.data.payer.name;

    // Fulfill the order
    await fulfillOrder(orderId);
  }
  ```
</CodeGroup>

## Example Response

```json theme={null}
{
  "success": true,
  "status": 200,
  "message": "Collection retrieved successfully",
  "data": {
    "collectionId": "col_a1b2c3d4e5f6",
    "reference": "A2B4C6D8E0F2",
    "orderId": "ORD-0001",
    "amount": 25.00,
    "fee": 0.75,
    "netAmount": 24.25,
    "currency": "USD",
    "description": "Premium Subscription",
    "status": "COMPLETED",
    "statusReason": null,
    "payer": {
      "email": "alice@example.com",
      "name": "Alice Example",
      "accountName": "Alice E.",
      "clientId": "clt_a1b2c3d4e5f6"
    },
    "metadata": {
      "plan": "premium"
    },
    "completedAt": "2026-01-08T11:35:00+00:00",
    "expiresAt": "2026-01-08T12:30:00+00:00",
    "createdAt": "2026-01-08T11:30:00+00:00"
  },
  "meta": {
    "requestId": "req_xyz789ghi012",
    "timestamp": "2026-01-08T11:40:00+00:00"
  }
}
```

## Verifying Payments

<Warning>
  Always verify payment status server-side before fulfilling orders. Never trust client-side redirects alone.
</Warning>

### Recommended Verification Flow

1. **Webhook**: Receive payment notification at your `webhookUrl`
2. **API Verification**: Call this endpoint to confirm the payment
3. **Check Status**: Ensure `status` is `COMPLETED`
4. **Check Amount**: Verify `amount` matches expected value
5. **Fulfill Order**: Only then process the order

```php theme={null}
<?php
// Webhook handler example
function handleWebhook($payload) {
    $collectionId = $payload['collectionId'];

    // Always verify with API
    $collection = getCollection($collectionId);

    if ($collection['status'] !== 'COMPLETED') {
        return; // Not completed yet
    }

    // Check if already processed
    if (orderAlreadyFulfilled($collection['orderId'])) {
        return; // Duplicate webhook
    }

    // Fulfill the order
    fulfillOrder($collection['orderId'], $collection['netAmount']);
}
```

## Error Responses

| Error Code           | HTTP | Description                              |
| -------------------- | ---- | ---------------------------------------- |
| `RESOURCE_NOT_FOUND` | 404  | Collection not found or not owned by you |
| `AUTH_TOKEN_INVALID` | 401  | Invalid or expired token                 |


## OpenAPI

````yaml v3/openapi.json GET /collections/{collectionId}
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/{collectionId}:
    get:
      tags:
        - Collections
      summary: Get Collection
      description: Retrieve details of a specific collection by ID, batch ID, or order ID.
      operationId: getCollection
      parameters:
        - name: collectionId
          in: path
          required: true
          schema:
            type: string
          description: Collection ID, batch ID, or order ID
      responses:
        '200':
          description: Collection retrieved successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CollectionDetailResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
      security:
        - BearerAuth: []
components:
  schemas:
    CollectionDetailResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        status:
          type: integer
          example: 200
        message:
          type: string
        data:
          $ref: '#/components/schemas/CollectionDetail'
        meta:
          $ref: '#/components/schemas/Meta'
    CollectionDetail:
      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
        description:
          type: string
        payer:
          type: object
          properties:
            clientId:
              type: string
              description: Payer's Fyatu client ID
            name:
              type: string
              description: Payer's full name
        metadata:
          type: object
        callbackUrl:
          type: string
          nullable: true
          description: Return URL after payment
        webhookUrl:
          type: string
          nullable: true
          description: IPN URL for notifications
        statusReason:
          type: string
          nullable: true
          description: Reason for the current status (e.g., expiry reason, failure details)
        completedAt:
          type: string
          format: date-time
        createdAt:
          type: string
          format: date-time
        expiresAt:
          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
    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'
    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

````