Sandbox
Top-up & Reset
Credit your test balance and wipe your own test data — two sandbox-only triggers
These two sandbox-only triggers let you set up and tear down test state. Both require HMAC + Idempotency-Key, and both return 404 if you call them with a live key.
Top-up — POST /v1/test/top-up
POST /v1/test/top-up
Credit your test balance directly (test ledger only — it never touches your live balance). Use it to rehearse flows that need a balance, such as withdrawals.
Request body (TopUpReq)
| field | type | required | description |
|---|---|---|---|
amount | string (baht) | yes | The amount to credit, e.g. "1000.00". Must be > 0. |
currency | string | no | Currency (can be omitted; the response returns "THB"). |
Response (200, TopUpResult)
{
"amount": "1000.00",
"currency": "THB",
"status": "credited"
}
Limits / cap
| Situation | HTTP | code |
|---|---|---|
amount ≤ 0 | 422 | INVALID_AMOUNT |
amount malformed | 422 | INVALID_AMOUNT |
| Over the sandbox cap of 1,000,000 baht per call | 422 | AMOUNT_TOO_LARGE |
currency fails validation | 422 | INVALID_CURRENCY |
| More than 60 calls/minute per merchant | 429 | RATE_LIMITED |
| Live key | 404 | NOT_FOUND |
Example request
cURL
curl -X POST https://api.unkpay.co/v1/test/top-up \
-H "X-Api-Key: unk_test_xxxxxxxxxxxxxxxx" \
-H "X-Timestamp: 1718790000" \
-H "X-Signature: <hex hmac>" \
-H "Idempotency-Key: topup-0001" \
-H "Content-Type: application/json" \
-d '{"amount":"1000.00","currency":"THB"}'
Reset — POST /v1/test/reset
POST /v1/test/reset
Wipe all of your own test data atomically: test deposits + withdrawals + any test bank_transactions/unmatched produced + the entire test ledger (live data and other merchants' data are untouched). You send no body (but Idempotency-Key is still required). This endpoint has no rate limit (it only clears your own data).
reset permanently deletes all of your test data. There is no undo — it is for tearing down your own sandbox state.Response (200, ResetResult)
{
"status": "reset"
}
Test data older than ~30 days is purged automatically by the system (a daily worker) anyway —
reset is for clearing it yourself right away.Example request
cURL
curl -X POST https://api.unkpay.co/v1/test/reset \
-H "X-Api-Key: unk_test_xxxxxxxxxxxxxxxx" \
-H "X-Timestamp: 1718790000" \
-H "X-Signature: <hex hmac>" \
-H "Idempotency-Key: reset-0001"
Errors
| Situation | HTTP | code |
|---|---|---|
| Live key | 404 | NOT_FOUND |
Missing Idempotency-Key | 400 | IDEMPOTENCY_KEY_REQUIRED |
| Missing/invalid signature, API key, or timestamp | 401 | UNAUTHORIZED |