1. Prerequisites — credentials you need

1. สิ่งที่ต้องเตรียม — credentials

Before you can call any endpoint you need three values issued by your payment gateway admin, plus the API base URL.

ก่อนเริ่มเรียก API คุณต้องมีค่า 3 อย่างจาก Payment gateway admin พร้อม API base URL อีก 1 ค่า

2. Base URL

2. Base URL

All endpoints in this documentation are written against the placeholder https://<your-api-domain>. Replace it with the real domain your payment gateway admin gave you.

ทุก endpoint ในเอกสารนี้ใช้ https://<your-api-domain> เป็น placeholder
คุณต้องเปลี่ยนเป็น domain จริงที่ Payment gateway admin แจ้งให้คุณตอนใช้งานจริง

POST https://<your-api-domain>/balance
POST https://<your-api-domain>/payment/create
POST https://<your-api-domain>/withdraw/create

3. Request rules

3. กติกาการเรียก API

• Method must be POST for every endpoint (except GET /health).
• ทุก endpoint ใช้ POST เท่านั้น (ยกเว้น GET /health)
• Header Content-Type: application/json is required.
• ต้องส่ง header Content-Type: application/json
• Header X-SIGNATURE must contain the HMAC-SHA256 of the raw request body using your secret.
• ต้องส่ง header X-SIGNATURE เป็น HMAC-SHA256 ของ raw request body โดยใช้ secret ของคุณ
• Body must include merchant_id, token, and time on every authenticated call.
• Body ต้องมี merchant_id, token, และ time ทุกครั้ง (ยกเว้น health)

4. Typical payment (deposit) flow

4. Flow การฝากเงิน

From order creation through customer payment to webhook delivery.

ตั้งแต่สร้างคำสั่งฝาก ลูกค้าโอนเงิน จนถึง webhook กลับ

• Create order — call /payment/create with your merchant_order_id, amount, customer bank info, and a notify_url.
• สร้างคำสั่ง — เรียก /payment/create พร้อมส่ง merchant_order_id, amount, ข้อมูลธนาคารลูกค้า และ notify_url
• Show payment instruction — display the returned QR code or transfer details to your customer. Note the transfer_amount may be slightly higher than amount for slot uniqueness.
• แสดงให้ลูกค้า — โชว์ QR หรือข้อมูลโอนเงินให้ลูกค้า
  สังเกตว่า transfer_amount อาจมากกว่า amount เล็กน้อยเพื่อแยก slot
• Wait for callback — when the customer pays, our system POSTs a callback to your notify_url. Always verify the X-Signature header.
• รอ callback — เมื่อลูกค้าโอนสำเร็จ ระบบจะ POST callback ไปที่ notify_url
  ต้องตรวจสอบ header X-Signature เสมอ
• Acknowledge — respond with HTTP 200 to confirm receipt. Anything else triggers a retry (up to 5 attempts, 60s apart).
• Acknowledge — ตอบ HTTP 200 เพื่อยืนยันว่ารับได้แล้ว
  ถ้าตอบเป็นค่าอื่นระบบจะ retry (สูงสุด 5 ครั้ง ห่างละ 60 วินาที)
• Optionally poll — if you don't receive a callback, you can call /payment/query to check status.
• Poll สถานะ (ทางเลือก) — ถ้ายังไม่ได้ callback คุณเรียก /payment/query เพื่อตรวจสอบได้

5. Typical withdrawal (payout) flow

5. Flow การถอนเงิน

This flow pays out from your merchant balance to an end customer's bank account — e.g. a player cashing out winnings. To withdraw your own merchant balance to your company's bank account instead (periodic settlement), see /thb-settlement/create.

Flow นี้คือการจ่ายเงินจาก merchant balance ไปยังบัญชีของ ลูกค้าปลายทาง เช่น ลูกค้าถอนเงิน
ถ้าต้องการถอน merchant balance ของคุณ เข้าบัญชี บริษัทตัวเอง (settle เป็นรอบ) ให้ดู /thb-settlement/create

• Create payout — call /withdraw/create with destination bank, account, amount, and notify_url. The order is created with status: 'open' and your balance is placed on a 10-minute hold.
• สร้างคำสั่งถอน — เรียก /withdraw/create พร้อมข้อมูลธนาคาร, บัญชี, จำนวนเงิน และ notify_url
  ระบบจะสร้างคำสั่งสถานะ open และ hold ยอดเงินไว้ 10 นาที
• Wait for callback — when the payout completes (or fails) we POST a callback to your notify_url. The status field will be SUCCESS or FAIL.
• รอ callback — เมื่อถอนสำเร็จหรือไม่สำเร็จ ระบบจะ POST callback ไปที่ notify_url โดย status จะเป็น SUCCESS หรือ FAIL
• Acknowledge with HTTP 200. Same retry rules as payment callback.
• ตอบ HTTP 200 — กฎการ retry เหมือน Payment callback

6. Quick test — call /balance

6. ทดสอบเร็ว ๆ — เรียก /balance

Once you have your credentials, the simplest end-to-end test is to call /balance. Replace YOUR_* placeholders with your real values, run the script, and you should see a JSON response with your balance.

พอได้ credentials ครบแล้ว วิธีทดสอบที่ง่ายสุดคือเรียก /balance
แทนค่า YOUR_* ด้วยค่าจริงของคุณ, รัน script แล้วจะได้ response JSON ที่มียอดเงิน

TIME=$(date +%s)
BODY="{\"merchant_id\":\"YOUR_MERCHANT_ID\",\"token\":\"YOUR_TOKEN\",\"time\":$TIME}"
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "YOUR_SECRET" | sed 's/^.* //')

curl -X POST https://<your-api-domain>/balance \
  -H "Content-Type: application/json" \
  -H "X-SIGNATURE: $SIG" \
  -d "$BODY"

import crypto from 'node:crypto';

const BASE   = 'https://<your-api-domain>';
const MID    = 'YOUR_MERCHANT_ID';
const TOKEN  = 'YOUR_TOKEN';
const SECRET = 'YOUR_SECRET';

const body = JSON.stringify({ merchant_id: MID, token: TOKEN });
const sig  = crypto.createHmac('sha256', SECRET).update(body).digest('hex');

const r = await fetch(`${BASE}/balance`, {
  method:  'POST',
  headers: { 'Content-Type': 'application/json', 'X-SIGNATURE': sig },
  body
});
console.log(await r.json());

<?php
$base   = 'https://<your-api-domain>';
$mid    = 'YOUR_MERCHANT_ID';
$token  = 'YOUR_TOKEN';
$secret = 'YOUR_SECRET';

$body = json_encode(['merchant_id' => $mid, 'token' => $token, 'time' => time()],
                    JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES);
$sig  = hash_hmac('sha256', $body, $secret);

$ch = curl_init("$base/balance");
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);

Expected response

Response ที่คาดหวัง

{
  "code":    200,
  "message": "Success",
  "data":    {
    "balance":          1000.00,
    "freeze_balance":   0.00,
    "unsettle_balance": 0.00
  },
  "success": true
}

If you get a 403 with signature-error, double-check that you're signing the exact bytes of your JSON body — not a re-serialized copy. See Authentication & Signature for details.

ถ้าได้ 403 พร้อม error signature-error ให้ตรวจสอบว่า HMAC ที่คำนวณคือของ raw bytes ของ JSON body ตัวเดียวกับที่ส่งจริง ๆ (ไม่ใช่ตัวที่ serialize ใหม่)
อ่านเพิ่มที่ Authentication & Signature

7. Try it in Postman

7. ลองใน Postman

Prefer a GUI over scripts? Download the ready-to-run Postman collection — it covers every endpoint and signs each request for you.

อยากลองผ่าน GUI แทนการเขียน script? ดาวน์โหลด Postman collection ที่พร้อมใช้ — ครบทุก endpoint และเซ็น request ให้อัตโนมัติ

How to use it

วิธีใช้

1. Import — in Postman, Import → drop in the downloaded .json file.
2. Import — ใน Postman กด Import แล้วลากไฟล์ .json ที่ดาวน์โหลดมาใส่
3. Set your credentials — open the collection's Variables tab and fill in baseUrl, merchant_id, token, and secret. These four are the only things you configure.
4. ตั้งค่า credentials — เปิดแท็บ Variables ของ collection แล้วกรอก baseUrl, merchant_id, token, secret
   ตั้งแค่ 4 ค่านี้พอ
5. Send — open any request (start with POST /balance) and press Send. The signature and a fresh time are generated for you on every send.
6. Send — เปิด request ไหนก็ได้ (เริ่มที่ POST /balance) แล้วกด Send
   signature และ time ใหม่ถูกสร้างให้ทุกครั้งที่ส่ง
7. Edit the body — transaction-specific values (amount, bank, account, order id, ...) live in each request's body as editable examples. Change them per call.
8. แก้ body — ค่าเฉพาะรายการ (amount, bank, บัญชี, order id ฯลฯ) อยู่ใน body ของแต่ละ request เป็นตัวอย่างที่แก้ได้
   เปลี่ยนตามที่ต้องการ