Reference
Endpoint Catalog
At-a-glance table of all 11 S2S endpoints — method, path, HMAC auth, and Idempotency-Key requirements
All 11 endpoints in one table. Every S2S request must be HMAC-signed except the public GET /v1/banks. The "Idempotency-Key" column marks the money-moving POSTs that require the header.
Endpoints
| # | Method | Path | Auth (HMAC) | Idempotency-Key | Summary |
|---|---|---|---|---|---|
| 1 | POST | /v1/deposits | ✅ | ✅ | Create a deposit; returns expected_amount + pay_to/qr_payload, status PENDING. |
| 2 | GET | /v1/deposits/:id | ✅ | — | Poll deposit status; pay_to only while PENDING. |
| 3 | POST | /v1/deposits/:id/cancel | ✅ | — | Cancel a still-PENDING deposit. |
| 4 | POST | /v1/withdrawals | ✅ | ✅ | Create a payout; debits gross (amount + fee) immediately, status PENDING. |
| 5 | GET | /v1/withdrawals/:id | ✅ | — | Get one withdrawal (caller-scoped). |
| 6 | GET | /v1/withdrawals | ✅ | — | List the caller's own withdrawals. |
| 7 | GET | /v1/balance | ✅ | — | Wallet balance (available + pending). |
| 8 | GET | /v1/banks | ❌ public | — | Public bank master keyed by bank_code; Cache-Control: max-age=3600. |
| 9 | POST | /v1/test/simulate-transfer | ✅ | ✅ | Sandbox only: inject a transfer into a PENDING test deposit; live key → 404. |
| 10 | POST | /v1/test/top-up | ✅ | ✅ | Sandbox only: credit the test balance (≤ 1,000,000 / call); live key → 404. |
| 11 | POST | /v1/test/reset | ✅ | ✅ | Sandbox only: wipe all of your own test data; live key → 404. |
Mode (live vs test) is derived from the key prefix (
unk_live_ / unk_test_), never from the URL. The three /v1/test/* endpoints only work with a test key — a live key gets 404 NOT_FOUND.