Testing

Simulate an inbound payment without moving real money.

Contents

What test mode gives you

A test key exercises the same routes, the same validation, the same ledger, and the same webhook signing as a live key. The only difference is the gateway behind it: test always routes through a stub that never contacts a bank, never moves money, and never charges a fee.

Virtual accounts are minted with plausible-looking numbers that nobody can pay into.
Payouts are accepted and settled without a transfer ever leaving.
Name enquiry resolves through the stub, so it costs nothing and is always available.
Every fee is zero — size your economics from live pricing, not from what you see here.

Simulating an inbound payment

Nobody is going to transfer into a test virtual account, so a collection would sit in awaiting_payment forever. This endpoint drives the same settlement path a real gateway webhook would: the ledger is posted, the collection is marked succeeded, the account is closed, and a real collection.success webhook is delivered to your endpoint.

POST/v1/sandbox/simulate/collection-success

Auth: Secret key

Test keys only. A live key is rejected with 403 SANDBOX_TEST_KEY_REQUIRED before the handler runs.

Body

Field	Type	Description
virtualAccountReferencerequired	string	The `reference` returned when you minted the account. Must be a test-environment account belonging to you.

curl

curl -X POST https://api.radokpay.com/v1/sandbox/simulate/collection-success \
  -H "Authorization: Bearer $RADOK_TEST_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "virtualAccountReference": "va_9f4c1b8e2d7a6c05" }'

200 OK

{
  "data": { "simulated": true }
}

The simulated payment is for the exact amount the account expects. Calling it twice for the same account returns 409 SANDBOX_SIMULATION_FAILED — the collection has already settled, and settlement is idempotent by design.

A crypto checkout has no broadcast in test mode. Post the collection reference to settle it on the same path a confirmed USDC transfer would, including the USD ledger credit and collection.success.

POST/v1/sandbox/simulate/crypto-payment

Auth: Secret key

Test keys only.

Body

Field	Type	Description
referencerequired	string	The crypto collection reference.
chain	string	ethereum, polygon, bsc, or tron. Defaults to polygon.
token	string	USDT or USDC. Defaults to USDC.
confirmNow	boolean	When false, the collection stays confirming and nothing is credited yet.

An end-to-end test

Node.js

const BASE = "https://api.radokpay.com/v1";
const headers = {
  Authorization: `Bearer ${process.env.RADOK_TEST_SECRET_KEY}`,
  "Content-Type": "application/json",
};

// 1. Mint an account for ₦5,000.00
const mint = await fetch(`${BASE}/virtual-accounts`, {
  method: "POST",
  headers,
  body: JSON.stringify({
    customerEmail: "ada@example.com",
    amount: { value: 500_000, currency: "NGN" },
    expiresInMinutes: 60,
  }),
});
const { data: account } = await mint.json();

// 2. Stand in for the customer's bank transfer.
await fetch(`${BASE}/sandbox/simulate/collection-success`, {
  method: "POST",
  headers,
  body: JSON.stringify({ virtualAccountReference: account.reference }),
});

// 3. The collection has settled and your webhook has already been delivered.
const check = await fetch(
  `${BASE}/collections/${account.collection.reference}`,
  { headers },
);
const { data: collection } = await check.json();

console.assert(collection.status === "succeeded");

Testing your webhook handler

Expose your local server with a tunnel. A localhost URL is rejected — private and loopback addresses are blocked, and the check is repeated at delivery time.
Save the tunnel URL as your TEST webhook endpoint and generate a test signing secret.
Press Send test event. Your endpoint gets a real signed request, and the dashboard shows you the status it returned.
Then run the simulation above to exercise a real collection.success payload rather than the test stub.
When something fails, open the delivery to see the exact bytes we sent and the body you returned. Use Replay to retry after a fix — see Inspecting and replaying deliveries.

Test secrets differ from live secrets

Signing is identical in both environments, but the secret is not shared. A verifier hard-coded to one environment’s secret will reject every delivery in the other.

Going live

Get KYB approved. Live keys cannot be created until it is.
Create a live secret key and deploy it. Keep the test key working in staging.
Configure the LIVE webhook endpoint and generate its own signing secret — none of this carries over from test.
Add a live payout account and set it as the default.
Re-check your fee assumptions. Test mode charged you nothing.
Send one small real payment end to end before pointing customers at it.