Look up a PIN · API reference

GET https://afropin.com/api/v1/brand/pins/{pin_id}

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

With an SDK

PHP$afropin->brand->pins->get($pinId, $params)

Node.jsafropin.brand.pins.get(pinId, params)

Pythonafropin.brand.pins.get(pin_id, params)

Javaafropin.brand().pins().get(pinId, params)

Path parameters

voucher uuid Required

The PIN pin_id returned when it was issued. It must belong to your account and to the mode of your API key.

Response fields

balance

Current balance.

status

active, blocked or expired.

pin_mask

Mask of the code that works now. Only this code can be redeemed.

past_pin_masks

Masks of every code the PIN has had, oldest first. A new code is added when a product rotates codes on top-up.

webhook_id

Webhook that receives this PIN's events, or null.

customer

Name, email and phone given at issue. phone is null when none was given. whatsapp says whether codes we deliver also go to the phone on WhatsApp.

handle_delivery

Whether we send the customer every new code and change, or you do. How delivery works

keep_code, keep_code_chosen_at, keep_code_via

Whether the customer chose to keep one code, and when and where they agreed to it: api, terminal, dashboard (Bulk send) or quote. A new code ends it.

frozen_by

Who froze the PIN, or null if it isn't frozen. seller means you did; only you can unfreeze it. cardholder means the customer did, in their card account; only they can unfreeze it. You hear of each change through pin.frozen and pin.unfrozen.

parent_pin_id, family_card_ids

Family cards are extra cards a customer makes from their own card for family members, and fills by moving money onto them. parent_pin_id is the card this one gets its money from (only on a family card). family_card_ids lists the family cards this card fills. You hear of each move through pin.moved.

daily_limit, daily_limit_left

The PIN's daily spending limit and what is left of it today, or null without one.

expires_at, sold_at

ISO 8601 timestamps in UTC.

The full PIN code is never returned after issue. Only masks are available.

Request

GET /api/v1/reseller/pins/e83f72e0-997c-4ca8-aee8-04a7423a1bd4

Response 200

{
    "ok": true,
    "data": {
        "pin_id": "e83f72e0-997c-4ca8-aee8-04a7423a1bd4",
        "webhook_id": "3693382f-d2f0-4966-88f7-26d03c454940",
        "balance": 3500,
        "currency": "NGN",
        "pin_mask": "7676-****-****-6608",
        "past_pin_masks": [
            "3093-****-****-3097",
            "7676-****-****-6608"
        ],
        "mode": "test",
        "customer": {
            "first_name": "Ada",
            "last_name": "Okafor",
            "email": "[email protected]",
            "phone": "+2348031234567",
            "whatsapp": true
        },
        "handle_delivery": true,
        "status": "active",
        "expires_at": "2027-10-27T09:14:22.000000Z",
        "sold_at": "2026-10-27T09:14:22.000000Z"
    }
}

Errors

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

403 wrong_account_type Your account type cannot use this endpoint

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

404 pin_not_found No PIN has this id

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 →