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

FieldTypeRequiredNotes ฟิลด์ประเภทบังคับหมายเหตุ
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

FieldTypeDescription ฟิลด์ประเภทคำอธิบาย
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 (BigDecimal in Java, Decimal in Python) instead of native floats.
  • ยอดเงินส่งกลับเป็นตัวเลข (ทศนิยม 2 ตำแหน่ง) — ฝั่งคุณควร parse ด้วย library ที่จัดการ decimal ได้ (BigDecimal ใน Java, Decimal ใน Python) แทน native float เพื่อให้บวก/ลบแม่นยำ
  • Withdrawable amount = balance. Items in freeze_balance and unsettle_balance are 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 สำเร็จ