Top up a PIN · API reference

POST https://afropin.com/api/v1/reseller/pins/top-up

HMAC-signed request with a unique Idempotency-Key header. Authentication

With an SDK

PHP$afropin->reseller->pins->topUp($params)

Node.jsafropin.reseller.pins.topUp(params)

Pythonafropin.reseller.pins.top_up(params)

Javaafropin.reseller().pins().topUp(params)

Body parameters

pin_id uuid Required

The PIN pin_id. It must belong to your account and to the mode of your API key.

amount numeric Required

Amount to add. The new balance must stay between the product min and max. For set_amounts products the amount itself must also be one of the denominations.

external_reference string Required max 191

Your own reference for this top-up, unique across all your issues and top-ups. A reused reference fails with duplicate_external_reference.

store_id string Required if your account enforces purchase locations max 255

ID of the active purchase location making the sale, from Your stores.

Response fields

transaction_ref

ID of the credit to the PIN.

amount, balance

Amount added and the PIN balance afterwards.

new_pin_code

When the product has new_code_after_top_up, the PIN gets a new code: it is returned here, only once, and the old code stops working. Otherwise null.

new_pin_mask

Mask of the new code, or null.

We never store PIN codes
new_pin_code is the only time you will see this code. Save it securely before you respond to your customer: we keep only a one-way fingerprint of it, so a lost code can never be shown again. If your customer loses it, reissue the PIN to give it a new code; the balance is kept. Storing PIN codes

The product must support top-ups (topup: true) and the PIN must be active. Your purchase commission on the top-up is credited to your commission balance.

Request

{
    "pin_id": "e83f72e0-997c-4ca8-aee8-04a7423a1bd4",
    "amount": 2500,
    "external_reference": "topup-7f3a91"
}

Response 200

{
    "ok": true,
    "data": {
        "pin_id": "e83f72e0-997c-4ca8-aee8-04a7423a1bd4",
        "transaction_ref": "92b7ed4d-f067-4d74-b131-c4a85dc3bc51",
        "store_id": null,
        "new_pin_code": null,
        "new_pin_mask": null,
        "amount": 2500,
        "balance": 6000,
        "currency": "NGN",
        "mode": "test",
        "customer": {
            "first_name": "Ada",
            "last_name": "Okafor",
            "email": "[email protected]",
            "phone": "+2348031234567"
        },
        "status": "active",
        "external_reference": "topup-7f3a91"
    }
}

Errors

Failed requests return a stable code with a translated message. Branch on code, never on the message.

422 validation_error Some fields are missing or invalid

403 wrong_account_type Your account type cannot use this endpoint

403 issuing_disabled Issuing PINs is not switched on for your account. Contact support

429 rate_limited Too many requests. Wait a moment and try again

422 duplicate_external_reference You have sent this external_reference before

422 invalid_store_id No store of yours has this store_id

404 pin_not_found No PIN has this id

403 topup_not_allowed This PIN type cannot be topped up

403 pin_blocked This PIN is blocked

403 pin_expired This PIN has expired

403 pin_type_inactive This PIN type is paused

403 product_inactive This product is switched off

422 amount_not_offered This product is only sold in set amounts, and this is not one of them

422 amount_too_small The amount is below this product's minimum

422 amount_too_large The amount is above this product's maximum

403 currency_not_supported Your account has no wallet in this currency

402 wallet_balance_low Your wallet balance does not cover this amount

500 pin_generation_failed A new PIN code could not be created. Try again

500 internal_error Something went wrong on our side. Try again; if it keeps happening, contact support

{
    "ok": false,
    "error": {
        "code": "pin_not_found",
        "message": "No PIN has this id",
        "fields": null
    }
}

All error codes →