Event reference

Every event Radok sends, with its exact payload.

Contents

The envelope

Every event has the same four top-level fields. Only data varies, and this page documents each shape exactly as it is sent.

Envelope

{
  "id": "evt_7c1f3a9d2b8e4506",
  "type": "collection.success",
  "createdAt": "2026-08-23T11:42:10.000Z",
  "data": { }
}

Treat unknown types as a no-op

New events are added over time and are not a breaking change. A handler that throws on an unrecognised type turns a new feature into a flood of failed deliveries.

Event catalogue

All events

Field	Type	Description
collection.success	money in	A collection was paid and your balance credited.
collection.failed	money in	A naira collection expired or failed.
collection.underpaid	money in	A crypto checkout closed short. The amount received was credited.
collection.expired	money in	A crypto checkout window ended with nothing confirmed.
collection.late_payment	money in	Crypto arrived after the window. Credited, and the order is not reopened.
crypto.payment.confirming	money in	A USDT or USDC transfer was seen and is waiting for confirmations.
crypto.payment.confirmed	money in	A seen transfer reached the confirmation threshold.
crypto.unsolicited	money in	Crypto arrived after the collection had already settled.
payout.success	money out	A payout reached the destination account.
payout.failed	money out	A payout failed and was reversed.
wallet.funding.success	money in	A deposit landed in your wallet funding account.
kyc.succeeded	identity	A BVN or NIN verification matched.
kyc.failed	identity	A BVN or NIN verification did not match.
webhook.test	diagnostic	Sent only by Send test event. Never emitted by real activity.

Money arrived and settled. This is the event to fulfil an order on. Credit your customer against netAmount if you reconcile balances — amount is what they paid, but netAmount is what reached you.

Payload

{
  "id": "evt_7c1f3a9d2b8e4506",
  "type": "collection.success",
  "createdAt": "2026-08-23T11:42:10.000Z",
  "data": {
    "reference": "col_3a7d5e1f9b2c4d68",
    "amount":    { "value": 500000, "currency": "NGN" },
    "netAmount": { "value": 495000, "currency": "NGN" },
    "paidAt": "2026-08-23T11:42:10.000Z"
  }
}

data

Field	Type	Description
reference	string	The collection reference. Match this against your order.
amount	money	What the customer paid.
netAmount	money	What was credited to your balance, after the platform fee.
paidAt	string	ISO 8601 settlement time.
paymentLinkId	string	Present only when the payment came from a payment link. Absent for a directly minted virtual account.

From a payment link

{
  "id": "evt_2b9e4d1a7f3c8065",
  "type": "collection.success",
  "createdAt": "2026-08-23T14:05:31.000Z",
  "data": {
    "reference": "col_9c2f7b4e1a8d3502",
    "amount":    { "value": 25000000, "currency": "NGN" },
    "netAmount": { "value": 24750000, "currency": "NGN" },
    "paymentLinkId": "652f1a9c4d7b3e0812345678",
    "paidAt": "2026-08-23T14:05:31.000Z"
  }
}

collection.failed

The collection will not be paid. In practice this almost always means the window lapsed. Handle it, or unpaid orders sit pending indefinitely.

Payload

{
  "id": "evt_5d8a2c6f0b9e1743",
  "type": "collection.failed",
  "createdAt": "2026-08-23T12:30:00.000Z",
  "data": {
    "reference": "col_3a7d5e1f9b2c4d68",
    "reason": "expired"
  }
}

data

Field	Type	Description
reference	string	The collection reference.
reason	string	Why it failed. `expired` is the common case. Log unknown values rather than branching exhaustively.

Payout events

payout.success

The money reached the destination account. Safe to tell the recipient it has landed.

Payload

{
  "id": "evt_1f7b3e9c5a2d8064",
  "type": "payout.success",
  "createdAt": "2026-08-23T11:31:12.000Z",
  "data": {
    "reference": "pyt_4e8a1c6b3f0d2957",
    "amount": { "value": 250000, "currency": "NGN" }
  }
}

data

Field	Type	Description
reference	string	The payout reference.
amount	money	What the recipient received. The fee is not included.

payout.failed

The transfer did not complete. By the time this event is sent the reservation has already been reversed and the full debit — amount plus fee — credited back to your balance. Do not issue your own refund on top of it.

Payload

{
  "id": "evt_6a0d4f2b8c1e5739",
  "type": "payout.failed",
  "createdAt": "2026-08-23T11:33:48.000Z",
  "data": {
    "reference": "pyt_4e8a1c6b3f0d2957",
    "reason": "destination account is dormant"
  }
}

data

Field	Type	Description
reference	string	The payout reference.
reason	string	Free text from the bank or gateway. Show it to whoever will act on it.

Wallet events

wallet.funding.success

A deposit landed in your permanent wallet funding account — money you sent yourself to top up your payout balance, rather than a customer payment. Unlike a collection account, the funding account stays open and reusable.

Payload

{
  "id": "evt_8e3c1a7d5b9f0246",
  "type": "wallet.funding.success",
  "createdAt": "2026-08-23T09:15:02.000Z",
  "data": {
    "virtualAccountReference": "va_2c8f1b7e4a3d9605",
    "amount": { "value": 10000000, "currency": "NGN" },
    "paidAt": "2026-08-23T09:15:02.000Z"
  }
}

data

Field	Type	Description
virtualAccountReference	string	Your funding account's reference.
amount	money	Credited in full — funding deposits carry no platform fee.
paidAt	string	ISO 8601.

Identity events

kyc.succeeded and kyc.failed

Emitted after a BVN or NIN verification resolves. Both carry the same shape; verified tells them apart within the payload as well as by type.

Payload

{
  "id": "evt_3b7f9d1c6e2a4850",
  "type": "kyc.succeeded",
  "createdAt": "2026-08-23T10:02:19.000Z",
  "data": {
    "reference": "kyc_7d2a9f4c1b8e3506",
    "type": "bvn",
    "verified": true,
    "name": "ADA LOVELACE"
  }
}

data

Field	Type	Description
reference	string	The verification request reference.
type	string	`bvn` or `nin`.
verified	boolean	Whether the identity matched.
name	string	The name on record when the provider returned one. Prefer `verified` (and the event `type`) over assuming `name` is present or absent.

webhook.test

Sent only when you press Send test event in the dashboard. It is delivered regardless of your subscriptions — it is a connectivity check, not something to opt into — and it is never produced by real activity, so it is safe to ignore in your handler.

Payload

{
  "id": "evt_test_1755948123456",
  "type": "webhook.test",
  "createdAt": "2026-08-23T11:22:03.456Z",
  "data": { "message": "This is a test event." }
}

Use it to confirm your URL is reachable, your TLS is valid, and your signature check passes.
The dashboard shows the HTTP status you returned, so a 401 from your own auth middleware is visible immediately.

The envelope

Event catalogue

Collection events

collection.success

collection.failed

Payout events

payout.success

payout.failed

Wallet events

wallet.funding.success

Identity events

kyc.succeeded and kyc.failed

webhook.test