AFRIPEI
Get started
Menu
OverviewPaymentsPayoutsWebhooksReferenceGet started

Start

Authentication

The API uses secret keys. The merchant portal uses a session cookie. They are not interchangeable.

Secret keys

Send Authorization: Bearer sk_live_... on every /v1 request except public checkout reads. Create the key in the merchant portal under Developers. The full key is shown once. AFRIPEI stores a hash.

A key has scopes. payments.create and payments.read cover collections. payouts.create and payouts.read cover disbursements. balance.read covers the balance. webhooks.read and webhooks.write cover endpoints. A missing scope returns 403 INSUFFICIENT_SCOPE.

A live key on https://api.afripei.co.tz moves real TZS. Rotate a key by creating a new one and revoking the old one. Revocation is immediate.

Portal sessions

The merchant portal signs in with email and password, then a one-time code when one is required. The session cookie is HttpOnly. State-changing portal requests also send X-CSRF-Token, copied from the cookie afripei_csrf.

Ten wrong passwords in 15 minutes lock the account. The error stays “The password is incorrect.” so the response does not reveal the lock.

Publishable keys

A publishable key can create a checkout session and read that session. It cannot list payments, create payouts, or read the balance.

Where each credential belongs

  • A secret key belongs on your server, or in the MCP environment of a developer who is allowed to move money.
  • A publishable key may be used by a checkout page.
  • A portal session belongs in the browser that signed in. Do not copy the session cookie into a script.

Rotation

Create the new secret key first and confirm a read, such as the balance, with it. Then revoke the old key. Revocation is immediate. A webhook signing secret is separate from the API key. Rotate that from the endpoint when the signing secret has been exposed. Both the new secret and the previous one can appear in X-AFRIPEI-Signature during the change.

What the API will not accept

A missing key is 401 INVALID_API_KEY. A key without the scope for that route is 403 INSUFFICIENT_SCOPE. An account that is not active yet is 403 MERCHANT_NOT_ACTIVE. None of those are fixed by retrying. Change the key, the scope, or wait until verification is complete.