Sandbox
Simulate Transfer
Inject a simulated bank transfer into a PENDING test deposit to drive the real matcher and a deposit.success webhook
POST /v1/test/simulate-transfer
Test mode only — requires HMAC + Idempotency-Key. This simulates money arriving on the account of a deposit that is PENDING. The system injects a test bank_transaction (mode test, bank_txn_id prefixed test_) into the real code path, then lets the real matcher run asynchronously to decide the result (match → credit → fires the deposit.success webhook).
It returns 202 Accepted immediately (meaning "injected" — the match/credit happens afterward, asynchronously).
A
202 does not mean the deposit was credited. The real outcome arrives only via the terminal deposit.success webhook — never treat the 202injected response as success.Request body (SimReq)
| field | type | required | description |
|---|---|---|---|
deposit_id | string | yes | id of your own test deposit in status PENDING. |
amount | string (baht) | no | Override the amount (omit → use the exact amount the deposit expects → matches); a non-matching amount drives AMOUNT_MISMATCH. |
sender_bank | string | no | The payer's bank — must match the declared payer, otherwise the matcher decides it is a mismatch. |
sender_name | string | no | Sender name. |
sender_account | string | no | Sender account number. |
To get the deposit credited: send
sender_* matching the payer declared when the deposit was created, and leave amount empty (so the exact expected amount is used). Every payment method must pass the same payer gate.Response (202, SimResult)
{
"bank_txn_id": "test_8f1c2e9a-...",
"amount": "500.37",
"currency": "THB",
"status": "injected"
}
status is always "injected" (this is not the match result yet — the real result comes via the deposit.success webhook).
Errors
| Situation | HTTP | code |
|---|---|---|
deposit_id empty | 422 | VALIDATION (deposit_id is required) |
| deposit not found / not yours / wrong mode (incl. live key → 404) | 404 | NOT_FOUND |
deposit is not in status PENDING | 409 | DEPOSIT_NOT_PENDING |
amount override malformed / ≤ 0 | 422 | INVALID_AMOUNT |
| Missing/invalid signature, API key, or timestamp | 401 | UNAUTHORIZED |
Missing Idempotency-Key | 400 | IDEMPOTENCY_KEY_REQUIRED |
| More than 60 calls/minute per merchant | 429 | RATE_LIMITED |
Example request
cURL
curl -X POST https://api.unkpay.co/v1/test/simulate-transfer \
-H "X-Api-Key: unk_test_xxxxxxxxxxxxxxxx" \
-H "X-Timestamp: 1718790000" \
-H "X-Signature: <hex hmac>" \
-H "Idempotency-Key: sim-0001" \
-H "Content-Type: application/json" \
-d '{
"deposit_id": "11111111-1111-4111-8111-111111111111",
"sender_bank": "KBANK",
"sender_name": "Payer Name",
"sender_account": "1234567890"
}'