Withdraw funds from your own merchant balance to your company's bank account in THB. This is the periodic settlement of profits/revenue accumulated from successful payments. Uses a fixed per-transaction fee and may be subject to time-window restrictions (e.g. business hours).
ถอนเงินจาก merchant balance ของคุณ เข้า บัญชีของบริษัทคุณเอง (THB) — ใช้สำหรับดึงรายได้/กำไรที่สะสมจาก payment สำเร็จเป็นรอบๆ — ค่าธรรมเนียมคงที่ต่อรายการ และอาจมีข้อจำกัดเรื่องเวลา (เช่น เฉพาะเวลาทำการ)
Use /thb-settlement/create to move funds from your
merchant balance into your own company's bank account — the periodic
settlement of revenue you've accumulated. To pay out to your end customer's
bank account (e.g. a player cashing out), use
/withdraw/create instead.
The two endpoints are billed differently: settlement uses a flat fee per transaction;
withdraw typically uses a percentage fee.
ใช้ /thb-settlement/create เพื่อย้ายเงินจาก
merchant balance เข้า บัญชีของบริษัทตัวเอง — เป็นการ settle รายได้
ที่สะสมไว้เป็นรอบๆ. ถ้าจะจ่ายเงินไปที่บัญชีของ ลูกค้าปลายทาง
(เช่น ลูกค้าถอนเงิน) ให้ใช้
/withdraw/create แทน —
ค่าธรรมเนียมต่างกัน: settlement เป็น flat fee ต่อรายการ, withdraw มักเป็น %
Request
Request
Body fields
Body fields
Identical schema to /withdraw/create:
Schema เดียวกับ /withdraw/create:
| Field | Type | Required | Notes | ฟิลด์ | ประเภท | บังคับ | หมายเหตุ |
|---|---|---|---|---|---|---|---|
| merchant_id | string | Yes | Your merchant identifier. | merchant_id | string | Yes | รหัส merchant |
| token | string | Yes | Your API token. | token | string | Yes | API token |
| time | number | string | Yes | Unix epoch (seconds). See Authentication. | time | number | string | Yes | Unix epoch (วินาที) — ดู Authentication |
| merchant_order_id | string | Yes | Unique per merchant. Alphanumeric, max 40 chars. Atomic deduplication for 7 days. | merchant_order_id | string | Yes | ห้ามซ้ำต่อ merchant — ตัวอักษร/ตัวเลข ไม่เกิน 40 ตัว — ระบบกัน duplicate แบบ atomic 7 วัน |
| amount | number | string | Yes | Settlement amount (THB). Min/max configured for your account (typical 100 – 500,000). | amount | number | string | Yes | จำนวนเงิน (THB) — ขั้นต่ำ/สูงสุดที่ตั้งไว้สำหรับบัญชีคุณ (ปกติ 100 – 500,000) |
| bank | string | Yes | Destination bank code, uppercase. See Bank codes. | bank | string | Yes | รหัสธนาคารปลายทาง ตัวพิมพ์ใหญ่ — ดูที่ Bank codes |
| account_name | string | Yes | Destination account holder name. | account_name | string | Yes | ชื่อบัญชีปลายทาง |
| account_no | string | Yes | Destination account number, 10–15 digits. | account_no | string | Yes | เลขบัญชีปลายทาง 10–15 หลัก |
| notify_url | string | Optional | HTTPS URL to receive the settlement callback. | notify_url | string | Optional | HTTPS URL รับ settlement callback |
Code samples
ตัวอย่างโค้ด
TIME=$(date +%s)
BODY="{\"merchant_id\":\"AA12345678\",\"token\":\"YOUR_TOKEN\",\"time\":$TIME,\"merchant_order_id\":\"SETTLE-2026-001\",\"amount\":\"50000.00\",\"bank\":\"KBANK\",\"account_name\":\"บริษัท เมอร์แชนต์ จำกัด\",\"account_no\":\"1234567890\",\"notify_url\":\"https://<your-merchant-webhook-URL>/settlement-callback\"}"
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "YOUR_SECRET" | awk '{print $2}')
curl -X POST https://<your-api-domain>/thb-settlement/create \
-H "Content-Type: application/json" \
-H "X-SIGNATURE: $SIG" \
-d "$BODY"
import crypto from 'node:crypto';
const SECRET = 'YOUR_SECRET';
const body = JSON.stringify({
merchant_id: 'AA12345678',
token: 'YOUR_TOKEN',
time: Math.floor(Date.now() / 1000),
merchant_order_id: 'SETTLE-2026-001',
amount: '50000.00',
bank: 'KBANK',
account_name: 'บริษัท เมอร์แชนต์ จำกัด',
account_no: '1234567890',
notify_url: 'https://<your-merchant-webhook-URL>/settlement-callback',
});
const sig = crypto.createHmac('sha256', SECRET).update(body).digest('hex');
const r = await fetch('https://<your-api-domain>/thb-settlement/create', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-SIGNATURE': sig },
body
});
console.log(await r.json());
<?php
$secret = 'YOUR_SECRET';
$body = json_encode([
'merchant_id' => 'AA12345678',
'token' => 'YOUR_TOKEN',
'time' => time(),
'merchant_order_id' => 'SETTLE-2026-001',
'amount' => '50000.00',
'bank' => 'KBANK',
'account_name' => 'บริษัท เมอร์แชนต์ จำกัด',
'account_no' => '1234567890',
'notify_url' => 'https://<your-merchant-webhook-URL>/settlement-callback',
], JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$sig = hash_hmac('sha256', $body, $secret);
$ch = curl_init('https://<your-api-domain>/thb-settlement/create');
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_POSTFIELDS => $body,
CURLOPT_HTTPHEADER => [
'Content-Type: application/json',
"X-SIGNATURE: $sig",
],
]);
echo curl_exec($ch);
Response
Response
Success — HTTP 200
สำเร็จ — HTTP 200
{
"code": 200,
"message": "Success",
"data": {
"platform_order_id": "ABCM20260509abc123XYZ456",
"merchant_order_id": "SETTLE-2026-001",
"order_datetime": "2026-05-09 03:00:00",
"amount": 50000.00,
"fee": 30.00,
"bank": "KBANK",
"account_no": "1234567890",
"account_name": "บริษัท เมอร์แชนต์ จำกัด",
"status": "open"
},
"success": true
}
Response fields
Response fields
| Field | Type | Description | ฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|---|---|---|
| data.platform_order_id | string | Settlement order ID. Format: <3-char prefix>M<YYYYMMDD><12 random alphanumeric chars> — 24 characters total. |
data.platform_order_id | string | Settlement order ID — รูปแบบ: <prefix 3 ตัวอักษร>M<YYYYMMDD><12 ตัวสุ่ม> รวม 24 ตัว |
| data.fee | number | Fixed merchant settlement fee debited along with amount. Total deducted from your balance = amount + fee. |
data.fee | number | ค่าธรรมเนียมคงที่ที่หักร่วมกับ amount — ยอดรวมที่หัก = amount + fee |
| data.status | string | Always open on creation. |
data.status | string | เป็น open เสมอตอนสร้าง |
| data.merchant_order_id | string | Same as the value you sent in the request. | data.merchant_order_id | string | ค่าเดียวกับที่คุณส่งใน request |
| data.order_datetime | string | When the settlement order was created (YYYY-MM-DD HH:mm:ss GMT+7). |
data.order_datetime | string | เวลาที่สร้าง settlement order (YYYY-MM-DD HH:mm:ss GMT+7) |
| data.amount | number | Settlement amount in THB. | data.amount | number | จำนวนเงินที่ settle (THB) |
| data.bank | string | Same as the value you sent in the request. | data.bank | string | ค่าเดียวกับที่คุณส่งใน request |
| data.account_no | string | Same as the value you sent in the request. | data.account_no | string | ค่าเดียวกับที่คุณส่งใน request |
| data.account_name | string | Same as the value you sent in the request. | data.account_name | string | ค่าเดียวกับที่คุณส่งใน request |
Errors
Errors
| HTTP | Error code | When | Error code | เกิดเมื่อ |
|---|---|---|---|---|
| 400 | invalid-inputs |
Missing/invalid fields, amount outside the configured min/max, or insufficient available balance for amount + fee. |
invalid-inputs |
Field ขาด/ผิด, amount เกินขอบเขต, หรือยอดคงเหลือไม่พอสำหรับ amount + fee |
| 409 | duplicate-entry |
Same merchant_order_id already used (atomic guard, 7 days). |
duplicate-entry |
merchant_order_id ซ้ำ (atomic ป้องกัน 7 วัน) |
| 403 | permission-denied |
Withdraw/settlement disabled, or current time is outside the configured settlement operating hours. | permission-denied |
การถอน/settlement ถูกปิด หรือเวลาปัจจุบันอยู่นอกช่วงเวลาที่อนุญาต |
| 404 | not-found |
Partner configuration not found — contact admin. | not-found |
ไม่พบ partner config — ติดต่อ admin |
Behavior & notes
พฤติกรรม & หมายเหตุ
- Atomic deduplication. Unlike regular withdraws (which use a 3-min window), settlement deduplication is atomic via Redis — the second call with the same
merchant_order_idimmediately fails withduplicate-entry. - Atomic dedup — ต่างจาก withdraw ปกติ (window 3 นาที) — settlement ใช้ atomic Redis — เรียกครั้งที่สองด้วย
merchant_order_idเดิมจะ fail ด้วยduplicate-entryทันที - Operating hours. We may restrict settlement creation to specific time windows (e.g. business hours). Outside the window you'll receive
permission-denied. - เวลาทำการ — อาจมีการจำกัดการสร้าง settlement ในช่วงเวลาที่กำหนดเท่านั้น — นอกช่วงจะได้
permission-denied - Fixed fee model. The fee is a flat THB amount per settlement, independent of
amount. Confirm the value with your payment gateway admin. - ค่าธรรมเนียมคงที่ — เป็นจำนวน THB คงที่ต่อรายการ ไม่แปรตาม
amount— ตรวจสอบค่ากับ Payment gateway admin - Callback uses the same payload schema as withdraw callback, with the
Mmode marker (4th char) inplatform_order_id. See Withdraw / Settlement Callback. - Callback ใช้ payload schema เดียวกับ withdraw โดยตัว mode (ตัวที่ 4) ของ
platform_order_idเป็นM— ดู Withdraw / Settlement Callback