POST
/balance
Retrieve current balance, frozen balance, and unsettled balance.
เรียกดูยอดเงินคงเหลือ ยอดที่ถูกล็อก และยอดที่ยังไม่ settle
POST
https://<your-api-domain>/balance
Returns the merchant's available balance along with frozen and unsettled balances. Read-only operation; no side effects.
ส่งกลับยอดเงินคงเหลือของ merchant พร้อมยอดที่ถูกล็อกและยอดที่ยังไม่ settle — เป็น read-only ไม่มี side effect
Request
Request
Body fields
Body fields
| 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 |
Code samples
ตัวอย่างโค้ด
TIME=$(date +%s)
BODY="{\"merchant_id\":\"AA12345678\",\"token\":\"YOUR_TOKEN\",\"time\":$TIME}"
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "YOUR_SECRET" | awk '{print $2}')
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 SECRET = 'YOUR_SECRET';
const body = JSON.stringify({
merchant_id: 'AA12345678',
token: 'YOUR_TOKEN',
time: Math.floor(Date.now() / 1000),
});
const sig = crypto.createHmac('sha256', SECRET).update(body).digest('hex');
const r = await fetch('https://<your-api-domain>/balance', {
method: 'POST',
headers: { 'Content-Type': 'application/json', 'X-SIGNATURE': sig },
body
});
const data = await r.json();
console.log(data);
<?php
$secret = 'YOUR_SECRET';
$body = json_encode(
['merchant_id' => 'AA12345678', 'token' => 'YOUR_TOKEN', 'time' => time()],
JSON_UNESCAPED_UNICODE | JSON_UNESCAPED_SLASHES
);
$sig = hash_hmac('sha256', $body, $secret);
$ch = curl_init('https://<your-api-domain>/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);
Response
Response
Success — HTTP 200
สำเร็จ — HTTP 200
JSON
{
"code": 200,
"message": "Success",
"data": {
"balance": 1500.00,
"freeze_balance": 200.00,
"unsettle_balance": 50.00
},
"success": true
}
Response fields
Response fields
| Field | Type | Description | ฟิลด์ | ประเภท | คำอธิบาย |
|---|---|---|---|---|---|
| data.balance | number | Available balance (number, 2 decimal places). | data.balance | number | ยอดเงินคงเหลือที่ใช้งานได้ ทศนิยม 2 ตำแหน่ง |
| data.freeze_balance | number | Balance currently held by pending withdrawals or settlements. Released back to balance if the operation fails or times out. |
data.freeze_balance | number | ยอดที่ถูกล็อกไว้สำหรับ withdraw/settlement ที่ยังไม่จบ — ถ้าล้มเหลวหรือ timeout จะคืนกลับเข้า balance |
| data.unsettle_balance | number | Balance from successful payments not yet settled to your withdrawable pool. | data.unsettle_balance | number | ยอดจาก payment ที่สำเร็จแล้วแต่ยังไม่ settle เข้า pool ที่ถอนได้ |
Errors
Errors
This endpoint returns only authentication errors. See authentication errors for the full list.
Endpoint นี้ส่งกลับเฉพาะ error ของ authentication — ดูรายการเต็มที่ authentication errors
Notes
หมายเหตุ
- Balance values are returned as numbers with 2 decimal places. For exact arithmetic, parse them with a decimal-safe library on your side (
BigDecimalin Java,Decimalin Python) instead of native floats. - ยอดเงินส่งกลับเป็นตัวเลข (ทศนิยม 2 ตำแหน่ง) — ฝั่งคุณควร parse ด้วย library ที่จัดการ decimal ได้ (
BigDecimalใน Java,Decimalใน Python) แทน native float เพื่อให้บวก/ลบแม่นยำ - Withdrawable amount =
balance. Items infreeze_balanceandunsettle_balanceare not available for withdrawal. - ยอดที่ถอนได้ =
balance— ส่วนfreeze_balanceและunsettle_balanceถอนไม่ได้ - Polling /balance hot is fine but unnecessary. Balance updates whenever a payment, withdraw, or settlement completes.
- เรียก /balance บ่อย ๆ ทำได้แต่ไม่จำเป็น — ยอดจะเปลี่ยนเฉพาะเมื่อมี payment / withdraw / settlement สำเร็จ