Payment Gateway API
Integrate deposits, payouts, and real-time webhooks into your platform with our simple REST API. Fast, secure, and reliable.
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 |
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 |
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
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.
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
paid
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. |
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 |
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). |
- 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.
// 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"
}
}
}
// 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"
}
}
}
// 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
}
// 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. |
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
}'
{
"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"
}
}
{
"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"
}
}
}
{
"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.
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 |
Duplicate refCode: one payout per refCode
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. |
{
"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"
}
}
{
"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
}
{
"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."
}
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 |
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
}'
{
"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"
}
}
}
{
"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.
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 -X GET '__BASE_URL__/api/v1/client/balance' \
-H 'X-API-Key: your_api_key' \
-H 'X-API-Secret: your_api_secret'
{
"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.
Deposit Callback Events: deposit.paid, deposit.expired, deposit.failed
// 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
}
Payout Callback Events: payout.success, payout.failed, payout.cancelled
// 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
}
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.
accNameaccountNoamountbankCodecallbackUrltimestamp
- refCode (optional client reference)
- signature (this is the output)
- timeout (optional)
- apiKey / apiSecret (HTTP headers only, never in signature)
Steps
- Pick the 6 fields listed above — do NOT include refCode/signature/timeout.
- Sort field names alphabetically A-Z (case-sensitive).
- Build the string: key1=value1&key2=value2&...
- Use raw values (no URL-encoding required — server accepts both).
- Compute HMAC-SHA256 using API Secret as the key.
- Output as a lowercase hex string (64 chars).
Example (Node.js)
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
If your code produces the expected signature, your integration is ready.
// 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).
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 -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.
/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 -X GET '__BASE_URL__/api/v1/transaction/DEP1709123456ABC123' \
-H 'X-API-Key: your_api_key' \
-H 'X-API-Secret: your_api_secret'
Response
{
"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 |
/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 -X POST '__BASE_URL__/api/v1/deposit/DEP1709123456ABC123/cancel' \
-H 'X-API-Key: your_api_key' \
-H 'X-API-Secret: your_api_secret'
Response
{
"status": "success",
"message": "Deposit cancelled successfully"
}
/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 -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
{
"status": "success",
"message": "Slip uploaded. Submitted for review.",
"data": {
"txnId": "DEP1709123456ABC123",
"status": "checking",
"slipImage": "https://cdn.example.com/slips/DEP1709123456ABC123.jpg"
}
}
{
"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. |
{
"success": false,
"status": "error",
"code": "SLIP_UPLOAD_TOO_LATE",
"max_age_days": 1,
"message": "รายการนี้สร้างมาเกิน 1 วันแล้ว ไม่สามารถแนบสลิปย้อนหลังได้ หากโอนเงินแล้วแต่ยังไม่ได้รับเครดิต กรุณาติดต่อทีมงานพร้อม statement จากธนาคารผู้โอน"
}
{
"status": "error",
"code": "SLIP_REUPLOAD_TOO_SOON",
"message": "เพิ่งแนบสลิปไปเมื่อสักครู่ กรุณารออีก 42 วินาทีก่อนแนบใหม่",
"retry_after": 42
}
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.
https://white-lable.sgp1.cdn.digitaloceanspaces.com/banks-logos/{CODE}.png


















