Collections

Track what a customer owes and whether it has been paid.

Contents

What a collection is

A collection is the record of one payment you expect to receive: how much, from whom, and whether it has arrived. It is created for you whenever a virtual account is minted or a payment link is paid, so there is no endpoint to create one directly — a collection always has a payment method attached.

The collection reference, not the virtual account reference, is what you should store against your own order.

Lifecycle

Status

Field	Type	Description
pending	initial	Created, but the payment method is not ready yet. Usually momentary.
awaiting_payment	open	A virtual account exists and is waiting for the transfer. This is where most of the wait happens.
succeeded	terminal	Money received and your balance credited. Fires `collection.success`.
expired	terminal	The window lapsed without payment. Fires `collection.failed` with `reason: "expired"`.
failed	terminal	The payment could not be completed. Fires `collection.failed`.

Terminal means terminal

A collection never leaves succeeded, expired, or failed. If a customer pays after expiry, that is handled as a separate inflow — mint a fresh account rather than waiting for the old one to settle.

Amount, fee, and what you actually receive

Three amounts appear on every collection, and they are easy to confuse. In test mode the fee is always zero.

Amounts

Field	Type	Description
amount	money	What the customer paid.
platformFee	money	What Radok charged, per your pricing plan.
netAmount	money	What was credited to your balance: `amount − platformFee`. This is the figure to reconcile against.

List collections

GET/v1/collections

Auth: Secret key or dashboard session
Scope: collections:read

Query

Field	Type	Description
limit	integer	1–100. Defaults to 20.
cursor	string	From `meta.nextCursor`.
environment	string	Required for dashboard sessions only. `test` or `live`.

curl

curl "https://api.radokpay.com/v1/collections?limit=1" \
  -H "Authorization: Bearer $RADOK_SECRET_KEY"

200 OK

{
  "data": [
    {
      "reference": "col_3a7d5e1f9b2c4d68",
      "amount": { "value": 500000, "currency": "NGN" },
      "platformFee": { "value": 5000, "currency": "NGN" },
      "netAmount": { "value": 495000, "currency": "NGN" },
      "status": "succeeded",
      "customerEmail": "ada@example.com",
      "customerName": "Ada Lovelace",
      "paidAt": "2026-08-23T11:42:10.000Z",
      "expiresAt": "2026-08-23T12:30:00.000Z",
      "createdAt": "2026-08-23T11:30:00.000Z"
    }
  ],
  "meta": { "nextCursor": "652f1a9c4d7b3e0812345678", "hasMore": true }
}

Retrieve a collection

GET/v1/collections/{reference}

Auth: Secret key or dashboard session
Scope: collections:read

curl

curl https://api.radokpay.com/v1/collections/col_3a7d5e1f9b2c4d68 \
  -H "Authorization: Bearer $RADOK_SECRET_KEY"

Use this to confirm state after receiving a webhook, or to reconcile in a nightly job. A reference belonging to another merchant returns 404.