> ## Documentation Index
> Fetch the complete documentation index at: https://docs.waftpay.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Collections

> Receive customer payments with signing, acceptance, webhooks, and reconciliation guidance.

Collections are incoming customer payments. The API is asynchronous: you get an acceptance response immediately, then a final result via webhook.

***

## Quick flow

Authenticate -> Sign -> Send collection -> Receive acceptance -> Receive webhook -> Reconcile (optional status check).

***

## Prerequisites

* Product-scoped Bearer token from [Authentication API](/api-reference/auth/auth-token).
* RSA 2048 key pair registered with Waftpay. See [Signature generation](/api-reference/signatures/signature-generate).
* Correct base URL for your environment. See [Environments](/environments).

***

## Endpoint

**POST** `/payments/api/v1/collections`

**Required headers**

```http theme={null}
Authorization: Bearer <access_token>
Content-Type: application/json
X-Custom-Signature: <base64-signature>
```

**Idempotency**: reuse the same `transaction.reference` for retries of the same logical collection.

***

## Request body (example)

```json theme={null}
{
  "transaction": {
    "reference": "TNC000008",
    "amount": 1000,
    "currency": "KES",
    "description": "Order #98765",
    "service_code": "RMT_WU",
    "timestamp": "2025-01-21T12:30:10Z"
  },
  "originator": {
    "msisdn": "254712345678",
    "channel": "USSD",
    "country": "KE",
    "name": "John Doe",
    "purpose": "Collections"
  },
  "recipient": {
    "invoice_number": "3456789987654",
    "reference": "INVJMA01",
    "account": "254712345678"
  },
  "callback_url": "https://merchant.example.com/webhooks/collections",
  "meta": {
    "note": "cartId=abc123",
    "agent_id": "AGENT456"
  }
}
```

**Notes**

* `invoice_number` is optional but useful for reconciliation.
* `timestamp` must be ISO 8601 UTC (ends with `Z`).
* `transaction.service_code` is required only if enabled on your account.

***

## Acceptance response (immediate)

The acceptance response uses the same envelope as payouts. See [Initiate collection API](/api-reference/collections/collection-initiate).

***

## Webhook (final outcome)

We POST to your `callback_url` when the collection completes. See [Webhook payload](/pages/webhooks/payload).

***

## Status checks (optional)

If a webhook is delayed or missing, query status using [Check collection status](/api-reference/collections/collections-status) or [Status checks](/pages/guides/status-checks).

***

## Common issues

* **Signature mismatch**: ensure the string-to-sign matches the payload exactly. See [Signature generation](/api-reference/signatures/signature-generate).
* **Wrong token**: use a collection-scoped Bearer token.
* **Duplicate references**: reuse `transaction.reference` only for safe retries.

***

## Related links

* [Initiate collection API](/api-reference/collections/collection-initiate)
* [Check collection status](/api-reference/collections/collections-status)
* [Webhooks overview](/pages/webhooks/overview)
* [Errors](/errors)