How AfroPin works

Base URL

Endpoint paths in the API reference are relative to this URL. Test and live mode share it; the API key you sign with decides the mode. Environments →

What the API covers

As a reseller you buy PIN value from the network and resell it to your customers.

Requests

• Send request bodies as JSON with Content-Type: application/json.
• Every request is signed with your API key and carries a unique Idempotency-Key. See Authentication.
• IDs such as pin_id, catalog_id and webhook_id are UUIDs.
• Write requests that move money accept an external_reference: your own ID for the operation. A reference can only be used once, so it also protects you from charging twice.
• You can send up to 60 requests per minute. Only one write request per account is processed at a time; a second one sent while the first is running fails with rate_limited.

Responses

Every response is JSON with the same envelope. ok is true or false. A success puts the result in data (lists add paging); a failure puts code, message and fields in error.

{
    "ok": true,
    "data": {
        "transaction_ref": "3c6bb90c-4dc9-4e01-bdf2-75e91199847d",
        "amount": 10,
        "balance": 90,
        "currency": "NGN",
        "mode": "test",
        "external_reference": "order_10293",
        "processed_at": "2026-10-05T09:14:22.000000Z"
    }
}

{
    "ok": false,
    "error": {
        "code": "pin_blocked",
        "message": "This PIN is blocked",
        "fields": null
    }
}

• Errors carry a stable error.code; validation errors also list each failing field in error.fields. Branch on error.code, never on error.message, which is translated into your account language. Errors →
• Amounts are JSON numbers in the currency's main unit, for example 10 for 10 naira.
• Timestamps are ISO 8601 in UTC.
• Objects carry a mode field, test or live.

Storing PIN codes

• Save pin_code from Issue a PIN before you show it to your customer. If your system fails after the call, the code cannot be fetched again: the PIN still exists, and only pin_mask can be looked up.
• Store codes encrypted at rest, keep them out of logs, analytics and error reports, and limit who can read them.
• Deliver the code to your customer in a way they can find again, such as email or SMS with the receipt.

Products that issue a new code

Some products replace the PIN code after it is used, so a code that leaked earlier stops working. The product tells you which: see new_code_after_spend and new_code_after_top_up on Look up a product. When the code changes, the old code fails with pin_code_replaced and the new code is sent once:

Replace the stored code with the new one each time, and give it to your customer. To receive codes changed by brand redemptions, attach a webhook_id when you issue the PIN, or add one later with Change the webhook on a PIN. You are the only one who receives a code changed by a redemption: brands are sent just its mask. Without a webhook (or the customer delivery you set when issuing), that new code reaches nobody and the PIN can't be used again.

Getting started

1. Switch your dashboard to test mode

   API keys and webhooks belong to the mode your dashboard is in when you create them.

2. Create a test API key

   Go to API keys and generate a key. Copy the key ID and the secret; the secret is shown only once.

3. Sign a first request

   Call GET /reseller/wallets with the code in Authentication.

4. Add a webhook

   Register an endpoint under Webhooks so your server hears about changes. Webhooks guide

5. Follow the integration guide, then pass UAT

   The integration guide walks through the full flow in test mode. When it works, run the Go-live checklist to request live access.