Skip to main content
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

​
Endpoint

POST /payments-api-service/v1/user/collections Required headers 
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)

{
  "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.

​
Webhook (final outcome)

We POST to your callback_url when the collection completes. See Webhook payload.

​
Status checks (optional)

If a webhook is delayed or missing, query status using Check collection status or Status checks.

​
Common issues

  • Signature mismatch: ensure the string-to-sign matches the payload exactly. See Signature generation.
  • Wrong token: use a collection-scoped Bearer token.
  • Duplicate references: reuse transaction.reference only for safe retries.