Build

API reference

Base URL https://api.afripei.co.tz. Send Authorization: Bearer sk_live_... and Content-Type: application/json. Amounts are decimal strings with two places. Currency is TZS.

Route	Purpose
`POST /v1/payments`	Create a collection. Requires Idempotency-Key and payments.create.
`GET /v1/payments`	List collections. Filters: status, merchant_reference, created_gte, created_lte.
`GET /v1/payments/:id`	Read one collection.
`POST /v1/payments/:id/cancel`	Cancel a pending prompt or close a control number.
`POST /v1/checkout_sessions`	Create a hosted pay page. A publishable key may call this.
`GET /v1/checkout_sessions/:id`	Read a pay page. No key required. The id is the capability.
`POST /v1/checkout_sessions/:id/submit`	Send the prompt for a pay page. Body is { phone }.
`POST /v1/payouts`	Send to mobile money or a bank. Requires Idempotency-Key.
`POST /v1/payouts/bulk`	Send many mobile-money payouts. One reservation for the batch.
`GET /v1/payouts`	List payouts.
`GET /v1/payouts/:id`	Read one payout.
`GET /v1/banks`	List banks for a bank payout.
`GET /v1/balance`	Available, pending, and reserved balances.
`GET /v1/balance/transactions`	Ledger lines. Query currency, default TZS.
`POST /v1/customers`	Save a customer.
`GET /v1/customers`	List customers.
`GET /v1/customers/:id`	Read one customer.
`POST /v1/webhook_endpoints`	Register an endpoint. Returns the signing secret once.
`GET /v1/webhook_endpoints`	List endpoints.
`POST /v1/webhook_endpoints/:id/rotate_secret`	Replace the signing secret.
`POST /v1/webhook_endpoints/:id/test`	Send a signed test event.
`POST /v1/webhook_endpoints/:id/disable`	Stop deliveries.
`GET /v1/events`	List stored events.
`POST /v1/events/:id/replay`	Deliver one stored event again.
`GET /v1/status`	Public component status.

Object

A payment includes id, amount, currency, status, payment_method, merchant_reference, failure_message, and control_number when the method is billpay. A payout includes id, amount, currency, status, and method.

Headers on every call

Authorization: Bearer with a secret key, except the public checkout read.
Content-Type: application/json when you send a body.
Idempotency-Key on every create that can move money or open a payment.

Amounts

Decimal strings with two places. Currency TZS. Mobile-money collections run from 500.00 to 3000000.00. Phones are Tanzania numbers in E.164, beginning with +255. Customers and recipients use M-Pesa, Airtel Money, Mixx by Yas, or Halopesa. You send the number, not a network code.

Errors

Failures are a JSON error object with code, message, and request_id. A 201 that later fails on the wallet is not this object. That outcome is the payment or payout status. The codes are listed on the errors page.

Versions

The API version on events is 2026-09-29. Objects keep the field names on this page. A field you do not recognize should be ignored, not rejected, so a later addition does not break a reader.