Collections
Charge a customer's mobile-money wallet.
A collection takes money from a customer's wallet into your NuruPay balance using a USSD push.
Lifecycle
created ──► pending ──► succeeded
│ └─► failed
└──────► expired| Status | Meaning |
|---|---|
created | Accepted by NuruPay; the push is being sent. |
pending | The customer's phone has the PIN prompt. |
succeeded | Paid. The money is in your pending balance. |
failed | Not paid; see failure_code and failure_message. |
expired | The customer did not approve in time (30 minutes); the order was cancelled at the network. |
succeeded, failed, and expired are final: a collection never changes after reaching one.
Channels
The network is detected from the phone number's prefix. If the customer has moved their number to another network, pass channel explicitly.
| Channel | Network | Prefixes |
|---|---|---|
MPESA_TZ | Vodacom M-Pesa | 074, 075, 076 |
AIRTEL_MONEY_TZ | Airtel Money | 068, 069, 078 |
MIXX_BY_YAS | Mixx by Yas | 065, 067, 071, 077 |
HALOPESA | HaloPesa | 061, 062 |
TPESA | T-Pesa | 073 |
Amounts and fees
- Amounts are whole Tanzanian shillings:
15000is TZS 15,000. Minimum TZS 100, maximum TZS 5,000,000. - The
feeis calculated when the collection is created and never changes. It is deducted from what you receive: a TZS 15,000 collection with a TZS 300 fee adds TZS 14,700 to your balance.
Your reference
reference is your own ID for the payment (for example an order number). It must be unique per mode: reusing one returns 409 duplicate_reference, which protects you from charging the same order twice.
Getting the result
Use webhooks (recommended) or poll GET /v1/collections/{id}. Don't rely on your customer's browser redirect or on the time elapsed: only succeeded means you were paid.