Collect payments
Ask a customer to pay from their mobile money wallet.
Ask a customer to pay from their M-Pesa or Mixx by Yas wallet. They approve with their PIN, and the amount, less the fee, goes to your balance.
Create the payment
Call Create a payment with kind COLLECTION, the provider, the
amount, the customer's phone number and an Idempotency-Key. You get 201 and the
payment.
Tell the customer to check their phone
They get a prompt to approve the payment with their PIN.
Act on the outcome
Your webhook endpoint gets payment.succeeded, payment.failed or payment.expired. Deliver on
payment.succeeded, never on the create response.
Without webhooks, retrieve the payment every few seconds until its status is final.
Statuses
| Status | What to do | Final |
|---|---|---|
CREATED, PENDING_PROVIDER, PENDING_CUSTOMER | Wait. | No |
SUCCEEDED | Deliver. | No, you can still reverse it |
FAILED | failureCode says why. Create a new payment to try again. | Yes |
EXPIRED | Not approved within 4 hours. Create a new payment, with a new Idempotency-Key, to ask again. | Yes |
REVERSING, REVERSED | See Reverse payments. | REVERSED only |
Amounts and fees
- Amounts are in Tanzanian shillings (
TZS), at least 500. A customer's wallet has its own daily limit, so a large payment can fail. - Each payment shows its
feeand itsnet, which isamountminusfee. Preview the fee to show the customer before you charge. A payment whose fee would leave nothing is refused with422.
Providers
Set provider to MPESA (Vodacom M-Pesa) or MIXBYYAS (Mixx by Yas). NBC is listed but not available yet.
To stop using a provider, switch it off with
Switch a payment provider on or off, separately
in test and live mode. A payment for a provider that is off, or for NBC, is refused with 400.
Metadata
Tag a payment with your own data, such as an order ID or a sales channel. It comes back on the payment and in every webhook event about it.
"metadata": { "orderId": "1042", "channel": "pos" }Use up to 20 keys. A key is 1 to 40 letters, digits, _ or -, and a value is up to 500 characters. Do not put
personal data in it.
Retry safely
If the network fails before you see the answer, send the same request with the same Idempotency-Key. You get the
first payment back, and the customer is charged once.