Payments received · API reference

GET https://afropin.com/api/v1/brand/payments

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

With an SDK

PHP$afropin->brand->payments->list($params)

Node.jsafropin.brand.payments.list(params)

Pythonafropin.brand.payments.list(params)

Javaafropin.brand().payments().list(params)

Query parameters

limit integer Optional min 1

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

day date Optional YYYY-MM-DD

Only return redemptions made on this day, for example 2026-10-27.

store_id uuid Optional

Only return redemptions at this store.

terminal_id uuid Optional

Only return redemptions run by this terminal.

page integer | "all" Optional

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

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.

Only redemptions in the mode of your API key are listed: a test key returns test redemptions, a live key live ones.

Redemption object

id uuid Required

ID of the credit on your wallet. Use it with Look up a payment. It is not the same value as the transaction_ref returned by Take payment with a PIN, but either one finds the redemption.

external_reference string | null Required

The reference you sent when redeeming. null for test-mode redemptions.

store_id uuid | null Required

The store that took the payment, if one was sent.

terminal_id uuid | null Required

The POS terminal that ran the redemption: the terminal_id sent to Redeem, or the terminal signed in to the terminal portal. null when none was named.

pin_mask string | null Required

The PIN code that was redeemed, with the middle digits hidden.

amount number Required

What left the PIN, truncated to 2 decimal places: the amount redeemed, plus the fee when the customer paid it. Your wallet received amount less fee.

fee number Required

The redemption fee.

fee_paid_by string Required brand customer

Who paid the fee. brand for redemptions made before this option existed.

currency string Required

Currency of the wallet credited.

balance_before number Required

Your wallet balance before the credit.

balance_after number Required

Your wallet balance after the credit. In live mode it rises by the amount less your redemption fee.

direction string Required in

Always in: the entry on your wallet.

type string Required pin_spend

Always pin_spend.

status string Required success

Redemptions settle immediately, so this is success.

mode string Required test live

Mode the redemption was made in.

created_at string Required

When the redemption was made, ISO 8601 in UTC.

Response 200

{
    "ok": true,
    "data": [
        {
            "id": "dcb2e747-5988-4553-ad05-371b5e707724",
            "external_reference": "order_98231",
            "store_id": "5c1e8f2a-7b3d-4e19-a6c0-2d9f4b8e1a73",
            "terminal_id": "9b7d2c41-3e8f-4a65-b1d0-7c2e9f4a8b16",
            "pin_mask": "3093-****-****-3097",
            "amount": 2500,
            "fee": 150,
            "fee_paid_by": "brand",
            "currency": "NGN",
            "balance_before": 120000,
            "balance_after": 122462.5,
            "direction": "in",
            "type": "pin_spend",
            "status": "success",
            "mode": "live",
            "created_at": "2026-10-27T09:14:22.000000Z"
        }
    ],
    "paging": {
        "page": 1,
        "pages": 1,
        "per_page": 20,
        "total": 1,
        "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

500 internal_error Something went wrong on our side. Try again; if it keeps happening, contact support

{
    "ok": false,
    "error": {
        "code": "wrong_account_type",
        "message": "Your account type cannot use this endpoint",
        "fields": null
    }
}

All error codes →