Documentation

Collect and send Tanzanian shillings

AFRIPEI is one merchant API for mobile-money collections and payouts in TZS. Amounts are decimal strings. A successful create response means the request was accepted. The customer still confirms a collection on their phone.

Create an account and a key

1. 1Open the merchant portal. Register at merchant.afripei.co.tz. The account can collect after it is active.
2. 2Create a secret key. In Developers, create a key and copy it once. Send it as Authorization: Bearer sk_live_....
3. 3Send a collection. POST /v1/payments with an Idempotency-Key you choose. Mobile money starts at 500.00 TZS.
4. 4Wait for the webhook. payment.success is the signal that the customer paid. A 201 is only the prompt.

First collection

curl https://api.afripei.co.tz/v1/payments \
  -H "Authorization: Bearer sk_live_..." \
  -H "Idempotency-Key: order-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": "500.00",
    "currency": "TZS",
    "payment_method": "mobile_money",
    "description": "Order 1001",
    "merchant_reference": "order-1001",
    "customer": { "phone": "+255700000000", "name": "Amina Juma" }
  }'

The phone is a Tanzania number in E.164, beginning with +255. Customers pay with M-Pesa, Airtel Money, Mixx by Yas, or Halopesa. Send the number they will confirm on. The response id is what you store and what you pass to GET /v1/payments/:id.

What a collection is

A collection is one payment. Status pending means the prompt was accepted. Status success means the customer paid. Hand over the goods on success, from the webhook or from a read of that payment. Do not hand them over on the create response.

What a payout is

A payout leaves available balance. The amount and the fee are reserved together. If the balance cannot cover both, nothing is created. A payout can go to a mobile wallet or to a bank account. payout.success means the recipient was paid.

The account has to be active

A new merchant waits for verification. Until the account is active, collections and payouts stay closed. A live secret key on https://api.afripei.co.tz moves real shillings. There is no sandbox.

What to read next

• Payments covers the prompt, the control number, the minimum, and every status.
• Payouts covers mobile money and bank transfer.
• Limits covers the amount range, the rate limits, and the idempotency window.
• Webhooks covers signing and the event list.
• Errors covers the JSON error body and what to do with each code.
• MCP connects Cursor and Claude to the same API.