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
Statuses
| Status | Description |
|---|
PENDING | Awaiting customer payment |
COMPLETED | Payment successful |
FAILED | Payment failed or expired |
REFUNDED | Fully refunded |
PARTIALLY_REFUNDED | Partially refunded |
Checkout sessions expire after 60 minutes. If not completed, the collection moves to FAILED.
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 |
Webhook Payload
{
"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
