Skip to main content
Remittances move funds across corridors and require extra KYC fields. The flow mirrors payouts/collections: accept immediately, then finalize via webhook.

​
Quick flow

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

​
Prerequisites

​
Endpoint

POST /payments-api-service/v1/remittance 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 remittance.

​
Request body (example)

{
  "transaction": {
    "reference": "TXN123654573",
    "amount": 100,
    "currency": "KES",
    "description": "Family support",
    "service_code": "RMT_WU",
    "timestamp": "2025-01-21 12:30:10"
  },
  "originator": {
    "msisdn": "254722111999",
    "channel": "APP",
    "country": "KEN",
    "Service_provider": "TELCOM-UK",
    "name": "John Sender",
    "dob": "1965-01-01",
    "nationality": "UK",
    "id_type": "Passport",
    "id_number": "PSA010101",
    "purpose": "No purpose"
  },
  "recipient": {
    "reference": "REM-2025-01",
    "account": "254701234567",
    "name": "John Doe Init"
  },
  "callback_url": "https://merchant.example.com/webhooks/remittances",
  "meta": {
    "note": "KYC verified",
    "agent_id": "AG1234"
  }
}
Notes
  • transaction.timestamp for remittance uses YYYY-MM-DD HH:mm:ss (no timezone suffix).
  • KYC fields are required per corridor. Provide full name, DOB, nationality, and ID details.

​
Acceptance response (immediate)

The acceptance response uses the same envelope as payouts. See Initiate remittance API.

​
Webhook (final outcome)

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

​
Status checks (optional)

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

​
Common issues

  • Signature mismatch: ensure the string-to-sign matches the payload exactly. See Signature generation.
  • Wrong token: use a remittance-scoped Bearer token.
  • Timestamp format: remittance uses YYYY-MM-DD HH:mm:ss.