Add to phone wallets · API reference

POST https://afropin.com/api/v1/reseller/pins/wallet-links

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

With an SDK

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

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

Pythonafropin.reseller.pins.wallet_links(params)

Javaafropin.reseller().pins().walletLinks(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.

pin_code string Required

The PIN's current code, with or without dashes. We only keep a fingerprint of codes, so you send it to prove you hold the PIN and so the pass can show it. A code that has been replaced fails with pin_code_replaced.

Response fields

pin_id uuid Required

The PIN.

pin_mask string Required

The code the pass shows, with its middle digits hidden.

google_wallet_url string Required

The "Add to Google Wallet" link, for Android phones. It opens Google Wallet, or a web page elsewhere. You can ask for it again at any time. Null if Google Wallet could not be reached.

apple_wallet_url string Required

The "Add to Apple Wallet" link, for iPhones: opened in Safari it shows the pass with an Add button. Each call makes a new link. Null if Apple Wallet is not available.

What keeps the pass up to date

Balance

Every spend and top-up updates the balance on the pass.

New codes

When the PIN gets a new code (a top-up or spend on a product that rotates codes, or Give a PIN a new code), the pass shows the new code and QR. There is nothing for you to call.

Status

A blocked PIN shows as inactive, an expired one as expired, and a spent single-use PIN as completed. Unblocking makes the pass active again.

Show your customer both links, or pick one from their phone: an iPhone gets apple_wallet_url, any other phone google_wallet_url. Use the official "Add to Apple Wallet" and "Add to Google Wallet" badges as the buttons.

Add "wallet_links": true to Sell a PIN or a printed card activation to get google_wallet_url and apple_wallet_url in the same response, without a second call.

Whoever opens a link can add the pass and see the code, so send links only to the PIN's customer, the way you send the code itself. A Google pass stays with the first Google account that saves it. An Apple pass can't be shared from the iPhone. Wrong codes count towards the same limit as other PIN checks.

Google Wallet works on Android phones in Nigeria, and Apple Wallet on any iPhone. Test PINs work too: their passes are labelled as test PINs.

An iPhone downloads its pass from us again whenever the PIN changes, so an Apple pass keeps its PIN's code sealed with a key that only that pass holds. We can't read it from our systems; it is opened only when the customer's iPhone asks for the pass. The sealed code is deleted when the PIN is blocked, expires or is spent, or the pass is removed from the customer's devices. PINs without an Apple pass keep no code at all.

Request

{
    "pin_id": "e83f72e0-997c-4ca8-aee8-04a7423a1bd4",
    "pin_code": "2923-5810-4476-1441"
}

Response 200

{
    "ok": true,
    "data": {
        "pin_id": "e83f72e0-997c-4ca8-aee8-04a7423a1bd4",
        "pin_mask": "2923-****-****-1441",
        "google_wallet_url": "https://pay.google.com/gp/v/save/eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3Mi...",
        "apple_wallet_url": "https://afropin.com/api/wallet/apple/add/0fbdf173-db9d-4efa-837b-42e621e8af98/SFkz3ZWoF6Ph0d0cZi_JVv3fyl3UU5hkvbPrvqxwcsw"
    }
}

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_blocked This PIN is blocked

403 pin_expired This PIN has expired

422 pin_checksum_failed This is not a valid PIN code: its check digit is wrong

404 pin_code_unknown No PIN has this code

403 pin_code_replaced This code has been replaced by a newer one; ask the customer for their latest code

503 wallet_unavailable Wallet passes are not available right now. Try again later

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 →