Give a PIN a new code · API reference

POST https://afropin.com/api/v1/brand/pins/new-code

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

With an SDK

PHP$afropin->brand->pins->newCode($params)

Node.jsafropin.brand.pins.newCode(params)

Pythonafropin.brand.pins.new_code(params)

Javaafropin.brand().pins().newCode(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, and be active.

Response fields

pin_code string Required

The PIN's new code. Give it to your customer the way you deliver codes today, after checking it is really them.

pin_mask string Required

The new code with its middle digits hidden.

previous_pin_mask string Required

The mask of the code that just stopped working.

balance number Required

The PIN's balance, unchanged.

customer object Required

The customer on the PIN, as when it was issued. It can't be changed, so a new code always belongs to the same customer.

reissued_at string Required

When the code was replaced, ISO 8601 in UTC.

We never store PIN codes
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

A PIN with a webhook receives a pin.code_changed event with the new code. When the PIN has handle_delivery on, we also send the customer the new code for you. How delivery works. You can also reissue from the PIN's page in your dashboard, which emails the customer without showing the code to anyone.

Check that the person asking really is the PIN's customer before you deliver a new code. A PIN can be reissued 5 times a day; more fail with reissue_limit_reached.

Request

{
    "pin_id": "e83f72e0-997c-4ca8-aee8-04a7423a1bd4"
}

Response 200

{
    "ok": true,
    "data": {
        "pin_id": "e83f72e0-997c-4ca8-aee8-04a7423a1bd4",
        "pin_code": "2923-5810-4476-1441",
        "pin_mask": "2923-****-****-1441",
        "previous_pin_mask": "3093-****-****-3097",
        "balance": 6000,
        "currency": "NGN",
        "status": "active",
        "mode": "live",
        "customer": {
            "first_name": "Ada",
            "last_name": "Okafor",
            "email": "[email protected]",
            "phone": null
        },
        "expires_at": "2027-10-28T09:14:22.000000Z",
        "reissued_at": "2026-10-28T09:14:22.000000Z"
    }
}

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

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

404 pin_not_found No PIN has this id

403 pin_expired This PIN has expired

403 pin_blocked This PIN is blocked

429 reissue_limit_reached This PIN's code has been reissued too many times today. Try again tomorrow

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 →