API v1.0

Payment Gateway API

Integrate deposits, payouts, and real-time webhooks into your platform with our simple REST API. Fast, secure, and reliable.

Base URL __BASE_URL__

🔒 Authentication

All API requests must include the following headers for authentication.

Header Value Description
X-API-Key your_api_key Your API key from the Client Management page
X-API-Secret your_api_secret Your API secret from the Client Management page
Content-Type application/json Request body format
ℹ
The Deposit/Payout create endpoints also require an X-Idempotency-Key header — see the Idempotency section.
⚠
Keep your API credentials secure. Never expose them in client-side code or public repositories.

🔁 Idempotency — Prevent Duplicate Transactions

Every Deposit/Payout create request must include the X-Idempotency-Key header to prevent duplicate transactions caused by retries or double-submits.

⚠
X-Idempotency-Key — Required header on create endpoints
  • X-Idempotency-Key: a string unique per transaction, up to 256 characters, chosen by the client — a UUID v4 generated once and stored with the transaction, or a value derived from your own transaction id. Never generate a new one for each attempt.
  • 1 transaction = 1 key; never reuse a key for a different transaction.
  • A retry must reuse the same key + identical body (every byte) → the server replays the original response without creating a duplicate.
  • Keys live for 60 minutes; after expiry the request is treated as new.
  • A replay is the response as it was first sent, not the current state of the transaction. Values that can change after create — for a deposit: status, and on channel=P2P also channel, amount, fee, feePercent, netAmount and expireDate — must be read from GET /api/v1/deposit/:txnId.

Error Responses

HTTP Code When
400 IDEMPOTENCY_KEY_REQUIRED X-Idempotency-Key header was not sent
409 IDEMPOTENCY_IN_PROGRESS The original request is still processing — wait, then retry with the same key
422 IDEMPOTENCY_BODY_MISMATCH Same key but a different body — a client bug; use a new key
ℹ
POST /api/v1/payout/create has one more 409 that is not about the key: DUPLICATE_REF_CODE. Tell the two apart by code, not by the HTTP status. See: duplicate refCode

Sending a payout request again safely

A payout moves money out of your wallet. X-Idempotency-Key is what tells us that two requests are the same withdrawal: a request with a new key is a new request. Follow these rules whenever a payout request may be sent more than once.

  • No answer — a timeout, a dropped connection, an error from something in between: send the request again with the SAME X-Idempotency-Key and the SAME body, byte for byte (the same timestamp and signature). If the first request was processed you receive its original response; if it is still being processed you receive 409 IDEMPOTENCY_IN_PROGRESS — wait, then retry with the same key. Not receiving an answer never means the payout was not created.
  • Bind the key to the withdrawal, not to the HTTP call. Create it once, when the withdrawal is created in your system, and store it with that record — or derive it from your own withdrawal id, for example WD-98765-1 — so that every retry, from any server and after any restart, sends the same key. A key generated inside the function that sends the request gives every retry a new key, and every retry becomes a new payout.
  • Before you create a new payout in place of an earlier one, confirm that the earlier one has failed: call GET /api/v1/payout/:txnId and go on only when its status is failed or cancelled (or you have received payout.failed or payout.cancelled for it). pending and processing are not failures, and neither is a callback that has not arrived yet. Only then send a new request with a new key — with a derived key, the next number: WD-98765-2.
  • If a byte-identical retry is answered 401 Invalid or expired signature — a signature is accepted once and a timestamp for 5 minutes — sign the same data again with a new timestamp and send it with the SAME X-Idempotency-Key. Until about a minute after that 401, the re-signed request may be answered 409 IDEMPOTENCY_IN_PROGRESS — wait, then send it again with the same key. Never change the key to get past an error.
  • Send a refCode with every payout — your own id for the withdrawal, the same value on every attempt. A key is remembered for 60 minutes only; the refCode check described under Payout API refuses a second payout for the same refCode whichever key it arrives with, once that check is in effect. See: duplicate refCode
⚠
Why this matters
A new key is a new request, and a new request is money leaving again. Two requests for the same withdrawal that carry two different keys are two withdrawals, and both are paid.

↓ Deposit API

Create deposit requests to receive funds from customers via QR code or bank transfer.

POST /api/v1/deposit/create Create Deposit

Request Fields

Field Type Description
accountNo Required string Customer bank account number (10-15 digits)
accName Required string Customer account name (2-100 characters)
bankCode Required string Bank code (e.g. KBANK, SCB, BBL)
amount Required number Amount in THB — integer baht only; any decimal portion is silently floored (e.g. 100.99 → 100). Range 1 - 2,000,000.
callbackUrl Required string HTTPS URL for status callbacks
refCode Optional string Client-side reference code (not included in signature, up to 100 chars)
signature Required string HMAC-SHA256 signature over the sorted query string (see Signature)
timestamp Required number Unix timestamp in milliseconds (must be within 5 minutes)

Response Fields

Field Type Description
txnId string Transaction ID (format: DEP{timestamp}{random})
status string Transaction status
pending expired cancelled failed
channel string Payment channel: QR (PromptPay), TRANSFER (bank transfer) or P2P (matched with another user). Always branch on this field — do not assume qrcode is present
amount number The EXACT amount the customer must transfer, satang included. On some accounts (e.g. GSB) the system adds satang to identify the transaction — a rounded transfer will not match. Always display this value, never requestedAmount
requestedAmount number The amount you asked for, before satang allocation. For your own reconciliation only — never show it as the amount to transfer
fee number Transaction fee (from MDR Profile, calculated on the satang-inclusive amount)
feePercent number Fee percentage
netAmount number Net amount after fee (amount - fee)
expireDate string Expiration date/time (ISO 8601, UTC)
refcode string Client reference code echoed back verbatim (empty string "" if not sent)
qrcode string PromptPay EMV payload for client-side QR rendering (only when channel=QR)
bankData object Bank account for transfer: bankName, bankCode, accountName, accountNumber (only when channel=TRANSFER)
url string The page to hand your customer. Present on every channel: on P2P it is the matching page that shows the account to transfer to, and on QR and TRANSFER it is the page where the customer attaches their transfer slip. Whether they MUST open it depends on the channel — see the table below.
ℹ
The system selects the channel automatically — if the assigned System Bank has PromptPay it returns QR; otherwise it returns TRANSFER.
⚠
channel=P2P carries NO qrcode and NO bankData — only url. A deposit on this channel is fulfilled by matching your customer with another user, so the destination account is not known at create time and cannot be returned in the response. Open (or redirect the customer to) url; that page shows the account to transfer to and takes the slip. An integration that reads qrcode unconditionally will show the customer a blank screen. Status, expireDate and callbacks behave exactly as on the other channels.
ℹ
Which deposits take this channel: an account enabled for P2P, and an amount from 100 to 950 THB that is a multiple of 50 — 100, 150, 200 … 950. Every other amount goes to a bank account as it always has, with no error and no difference in the request you send. The same range applies during bank maintenance hours, when P2P is the only rail still serving. Treat these figures as our current setting and not as a contract: we tune them, and the ceiling moved from 1,000 to 950 on 11 Sep 2026. Branch on the channel field in the response, never on the amount you sent.
⚠
The values returned for a channel=P2P deposit are not final. The same deposit may later be given a bank account: channel, amount (satang), fee, feePercent, netAmount and expireDate can all change after create, while txnId, refcode and url stay the same. See: a deposit that is switched to a bank account

P2P: paying the wrong amount

A P2P deposit is matched to a withdrawal as one whole unit, and the customer is told to transfer that exact figure. The check on settlement compares the amount on the bank slip with the amount of the match, so anything other than an exact transfer has consequences worth building for.

Customer transfers What happens Deposit credited
The exact amount Settles normally. Yes
Less than the amount The deposit is held for review by our team. It is NOT treated as a part payment and it is NOT topped up by a second transfer — the deposit is finished. The withdrawal it was matched to is released and filled by other depositors, so the withdrawing side is unaffected. No
More than the amount Settles, but only the matched amount is credited. The excess is not returned automatically. Matched amount only
⚠
Money that was under-transferred has already reached the other customer's bank account and cannot be recalled — a bank transfer between two customers is final. This is why an under-transfer is held for review instead of being closed automatically, and why your integration should make the amount impossible for the customer to mistype.
ℹ
There is no callback for "transferred the wrong amount". A deposit held for review sends no deposit.paid, and if it is still unresolved when the window closes your integration receives the ordinary EXPIRED callback — the same one a customer who never paid at all produces. If a customer insists they transferred but you received EXPIRED, contact us with the txnId rather than telling them nothing was received.
⚠
On channel=P2P the customer must transfer the EXACT amount. A transfer for less is not a partial payment — the deposit is not credited at all, it is held for review, and the money the customer already sent cannot be pulled back. Tell the customer the exact figure and do not let them edit it after the deposit is created.

P2P: a deposit that is switched to a bank account

A deposit created with channel=P2P waits to be matched with another user. If no match is found after a short wait, the system may give that same deposit a bank account to be paid into instead. Nothing is re-created: it is the same txnId, the same refcode and the same url, and your customer is not sent anywhere — the page behind url simply shows a bank account (plus its PromptPay number when it has one) and the exact amount where the matched account would have appeared. This does not happen to every P2P deposit, and you are not notified when it does: there is no callback for the switch itself. Build for it now so that it is harmless when it happens.

Field After the switch
txnId Unchanged
refcode Unchanged
url Unchanged — the same link opens the same page. The link you already handed your customer keeps working; the page now shows the bank account (plus its PromptPay number when it has one) and the exact amount to transfer.
status Still pending. The switch is not a status change.
channel Changes from P2P to QR or TRANSFER. A deposit you created as P2P that now reads QR or TRANSFER has been switched.
amount May gain satang: the same baht figure plus 0.01 to 0.99 (500 becomes 500.37, for example). It is never lower than the amount you requested and never 1 baht or more above it. On some accounts no satang is added and the amount stays as it was.
requestedAmount Unchanged — always the amount you originally requested, on every endpoint (create, get, list, status) and every channel. It equals amount when no satang are added, and is lower than amount by at most 0.99 when they are.
fee, feePercent, netAmount Recalculated at your bank-channel rate, on the new amount. They can differ from the values in the create response in either direction.
expireDate May move earlier. It is never later than the expireDate you were given at create.
bankAccountNumber, bankAccountName, bankName, bankCode, promptpayNumber Returned by GET /api/v1/deposit/:txnId. Empty while the deposit is on P2P, filled in after the switch (promptpayNumber only when channel is QR).
⚠
What your integration must do
  • Take the amount from the deposit.paid callback (or from GET /api/v1/deposit/:txnId) as the amount that was paid. Do not require it to equal the amount you requested: accept an amount that is equal to it or up to 0.99 THB above it. An integration that rejects 500.37 because it asked for 500 will refuse a deposit that was paid in full.
  • Take fee, feePercent and netAmount from GET /api/v1/deposit/:txnId at the time you reconcile, not from the create response. The callback does not carry them.
  • Send your customer to url and let that page show what to pay. Do not show an amount or an account you saved from the create response on a screen of your own — both can be out of date. If you must show the amount yourself, read it fresh from GET /api/v1/deposit/:txnId and show amount exactly, satang included.
  • Do not treat channel as fixed for the life of a deposit. Read it from GET /api/v1/deposit/:txnId when you need it; callbacks do not include it.
  • A retry with the same X-Idempotency-Key replays the create response exactly as it was first sent — channel P2P and the original amount and fee — even after the deposit has been switched. Its url is still correct. For every other value call GET /api/v1/deposit/:txnId.
  • Cancelling works as before: a switched deposit is still pending, so POST /api/v1/deposit/:txnId/cancel cancels it. After the switch a deposit ends as paid, expired, cancelled or failed.
ℹ
deposit.failed can arrive well before expireDate. Once the system stops looking for a match, the page has only a short time to be given a bank account; if none can be put on it in time, the deposit is closed with status failed and you receive deposit.failed (status FAILED, no paidAt) straight away instead of an EXPIRED callback later. The customer's page tells them not to transfer, and nothing was paid or credited. Handle it as you handle EXPIRED: close the order, and create a new deposit if the customer still wants to pay. Do not assume anything about channel or satang on a failed deposit — it may have been closed before or after it was given an account.
JSON
// GET /api/v1/deposit/DEP1709123456ABC123
{
  "status": "success",
  "message": "Get Success",
  "data": {
    "txnId": "DEP1709123456ABC123",
    "status": "pending",
    "amount": 500.00,
    "requestedAmount": 500.00,
    "fee": 7.00,
    "feePercent": 1.4,
    "netAmount": 493.00,
    "paidAmount": 0,
    "bankAccountNumber": "",
    "bankAccountName": "",
    "bankName": "",
    "bankCode": "",
    "promptpayNumber": "",
    "channel": "P2P",
    "url": "https://p2p.example.com/deposit/9xQ2m4Kd?t=...",
    "expireDate": "2024-01-01T12:15:00Z",
    "paidAt": "0001-01-01T00:00:00Z",
    "refcode": "ORDER-12345",
    "customerData": {
      "accountNo": "1234567890",
      "accName": "John Doe",
      "bankCode": "KBANK"
    }
  }
}
JSON
// GET /api/v1/deposit/DEP1709123456ABC123
{
  "status": "success",
  "message": "Get Success",
  "data": {
    "txnId": "DEP1709123456ABC123",
    "status": "pending",
    "amount": 500.37,
    "requestedAmount": 500.00,
    "fee": 7.51,
    "feePercent": 1.5,
    "netAmount": 492.86,
    "paidAmount": 0,
    "bankAccountNumber": "020123456789",
    "bankAccountName": "Company ABC",
    "bankName": "GSB",
    "bankCode": "GSB",
    "promptpayNumber": "0105568164630",
    "channel": "QR",
    "url": "https://p2p.example.com/deposit/9xQ2m4Kd?t=...",
    "expireDate": "2024-01-01T12:10:00Z",
    "paidAt": "0001-01-01T00:00:00Z",
    "refcode": "ORDER-12345",
    "customerData": {
      "accountNo": "1234567890",
      "accName": "John Doe",
      "bankCode": "KBANK"
    }
  }
}
JSON
// You requested 500.00 — the callback reports what was paid
{
  "event": "deposit.paid",
  "txnId": "DEP1709123456ABC123",
  "amount": 500.37,
  "status": "PAID",
  "paidAt": "2024-01-01T12:05:00Z",
  "refCode": "ORDER-12345",
  "signature": "callback_signature_here",
  "timestamp": 1709123456789
}
JSON
// May arrive before expireDate — nothing was paid
{
  "event": "deposit.failed",
  "txnId": "DEP1709123456ABC123",
  "amount": 500.00,
  "status": "FAILED",
  "refCode": "ORDER-12345",
  "signature": "callback_signature_here",
  "timestamp": 1709123456789
}

url: the page to hand your customer

Every deposit returns url — one field, on every channel. What it points at, and whether your customer has to open it, depends on channel.

channel Must the customer open it? Why
P2P Yes There is no qrcode and no bankData on this channel — the account to transfer to appears only on that page, so a customer who never opens it cannot pay at all.
TRANSFER Yes The customer attaches their transfer slip there. Send them the link after they transfer.
QR Optional The QR is the payment method, so the deposit completes without it. The page is there if you want the customer to attach a slip as well.
ℹ
url is a link for the CUSTOMER, not for your back office. It carries a signed, expiring token scoped to that one deposit, so it is safe to send by SMS or chat or to show after payment — but a link you file in your own admin gives you nothing. On QR and TRANSFER a slip can be attached once per deposit; to replace one, use POST /api/v1/deposit/:txnId/upload-slip (see Other Endpoints). When the feature is not enabled for your deployment the field is absent, so read it as optional.
⚠
The amount may carry satang — the customer must transfer it EXACTLY. On some destination accounts (e.g. GSB) the bank statement does not identify the payer, so the system adds satang to the amount to identify the transaction (request 1000.00, receive 1000.37). A rounded transfer will not match and the money sits unreconciled. Always display amount; requestedAmount exists only for your own reconciliation.
cURL
curl -X POST '__BASE_URL__/api/v1/deposit/create' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret' \
  -H 'X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -d '{
    "accountNo": "1234567890",
    "accName": "John Doe",
    "bankCode": "KBANK",
    "amount": 1000.00,
    "callbackUrl": "https://your-domain.com/callback",
    "refCode": "ORDER-12345",
    "signature": "abc123...",
    "timestamp": 1709123456789
  }'
JSON
{
  "status": "success",
  "message": "Create Success",
  "data": {
    "txnId": "DEP1709123456ABC123",
    "status": "pending",
    "channel": "QR",
    "amount": 1000.00,
    "fee": 15.00,
    "feePercent": 1.5,
    "netAmount": 985.00,
    "expireDate": "2024-01-01T12:10:00Z",
    "refcode": "ORDER-12345",
    "customerData": {
      "accountNo": "1234567890",
      "accName": "John Doe",
      "bankCode": "KBANK"
    },
    "qrcode": "00020101021229370016A000000677010111011300105568164630530376454041000802TH5910COMPANY CO6304ABCD"
  }
}
JSON
{
  "status": "success",
  "message": "Create Success",
  "data": {
    "txnId": "DEP1709123456ABC123",
    "status": "pending",
    "channel": "TRANSFER",
    "amount": 1000.37,
    "requestedAmount": 1000.00,
    "fee": 15.01,
    "feePercent": 1.5,
    "netAmount": 985.36,
    "expireDate": "2024-01-01T12:10:00Z",
    "refcode": "ORDER-12345",
    "customerData": {
      "accountNo": "1234567890",
      "accName": "John Doe",
      "bankCode": "KBANK"
    },
    "bankData": {
      "bankName": "GSB",
      "bankCode": "GSB",
      "accountName": "Company ABC",
      "accountNumber": "020123456789"
    }
  }
}
JSON
{
  "status": "success",
  "message": "Create Success",
  "data": {
    "txnId": "DEP1709123456ABC123",
    "status": "pending",
    "channel": "P2P",
    "amount": 500.00,
    "requestedAmount": 500.00,
    "fee": 7.00,
    "feePercent": 1.4,
    "netAmount": 493.00,
    "expireDate": "2024-01-01T12:10:00Z",
    "refcode": "ORDER-12345",
    "customerData": {
      "accountNo": "1234567890",
      "accName": "John Doe",
      "bankCode": "KBANK"
    },
    "url": "https://p2p.example.com/deposit/9xQ2m4Kd?t=..."
  }
}

↑ Payout API

Create payout requests to transfer funds to customer bank accounts.

POST /api/v1/payout/create Create Payout

Request Fields

Field Type Description
accountNo Required string Destination bank account number
accName Required string Destination account name (must match bank records)
bankCode Required string Destination bank code (e.g. KBANK, SCB, BBL)
amount Required number Amount in THB (must have sufficient balance). Range 1 - 2,000,000.
callbackUrl Required string HTTPS URL for status callbacks
refCode Optional string Your own id for this withdrawal (not included in signature, up to 100 chars). One refCode stands for one withdrawal: send the same value on every attempt at that withdrawal, and never on a different one. See: duplicate refCode
signature Required string HMAC-SHA256 signature over the sorted query string (see Signature)
timestamp Required number Unix timestamp in milliseconds (must be within 5 minutes)

Response Fields

Field Type Description
txnId string Transaction ID (format: PAY{timestamp}{random})
status string Transaction status
pending processing completed failed cancelled
amount number Payout amount
fee number Withdrawal fee (from MDR Profile)
feePercent number Fee percentage
channel string Present only when the payout is fulfilled over the P2P channel, with the value "P2P". Absent on the ordinary bank-transfer channel
refcode string Client reference code echoed back verbatim (empty string "" if not sent)
customerData object Destination account details: accountNo, accName, bankCode
url string Status page for the withdrawing customer (only when channel=P2P). Optional — the payout completes without anyone opening it; it exists because on this channel there is no bank reference to show while the transfer is being matched
ℹ
Ensure your account has sufficient balance before creating a payout. Insufficient balance will result in an error.
ℹ
A payout may be fulfilled over the P2P channel, in which case the response carries channel="P2P" and url. Nothing about your integration changes: the wallet is debited at create time exactly as on the bank channel, and payout.success / payout.failed arrive the same way. url is a status page you may pass to the withdrawing customer — it is optional.

Duplicate refCode: one payout per refCode

📅
Upcoming change — not in effect yet
The check described in this section is not enforced today: a payout create request whose refCode is already in use is still accepted, exactly as before. It takes effect when it is announced — you will be told before it is switched on, and this document sets no date. Prepare for it now: the request you send does not change, only the responses below are added.

refCode is your own id for a withdrawal. Once this check is in effect, POST /api/v1/payout/create refuses a request whose refCode is already carried by another of your payouts that has not failed. A refused request creates no payout and debits nothing from your wallet.

  • A payout releases its refCode only when its status is failed or cancelled. Every other status — pending, processing, completed, or one your integration does not recognise — keeps the refCode taken.
  • Once the earlier payout is failed or cancelled, the same refCode is accepted again — in a new request with a new X-Idempotency-Key.
  • The check looks only at your own payouts. The same value used by another account does not affect you.
  • Values are compared exactly as sent: case-sensitive, and spaces are not trimmed. WD-98765 and wd-98765 are two different refCodes.
  • A request with no refCode, or with an empty one, is not checked.
  • Only payout create is checked. Deposits are not: POST /api/v1/deposit/create accepts a repeated refCode as before.
  • A retry with the same X-Idempotency-Key and the same body is answered before this check, with the response the first request received. The idempotency rules are unchanged. See: sending a payout request again safely

Responses added by this check

HTTP Code When What to do
409 DUPLICATE_REF_CODE One of your payouts already carries this refCode and has not failed. The response names it in existing (request_id and status). Do not create a new payout. existing.request_id is the txnId of the payout that holds the refCode: call GET /api/v1/payout/:txnId and follow that payout, or wait for its callback. Send the refCode again only after that payout is failed or cancelled, and then with a new X-Idempotency-Key — this response stays stored for 60 minutes under the key that received it, even if the earlier payout fails in the meantime.
409 DUPLICATE_REF_CODE Another request with the same refCode is being processed at this moment and has no payout to name yet. The response has no existing; it carries retry_after_seconds. Do not treat it as a failure, and do not send a different refCode. Wait retry_after_seconds, then find out what the first request did: read its response, or send this request again with the same X-Idempotency-Key and a new timestamp and signature. If the first request created a payout you now receive the 409 above, with existing; if it created nothing, this request is processed normally.
503 REF_CODE_CHECK_UNAVAILABLE The check could not be completed — a temporary condition. No payout was created and nothing was debited. Send the request again: the same X-Idempotency-Key, a new timestamp and a new signature. This response is not stored under the key, so the request can be sent again as often as needed.
JSON
{
  "status": "error",
  "code": "DUPLICATE_REF_CODE",
  "message": "A payout with this refCode already exists and has not failed. Check the existing payout instead of creating a new one. A refCode can be used again only after its payout has failed, in a new request with a new X-Idempotency-Key.",
  "existing": {
    "request_id": "PAY1709123456XYZ789",
    "status": "pending"
  }
}
JSON
{
  "status": "error",
  "code": "DUPLICATE_REF_CODE",
  "message": "Another payout request with this refCode is being processed. Check its result before sending this refCode again.",
  "retry_after_seconds": 5
}
JSON
{
  "status": "error",
  "code": "REF_CODE_CHECK_UNAVAILABLE",
  "message": "Unable to verify that this refCode is not already in use. No payout was created and nothing was debited; please send the request again."
}
ℹ
Branch on code, not on the HTTP status. This endpoint has two 409 responses that carry retry_after_seconds — IDEMPOTENCY_IN_PROGRESS and DUPLICATE_REF_CODE — and it can answer 503 for other reasons, without a code; only REF_CODE_CHECK_UNAVAILABLE tells you that nothing was created or debited. existing.status is the status of that payout at the moment of the response and may be a value that is not listed in this document: treat everything other than failed or cancelled as a payout that may still be paid.

P2P: a withdrawal delivered in two parts

A P2P withdrawal is filled by matching it against deposits. If not enough deposits arrive before the deadline, the part already delivered stays delivered and a system bank transfers the remainder to the same customer. Your customer receives the full amount either way; what changes is when.

Situation What happens Callback
Filled by deposits Settles normally. payout.success
Filled in part, bank pays the rest The remainder is transferred from a system bank to the same account. The customer ends up with the full amount, usually within minutes. payout.success
Filled in part while the banks are closed The banks that carry withdrawals close overnight. Rather than hold your withdrawal until they reopen, the unpaid remainder is returned to your wallet and the withdrawal is closed. Your customer keeps what was already sent. payout.success with the amounts
Bank transfer for the remainder fails The withdrawal is held by our team until the remainder is transferred. It is not cancelled and the amount already sent is never refunded, because it cannot be recalled and your customer asked for the whole amount. None until it resolves
⚠
Silence is not failure. While a withdrawal is waiting for its remaining transfer you receive no callback at all — not payout.failed, not payout.success. Do not treat the absence of a callback as a failed withdrawal and do not return the amount to your user's balance: part of it is already in their bank account. The callback arrives when the withdrawal finishes.
⚠
When a withdrawal is closed with part of it returned, the callback carries paidAmount and refundedAmount alongside amount. amount is still what your customer ASKED for; paidAmount is what reached their bank account. Credit your user against paidAmount, not amount — an integration that ignores these two fields will credit a player the full figure while the player is holding less, and the difference is already back in your wallet.
ℹ
Conversely, payout.failed on this channel always means your customer received nothing. A withdrawal that delivered any money cannot end as failed or cancelled — the only ending available to it is completion. So payout.failed is safe to act on exactly as you do today, and payout.success means the full amount arrived, whether it came from one transfer or two.
cURL
curl -X POST '__BASE_URL__/api/v1/payout/create' \
  -H 'Content-Type: application/json' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret' \
  -H 'X-Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -d '{
    "accountNo": "9876543210",
    "accName": "Jane Doe",
    "bankCode": "SCB",
    "amount": 5000.00,
    "callbackUrl": "https://your-domain.com/callback",
    "refCode": "WD-98765",
    "signature": "def456...",
    "timestamp": 1709123456789
  }'
JSON
{
  "status": "success",
  "message": "Create Success",
  "data": {
    "txnId": "PAY1709123456XYZ789",
    "amount": 5000.00,
    "fee": 75.00,
    "feePercent": 1.5,
    "status": "pending",
    "refcode": "WD-98765",
    "customerData": {
      "accountNo": "9876543210",
      "accName": "Jane Doe",
      "bankCode": "SCB"
    }
  }
}
JSON
{
  "status": "success",
  "message": "Create Success",
  "data": {
    "txnId": "PAY1709123456XYZ789",
    "amount": 500.00,
    "fee": 1.00,
    "feePercent": 0.2,
    "status": "pending",
    "channel": "P2P",
    "refcode": "WD-98765",
    "customerData": {
      "accountNo": "9876543210",
      "accName": "Jane Doe",
      "bankCode": "SCB"
    },
    "url": "https://p2p.example.com/withdraw/7bT1n8Le?t=..."
  }
}

💰 Balance API

Check your wallet balance including available and frozen amounts.

GET /api/v1/client/balance Check Wallet Balance

Response Fields

Field Type Description
clientId string Client ID
name string Client name
balance number Total balance
available number Available balance (balance - frozen)
frozen number Frozen/locked amount
updatedAt string Last updated timestamp (Asia/Bangkok)
cURL
curl -X GET '__BASE_URL__/api/v1/client/balance' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret'
JSON
{
  "status": "success",
  "data": {
    "clientId": "65a1b2c3d4e5f6a7b8c9d0e1",
    "name": "ACME-01",
    "balance": 150000.00,
    "available": 148500.00,
    "frozen": 1500.00,
    "updatedAt": "2024-01-01T19:05:00+07:00"
  }
}

🔔 Callback / Webhook

The system sends a POST request to your callback URL whenever a transaction status changes.

ℹ
Your callback endpoint must respond with HTTP 200 within 10 seconds. Failed callbacks will be retried.
POST your_callback_url Deposit Callback

Deposit Callback Events: deposit.paid, deposit.expired, deposit.failed

JSON
// Deposit Paid
{
  "event": "deposit.paid",
  "txnId": "DEP1709123456ABC123",
  "amount": 1000.00,
  "status": "PAID",
  "paidAt": "2024-01-01T12:05:00Z",
  "refCode": "ORDER-12345",
  "signature": "callback_signature_here",
  "timestamp": 1709123456789
}

// Deposit Paid — the amount carries satang (you requested 500.00)
{
  "event": "deposit.paid",
  "txnId": "DEP1709123456ABC124",
  "amount": 500.37,
  "status": "PAID",
  "paidAt": "2024-01-01T12:05:00Z",
  "refCode": "ORDER-12346",
  "signature": "callback_signature_here",
  "timestamp": 1709123456789
}

// Deposit Expired
{
  "event": "deposit.expired",
  "txnId": "DEP1709123456ABC125",
  "amount": 1000.00,
  "status": "EXPIRED",
  "refCode": "ORDER-12347",
  "signature": "callback_signature_here",
  "timestamp": 1709123456789
}

// Deposit Failed
{
  "event": "deposit.failed",
  "txnId": "DEP1709123456ABC126",
  "amount": 500.00,
  "status": "FAILED",
  "refCode": "ORDER-12348",
  "signature": "callback_signature_here",
  "timestamp": 1709123456789
}
ℹ
A deposit callback carries exactly these fields: event, txnId, amount, status, paidAt (deposit.paid only), refCode (only when you sent one — note the capital C here, while API responses use refcode), signature and timestamp. It does not carry channel, fee or netAmount; read those from GET /api/v1/deposit/:txnId.
⚠
amount is the deposit's current amount, which is the amount your customer was told to transfer. It can carry satang and so differ from the amount you requested by up to 0.99 THB — including on a deposit that was created as a round figure on channel=P2P. Never compare it for equality with the amount you sent. See: a deposit that is switched to a bank account
POST your_callback_url Payout Callback

Payout Callback Events: payout.success, payout.failed, payout.cancelled

JSON
// Payout Success
{
  "event": "payout.success",
  "txnId": "PAY1709123456XYZ789",
  "amount": 5000.00,
  "fee": 15.00,
  "status": "SUCCESS",
  "completedAt": "2024-01-01T14:30:00Z",
  "signature": "callback_signature_here",
  "timestamp": 1709123456789
}

// Payout Failed
{
  "event": "payout.failed",
  "txnId": "PAY1709123456XYZ789",
  "amount": 5000.00,
  "fee": 15.00,
  "status": "FAILED",
  "signature": "callback_signature_here",
  "timestamp": 1709123456789
}

// Payout Cancelled
{
  "event": "payout.cancelled",
  "txnId": "PAY1709123456XYZ789",
  "amount": 5000.00,
  "fee": 15.00,
  "status": "CANCELLED",
  "signature": "callback_signature_here",
  "timestamp": 1709123456789
}
⚠
Verify Callback Signature
Always verify the callback signature by re-generating the HMAC-SHA256 hash from the callback data using your API Secret. This ensures the callback is genuinely from our system.

🔑 Signature Generation

Generate the signature with HMAC-SHA256 over a sorted query string of exactly these 6 fields.

✅
Fields included in the signature
  • accName
  • accountNo
  • amount
  • bankCode
  • callbackUrl
  • timestamp
Use exactly these 6 fields — no more, no less.
❌
Fields NOT included in the signature
  • refCode (optional client reference)
  • signature (this is the output)
  • timeout (optional)
  • apiKey / apiSecret (HTTP headers only, never in signature)

Steps

  1. Pick the 6 fields listed above — do NOT include refCode/signature/timeout.
  2. Sort field names alphabetically A-Z (case-sensitive).
  3. Build the string: key1=value1&key2=value2&...
  4. Use raw values (no URL-encoding required — server accepts both).
  5. Compute HMAC-SHA256 using API Secret as the key.
  6. Output as a lowercase hex string (64 chars).
📅
timestamp = Unix epoch milliseconds. Server accepts a ±5 min window — generate the timestamp right before signing.
💰
amount: use the same value as in the body. The server normalizes 201, 201.00, 201.0 automatically.

Example (Node.js)

JavaScript
const crypto = require('crypto');

// Allowed fields for signature — IMPORTANT: must be exactly these 6.
// Do NOT include refCode, signature, timeout, apiKey, or any other field.
const SIG_FIELDS = ['accName', 'accountNo', 'amount', 'bankCode', 'callbackUrl', 'timestamp'];

function generateSignature(data, apiSecret) {
  // 1. Pick only the allowed fields + sort alphabetically (case-sensitive)
  const sortedKeys = SIG_FIELDS.slice().sort();

  // 2. Build query string: key=value joined by '&', raw values (no URL encoding)
  const queryString = sortedKeys
    .map(key => `${key}=${data[key]}`)
    .join('&');

  // 3. HMAC-SHA256 with API Secret as key, output as lowercase hex
  return crypto
    .createHmac('sha256', apiSecret)
    .update(queryString)
    .digest('hex');
}

// Usage (Deposit example)
const data = {
  accName: 'John Doe',
  accountNo: '1234567890',
  bankCode: 'KBANK',
  amount: 1000,
  callbackUrl: 'https://your-site.com/callback',
  refCode: 'ORDER-123',           // stays in body but NOT in signature
  timestamp: Date.now(),          // Unix epoch ms, generate right before signing
};

data.signature = generateSignature(data, 'your_api_secret');
// data is now ready to POST as JSON
🧪
Verifiable example — test your code with these values
If your code produces the expected signature, your integration is ready.
JavaScript
// Test inputs (use these exact values in your code)
const apiSecret = 'test_secret_for_docs';
const data = {
  accName: 'John Doe',
  accountNo: '1234567890',
  amount: 1000,
  bankCode: 'KBANK',
  callbackUrl: 'https://your-site.com/callback',
  timestamp: 1709123456789,
};

// Step 2 output (sorted query string):
//   accName=John Doe&accountNo=1234567890&amount=1000&bankCode=KBANK&callbackUrl=https://your-site.com/callback×tamp=1709123456789

// Expected HMAC-SHA256 output (lowercase hex):
//   7fcd73b8eb6a5e2f5250ab0011caa230171b11ca6af65b0954567f3dc9e78e25

const sig = generateSignature(data, apiSecret);
console.log(sig);
// if your code prints the same value the server computes, your integration is ready.

🏦 Banks API

Retrieve the list of supported banks with pagination and search (uses API Key like Deposit/Payout).

GET /api/v1/client/banks Get Banks List

Query Parameters

Field Type Description
page Optional number Page number (default: 1)
limit Optional number Items per page (default: 100)
search Optional string Search by bank name, bank code, or international code

Response Fields

Field Type Description
id string Bank ID (MongoDB ObjectId)
bank_name string Bank name
bank_code string Bank code (e.g. KBANK, SCB)
int_code string International code (e.g. 004, 014)
bank_logo string Bank logo URL
cURL
curl -X GET '__BASE_URL__/api/v1/client/banks?page=1&limit=100' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret'

📄 Other Endpoints

Additional endpoints for managing deposits and payouts.

GET /api/v1/transaction/:txnId Check transaction status (deposit or payout, by a single txnId)

Normalized status poll — resolves the txnId across both deposits and payouts and returns a lean, type-agnostic status view. Requires API Key. For full type-specific detail use /api/v1/deposit/:txnId or /api/v1/payout/:txnId.

cURL
curl -X GET '__BASE_URL__/api/v1/transaction/DEP1709123456ABC123' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret'

Response

JSON
{
  "status": "success",
  "message": "Get Success",
  "data": {
    "txnId": "DEP1709123456ABC123",
    "type": "deposit",
    "status": "pending",
    "amount": 1000.00,
    "netAmount": 985.00,
    "refcode": "ORDER-12345",
    "createdAt": "2024-01-01T12:00:00Z"
  }
}

Deposit Endpoints

Method Endpoint Description
GET /api/v1/deposit/:requestId Get deposit details by ID
GET /api/v1/deposit/status/:requestId Get deposit status (public, no auth required)
GET /api/v1/deposits List all deposits with pagination
POST /api/v1/deposit/:requestId/cancel Cancel a pending deposit
POST /api/v1/deposit/:requestId/upload-slip Attach a transfer slip to a deposit
POST /api/v1/deposit/:txnId/cancel

Cancel a pending deposit. Only deposits with pending status can be cancelled.

This is true on every channel, including a channel=P2P deposit that has since been switched to a bank account — it is still pending until it is paid, expires or fails. No callback is sent for a cancel. Once a deposit is no longer pending the call returns HTTP 404 with the message "Deposit not found or not in pending status".

cURL
curl -X POST '__BASE_URL__/api/v1/deposit/DEP1709123456ABC123/cancel' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret'

Response

JSON
{
  "status": "success",
  "message": "Deposit cancelled successfully"
}
POST /api/v1/deposit/:txnId/upload-slip Upload a deposit slip

Attaches your customer's transfer slip to one of your deposits, so a transfer that was not matched automatically can be checked. It uses the same X-API-Key and X-API-Secret as POST /api/v1/deposit/create. The checks are the same as for a slip attached by our team.

cURL
curl -X POST '__BASE_URL__/api/v1/deposit/DEP1709123456ABC123/upload-slip' \
  -H 'X-API-Key: your_api_key' \
  -H 'X-API-Secret: your_api_secret' \
  -F 'slip_image=@slip.jpg'

Request

  • Path — txnId: the deposit's txnId, as returned by POST /api/v1/deposit/create. It must be a deposit of the client the API key belongs to.
  • Body — multipart/form-data with one file in the field slip_image: the slip image, at most 5 MB.

Which deposits accept a slip

  • The deposit belongs to the client of the API key.
  • It is not paid or refunded. A deposit in status paid, refunded or refund_pending_review is answered 404.
  • It is not on channel=P2P. A P2P slip is attached on the deposit's url page only; uploading it here would not move the deposit forward, so it is refused with 409 SLIP_NOT_ACCEPTED_ON_P2P.
  • It was created at most 1 day (24 hours) ago. An older deposit does not accept a slip and is answered 409 SLIP_UPLOAD_TOO_LATE. The limit can be changed by the provider; the value in force is max_age_days in that response.
  • A new slip may replace the previous one (for example a wrong image), at least 60 seconds after the last upload. Sending the identical file again is answered 200 with data.duplicate: true and changes nothing.

Status after the upload

  • pending stays pending. The deposit is still matched against incoming transfers as usual; if no transfer matches, the slip is checked.
  • expired, failed or checking becomes checking, and the slip is checked right away.
  • The upload is not the result. The outcome arrives as a callback (deposit.paid or another event) and through GET /api/v1/deposit/:txnId.

Response

JSON — 200
{
  "status": "success",
  "message": "Slip uploaded. Submitted for review.",
  "data": {
    "txnId": "DEP1709123456ABC123",
    "status": "checking",
    "slipImage": "https://cdn.example.com/slips/DEP1709123456ABC123.jpg"
  }
}
JSON — 200 (same file again)
{
  "status": "success",
  "message": "สลิปนี้ถูกแนบไว้แล้ว ระบบกำลังตรวจสอบอยู่ ไม่ต้องแนบซ้ำ",
  "data": {
    "txnId": "DEP1709123456ABC123",
    "duplicate": true
  }
}

Errors

HTTP Code When
400 — slip_image is missing, the file is over 5 MB, or the form could not be read.
401 — The API key or secret is invalid.
403 — The request IP is not on the client's IP whitelist.
404 — No such deposit for this API key, or it is already paid or refunded. Message: "Deposit not found or already paid".
409 SLIP_NOT_ACCEPTED_ON_P2P The deposit is on channel=P2P. Send your customer to the deposit's url instead.
409 SLIP_UPLOAD_TOO_LATE The deposit is older than the limit (1 day by default). The response carries max_age_days. Do not retry.
429 SLIP_REUPLOAD_TOO_SOON A slip was uploaded less than 60 seconds ago. Wait retry_after seconds, then send again.
500 / 503 — The file could not be stored or the deposit could not be updated. Safe to send again.
JSON — 409
{
  "success": false,
  "status": "error",
  "code": "SLIP_UPLOAD_TOO_LATE",
  "max_age_days": 1,
  "message": "รายการนี้สร้างมาเกิน 1 วันแล้ว ไม่สามารถแนบสลิปย้อนหลังได้ หากโอนเงินแล้วแต่ยังไม่ได้รับเครดิต กรุณาติดต่อทีมงานพร้อม statement จากธนาคารผู้โอน"
}
JSON — 429
{
  "status": "error",
  "code": "SLIP_REUPLOAD_TOO_SOON",
  "message": "เพิ่งแนบสลิปไปเมื่อสักครู่ กรุณารออีก 42 วินาทีก่อนแนบใหม่",
  "retry_after": 42
}
ℹ
A customer who paid but missed the slip window: contact our team with the statement from the sending bank. A late transfer can still be credited from the bank statement; it only cannot be claimed with a slip.

Payout Endpoints

Method Endpoint Description
GET /api/v1/payout/:requestId Get payout details by ID
GET /api/v1/payout/status/:requestId Get payout status (public, no auth required)
GET /api/v1/payouts List all payouts with pagination

🏧 Bank Codes

Supported bank codes and their logos.

ℹ
Bank logo URL pattern
https://white-lable.sgp1.cdn.digitaloceanspaces.com/banks-logos/{CODE}.png
KBANK
KBANK004
SCB
SCB014
BBL
BBL002
KTB
KTB006
BAY
BAY025
TTB
TTB011
GSB
GSB030
CIMB
CIMB022
UOB
UOB024
TISCO
TISCO067
KKP
KKP069
CITI
CITI017
HSBC
HSBC031
ICBC
ICBC070
GHB
GHB033
IBANK
IBANK066
BAAC
BAAC034
LHB
LHB073
TCRB
TCRB071