Activate a printed card · API reference

POST https://afropin.com/api/v1/brand/cards/activate

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

With an SDK

PHP$afropin->brand->cards->activate($params)

Node.jsafropin.brand.cards.activate(params)

Pythonafropin.brand.cards.activate(params)

Javaafropin.brand().cards().activate(params)

Body parameters

card_number string Required 19 digits

The number printed on the card. The card must be yours, not yet activated, and its order must have shipped.

amount numeric Required

The value to load, debited from your balance. It must be between the product min and max, or one of its denominations for set_amounts products.

external_reference string Required max 191

Your own reference for this activation, unique across everything you issue. A reused reference fails with duplicate_external_reference.

first_name string Required max 255

Customer's first name.

last_name string Required max 255

Customer's last name.

email string Required max 255

Customer's email address.

phone_code string Required with phone max 2

ISO country code of the phone number, e.g. NG.

phone string Optional

Customer's phone number.

webhook_id uuid Optional

A webhook to attach to the new PIN, as when issuing.

handle_delivery boolean Optional

true to have us send the customer their code now and every new code after it, as when issuing. Defaults to false. How delivery works

store_id string Required if your account enforces purchase locations max 255

The purchase location selling the card.

terminal_id uuid Optional

One of your terminals, to record which till activated the card. Another business's terminal fails with invalid_terminal_id.

wallet_links boolean Optional

Send true to get a google_wallet_url and apple_wallet_url for the new PIN, as when issuing.

Response fields

Every field of Issue a PIN

The new PIN: pin_id, pin_code, pin_mask, amount, balance and the rest.

card_mask, serial, order_reference

The card that was activated, now retired.

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

Physical cards are live stock: use live API keys, and the PIN issued is always a live PIN. Your purchase commission is credited as for any issue. The pin.sold webhook for the new PIN carries the card in physical_card.

Request

{
    "card_number": "9307 9280 2477 8142 827",
    "amount": 7500,
    "external_reference": "card-activation-1093",
    "first_name": "Amina",
    "last_name": "Sule",
    "email": "[email protected]",
    "wallet_links": true
}

Response 200

{
    "ok": true,
    "data": {
        "pin_id": "b2f8c3a1-1d4e-4f6a-9b7c-0e2d5a8f1c3b",
        "transaction_ref": "c0a9e8f7-6d5c-4b3a-9e8d-7c6b5a4f3e2d",
        "pin_code": "1909-4417-2286-7527",
        "pin_mask": "1909-****-****-7527",
        "amount": 7500,
        "balance": 7500,
        "currency": "NGN",
        "mode": "live",
        "status": "active",
        "external_reference": "card-activation-1093",
        "card_mask": "9307 **** **** **** 827",
        "serial": 1,
        "order_reference": "PVO-MWEFCT3D",
        "google_wallet_url": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3Mi...",
        "apple_wallet_url": "https://afropin.com/api/wallet/apple/add/6c1e9a40-27d3-4b8e-9f15-3a7d0c2b84e1/q3Vh0nB7xLp2RkT9mYdW4sEa8cJf6uZiNo1gHbKtMv5"
    }
}

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 physical_vouchers_not_permitted Printed cards are not switched on for your account. Contact support

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

404 physical_voucher_not_found No printed card has this number

409 physical_voucher_not_shipped This card's order has not shipped yet

409 physical_voucher_already_activated This card has already been activated

409 physical_voucher_void This card has been cancelled

422 invalid_terminal_id No terminal of yours has this terminal_id

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

422 duplicate_external_reference You have sent this external_reference before

404 invalid_webhook_id No webhook of yours has this webhook_id

422 invalid_store_id No store of yours has this store_id

403 pin_type_inactive This PIN type is paused

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 internal_error Something went wrong on our side. Try again; if it keeps happening, contact support

{
    "ok": false,
    "error": {
        "code": "physical_voucher_not_found",
        "message": "No printed card has this number",
        "fields": null
    }
}

All error codes →