Create a Deposit

POST /v1/deposits

Create a deposit so a customer can transfer money in. The response returns an expected_amount (the exact amount the customer must transfer) plus a pay_to destination / qr_payload, with status PENDING. This call must be HMAC-signed (see Authentication) and requires an Idempotency-Key header.

Idempotency-Key (mandatory when creating)

POST /v1/deposits requires the Idempotency-Key header (if omitted → 400 IDEMPOTENCY_KEY_REQUIRED). See the mechanism and replay behavior under Idempotency.

• Any unique value — the system does not enforce a format/length, only that it is non-empty. UUID v4 recommended, e.g. 9f1c2e7a-3b4d-4f8a-9c10-2b6d5e7f8a90 (or map it to your order id, as long as it is unique per record).
• The system caches the key's result for 24 hours — retrying with the same key + same body returns the same deposit (no duplicate, no double amount-slot reservation).
• The idempotency namespace is separated by mode (live/test) — the same key in live and test do not collide.

Request body

Response body

After creation the status is always PENDING.

pay_to (object):

Why expected_amount has a satang remainder

The system matches inbound money by comparing the amount arriving in the account to expected_amount exactly, so it can tell which inbound payment belongs to which deposit (many customers may transfer into the same pool account at nearly the same time).

So when a merchant requests amount = "500.00", the system adds a small satang remainder to make a value unique among other outstanding deposits, e.g. expected_amount = "500.37" (a remainder of 1–99 satang, and if truly necessary the system may nudge it up by a small whole baht). This value is the deposit's "signature amount".

"One customer, one active deposit" rule

The same customer (identified by payer_bank_provider + payer_bank_account_number) can have only one PENDING deposit at a time. Creating another while one is still outstanding returns:

{ "code": "DEPOSIT_ALREADY_ACTIVE", "message": "this customer already has an active deposit — cancel it or wait for it to expire", "details": { "deposit_id": "<existing id>" } }

Use the returned deposit_id with GET /v1/deposits/:id to re-fetch the existing payment instructions, or cancel the existing one first.

Error codes

Common errors for POST /v1/deposits. Branch on the stable code — see the full envelope under Error Envelope & Codes.

Example request

# X-Signature = hex( HMAC-SHA256( secret, "POST\n/v1/deposits\n{TS}\n{SHA256_HEX(body)}" ) )
curl -X POST 'https://api.unkpay.co/v1/deposits' \
  -H 'X-Api-Key: unk_live_xxxxxxxxxxxx' \
  -H 'X-Timestamp: 1718790000' \
  -H 'X-Signature: <hex hmac-sha256>' \
  -H 'Idempotency-Key: order-2026-0001' \
  -H 'Content-Type: application/json' \
  -d '{
    "amount": "500.00",
    "currency": "THB",
    "payment_method_type": "PROMPTPAY_QR",
    "payer_bank_provider": "KBANK",
    "payer_bank_account_name": "Somchai Jaidee",
    "payer_bank_account_number": "9876543210",
    "additional_data": { "description": "inv #42" },
    "user_ref": "ord-1"
  }'

Example response

Example response (201 Created) for PROMPTPAY_QR:

{
  "id": "8f2b1c4e-7a90-4d2f-9b3a-1c2d3e4f5a6b",
  "amount": "500.00",
  "expected_amount": "500.37",
  "currency": "THB",
  "status": "PENDING",
  "payment_method_type": "PROMPTPAY_QR",
  "pay_to": {
    "bank": "SCB",
    "account_holder": "ACME Holder",
    "qr_payload": "00020101021229370016A0000006770101110213..."
  },
  "payer": {
    "bank": "KBANK",
    "account_no": "9876543210",
    "name": "Somchai Jaidee"
  },
  "display_expires_at": "2026-06-19T10:05:00Z",
  "match_window_until": "2026-06-19T10:07:00Z"
}

Example response for BANK_TRANSFER (has account_no, no qr_payload):

{
  "id": "1a2b3c4d-...",
  "amount": "500.00",
  "expected_amount": "500.37",
  "currency": "THB",
  "status": "PENDING",
  "payment_method_type": "BANK_TRANSFER",
  "pay_to": {
    "bank": "SCB",
    "account_no": "1234567890",
    "account_holder": "ACME Holder"
  },
  "payer": {
    "bank": "KBANK",
    "account_no": "9876543210",
    "name": "Somchai Jaidee"
  },
  "display_expires_at": "2026-06-19T10:05:00Z",
  "match_window_until": "2026-06-19T10:07:00Z"
}