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

# Collections

> Accept payments from Fyatu users via a hosted checkout page. Create a session, redirect your customer, and receive webhook confirmation.

# Collections

A collection is an inbound payment from a Fyatu user to your business wallet. You create a checkout session, redirect the customer, and receive a webhook when the payment completes.

## Flow

```mermaid theme={null}
sequenceDiagram
    participant Merchant
    participant FYATU API
    participant Customer
    participant Checkout

    Merchant->>FYATU API: POST /collections
    FYATU API-->>Merchant: checkoutUrl
    Merchant->>Customer: Redirect to checkoutUrl
    Customer->>Checkout: Complete payment
    Checkout->>FYATU API: Process payment
    FYATU API->>Merchant: Webhook: collection.completed
    Merchant->>FYATU API: GET /collections/{id}
    FYATU API-->>Merchant: Confirm COMPLETED
```

## Statuses

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

<Note>
  Checkout sessions expire after **60 minutes**. If not completed, the collection moves to `FAILED`.
</Note>

## Fees

Collection fees are deducted from the received amount — the customer pays the gross amount, you receive the net:

| Gross Amount | Fee    | Net Amount Received |
| ------------ | ------ | ------------------- |
| \$25.00      | \$0.75 | \$24.25             |
| \$100.00     | \$3.00 | \$97.00             |

Use [GET /account/pricing](/v3/api-reference/account/pricing) to retrieve your current collection fee rate.

## Webhook Payload

```json theme={null}
{
  "event": "collection.completed",
  "data": {
    "collectionId": "col_a1b2c3d4e5f6",
    "reference": "A2B4C6D8E0F2",
    "orderId": "ORD-0001",
    "amount": 25.00,
    "fee": 0.75,
    "netAmount": 24.25,
    "currency": "USD",
    "status": "COMPLETED",
    "payer": {
      "name": "Alice Example",
      "email": "alice@example.com"
    },
    "completedAt": "2026-01-08T11:35:00+00:00"
  },
  "timestamp": "2026-01-08T11:35:01+00:00"
}
```

## Best Practices

* **Use order IDs**: pass `orderId` to link each collection to your order system and prevent duplicates
* **Verify server-side**: always call `GET /collections/{id}` before fulfilling an order — never trust the webhook payload alone
* **Handle expiry**: sessions expire after 60 minutes; let customers re-initiate if they don't complete in time
* **Verify webhook signatures**: check the HMAC-SHA256 signature on every incoming webhook before processing
* **Retry safely**: for 5xx errors, use exponential backoff (start at 1 s, cap at 30 s, max 3 retries)

## Error Codes

| Code                  | Cause                 | Resolution                            |
| --------------------- | --------------------- | ------------------------------------- |
| `DUPLICATE_REFERENCE` | Order ID already used | Use a unique `orderId` per collection |

## Endpoints

* `POST /collections` — [Create checkout session](/v3/api-reference/collections/create)
* `GET /collections/{id}` — [Get collection details](/v3/api-reference/collections/get)
* `GET /collections` — [List collections](/v3/api-reference/collections/list)