​

Collections

​

Flow

​

Statuses

​

Fees

​

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

​

Endpoints

• POST /collections — Create checkout session
• GET /collections/{id} — Get collection details
• GET /collections — List collections