A PIN's history · API reference

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

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

With an SDK

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

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

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

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

Path parameters

voucher uuid Required

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

Query parameters

day string Optional date

Only return transactions created on this date, for example 2026-10-27.

limit integer Optional min 1

Transactions per page. Defaults to 20. Ignored when page=all.

page integer | "all" Optional

Page to return, starting at 1. Pass all to return every transaction without pagination.

Response fields

id

Transaction ID. Matches the transaction_ref returned by issue and top-up calls.

direction

in (money onto the PIN) or out (money off it).

type

pin_sale, pin_top_up or pin_spend.

status

success.

amount

Amount as a number, truncated to 2 decimal places.

balance_before, balance_after

PIN balance around this transaction.

external_reference

The reference sent with the request that created it.

store_id

The purchase or redemption location, or null.

Paged responses carry a paging object with page, pages, total and the next and previous page URLs. It is left out when page=all. A page number below 1 or any other text fails with validation_error.

Request

GET /api/v1/reseller/pins/e83f72e0-997c-4ca8-aee8-04a7423a1bd4/movements?limit=20

Response 200

{
    "ok": true,
    "data": [
        {
            "id": "3c6bb90c-4dc9-4e01-bdf2-75e91199847d",
            "external_reference": "rdm-55120",
            "store_id": "b7e2c4a1-3f58-4d9e-8a61-2c0f9b4d7e13",
            "amount": 500,
            "currency": "NGN",
            "balance_before": 5000,
            "balance_after": 4500,
            "direction": "out",
            "type": "pin_spend",
            "status": "success",
            "mode": "test",
            "created_at": "2026-10-27T11:02:10.000000Z"
        },
        {
            "id": "98d90ca6-b842-4596-af08-bce3c47c9857",
            "external_reference": "order-7f3a91",
            "store_id": null,
            "amount": 5000,
            "currency": "NGN",
            "balance_before": 0,
            "balance_after": 5000,
            "direction": "in",
            "type": "pin_sale",
            "status": "success",
            "mode": "test",
            "created_at": "2026-10-27T09:14:22.000000Z"
        }
    ],
    "paging": {
        "page": 1,
        "pages": 1,
        "per_page": 20,
        "total": 2,
        "next": null,
        "previous": null
    }
}

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

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 →