ประวัติยอดเงินผ่าน API

เรียก GET /v1/pay/balance/transactions?limit=20&since_sequence=0 ด้วย Live key ที่มี wallet:read และ HMAC เดิม ไม่ส่ง body limit รับ 1–100 (ค่าเริ่มต้น 20) ส่วน since_sequence เป็นเลขจำนวนเต็มแบบข้อความตั้งแต่ 0 ถึง 9223372036854775807 ห้ามส่ง query ซ้ำ, cursor หรือ query อื่น ส่วน run_generation ที่อธิบายด้านล่างใช้ได้เฉพาะ Test key บน Sandbox hostname

แต่ละแถวเป็นการเปลี่ยนแปลงยอดของ Merchant จาก journal จริง ID ใช้รูปแบบ btxn_ และไม่เปลี่ยนภายหลัง ยอดทั้งสามอยู่ใน bucket_deltas:

Field	ความหมาย
available_minor	ยอดพร้อมใช้ที่เพิ่มหรือลด
pending_clearing_minor	ยอดรวมรอเคลียร์และถูกพักที่เพิ่มหรือลด
reserved_minor	ยอดที่กันไว้ให้รายการจ่ายที่เพิ่มหรือลด

จำนวนเงินเป็น signed decimal string หน่วยสตางค์ และ sequence เป็น decimal string ใช้เลขฐานสิบแบบ exact หรือ BigInt แทนการแปลงเป็น JavaScript Number รุ่นนี้ไม่มี scalar amount_minor, balance_after, ชนิดรายการหรือข้อมูลเชื่อมโยงที่ยังไม่พิสูจน์ ใบเงินต้น ใบค่าธรรมเนียมและใบปรับกลับยังเป็นคนละแถว

อ่านต่อและกระทบยอด

ผลสำเร็จระบุ contract: merchant_balance_history_v1, schema_version: 1, livemode: true, currency: THB, data, has_more, next_sequence, checkpoint และ as_of แถวแต่ละใบมีเพียง id, object: balance_transaction, sequence, currency, created_at และ bucket_deltas

เก็บ ID ที่ประมวลผลแล้วเพื่อไม่บวกซ้ำ จากนั้นส่ง next_sequence กลับเป็น since_sequence จน has_more เป็น false หน้าเปล่าคง sequence ที่ส่งมา หน้าเสร็จสิ้นจะถึง checkpoint.sequence ซึ่งเป็นยอดรวมของทั้งสามช่อง ณ snapshot ที่ตรวจแล้ว sequence เป็นลำดับเผยแพร่ประวัติ ส่วน created_at เป็นเวลาลงบัญชีจริง จึงไม่รับประกันว่าทั้งสองจะเรียงเหมือนกัน ประวัติก่อนติดตั้งสร้างจาก journal ที่มีจริง แต่ไม่อ้างว่ากู้ลำดับ commit เดิมได้

ถ้าข้อมูลยังเผยแพร่ไม่ครบหรือยอดไม่ตรงบัญชี API ตอบ 503 history_not_ready พร้อม Retry-After: 1 ให้รอแล้วอ่านด้วย sequence เดิม ไม่คำนวณยอดเติมเอง เมื่อข้อมูลพร้อมแต่ cursor อยู่ข้างหน้า checkpoint จะตอบ 422 invalid_cursor429 rate_limited พร้อม Retry-After: 60 หมายถึงโควตาอ่านเต็ม การอ่านเพื่อกู้ความพร้อมอาจใช้โควตาสองครั้งเพราะตรวจ authority ใหม่หลังเผยแพร่

Sandbox

ประวัติ Sandbox มาจาก ledger จริง เริ่มอ่านด้วย since_sequence=0 ผลตอบกลับมี livemode:false, environment:sandbox, run_generation และ coverage เพิ่มจาก field กลาง ID ของแถวขึ้นต้น sbxbtxn_l_ ยอด pending clearing เป็น "0" เสมอ และค่าธรรมเนียมรวมอยู่ในยอดสุทธิของ ledger แล้ว การยกเลิก Payin ที่ไม่เปลี่ยน ledger จึงไม่มีแถวประวัติยอดเพิ่ม

เวลาอ่านต่อให้ส่งค่าทั้งคู่ เช่น ?since_sequence=3&run_generation=2 เมื่อ sequence มากกว่า 0 ต้องมี run_generation (จำนวนเต็ม 1–2147483647) เพราะแต่ละรอบเริ่มลำดับใหม่ ให้เก็บ cursor และการกัน ID ซ้ำแยกตามรอบ ถ้ารอบไม่ตรงปัจจุบันจะได้ 409 sandbox_run_changed พร้อม details.current_run_generation ให้เริ่มจาก 0 ในรอบนั้นและแทนที่มุมมองรอบปัจจุบัน รายงาน Backoffice ของรอบเก่ายังอ่านผ่าน archive เดิมได้

coverage มี state: complete|partial, retention_days:30 และ min_since_sequence เก็บประวัติ 30 วัน การเริ่มจาก 0 จะอ่านหลังขอบเขตนี้ โดยไม่สร้างรายการเปิดยอดขึ้นแทนข้อมูลที่หมดอายุ ถ้า cursor มากกว่า 0 แต่ต่ำกว่าขอบเขต จะได้ 410 sandbox_history_cursor_expired พร้อม details.run_generation และ details.min_since_sequence ให้เริ่มอ่านจาก 0 และถือประวัติ partial เป็นเฉพาะส่วนที่ยังเก็บอยู่ ห้ามรวมยอดโดยสมมติว่ายอดเปิดเป็น 0 ถ้าทุกแถวหมดอายุ หน้าอ่านจะว่างและ next_sequence เท่ากับขอบเขตและ checkpoint sequence

ถ้าประวัติไม่ครบหรือกระทบยอดไม่ตรง จะได้ 503 sandbox_balance_history_not_ready, retryable:false ถ้า cursor อยู่ข้างหน้า checkpoint ของรอบปัจจุบันที่พร้อมแล้วจะได้ 422 invalid_cursor และถ้า cursor มากกว่า 0 แต่ไม่ส่งรอบจะได้ 422 validation_error โควตา TEST เดิมตอบ 429 sandbox_rate_limited, retryable:true ส่วนระบบหรือคลังข้อมูลยืนยันตัวตนขัดข้องชั่วคราวอาจตอบ 503 service_unavailable, retryable:true ทุกผลตอบกลับ Sandbox ไม่มี Retry-After และไม่ใช้ LIVE publisher หรือข้อมูล LIVE

ยังใช้ รายงานและเครื่องมือ Sandbox ตามขอบเขตเดิมได้