API INQUIRY BALANCE

Request

API สอบถามยอดเงินคงเหลือ (Balance Inquiry) ช่วยให้ร้านค้าสามารถตรวจสอบยอดเงินคงเหลือของบัญชี Smilepayz ได้แบบเรียลไทม์ โดยจะแสดงข้อมูลยอดคงเหลือแยกตามประเภทบัญชี เช่น บัญชีรับเงิน (Pay-In) และบัญชีจ่ายเงิน (Pay-Out)

เส้นทางคำขอ (Request Path):

sandbox: https://sandbox-gateway.smilepayz.com/v2.0/inquiry-balance
production: https://gateway.smilepayz.com/v2.0/inquiry-balance

พารามิเตอร์ใน Header

Field	Required	Type	Description
Content-Type	M	String	ระบุรูปแบบข้อมูลของ HTTP ค่าคงที่: application/json จำเป็นต้องระบุเพื่อให้ระบบสามารถประมวลผลคำขอได้ถูกต้อง
X-TIMESTAMP	M	String	เวลาประทับของคำขอในรูปแบบ ISO 8601 พร้อมส่วนต่างเขตเวลา รูปแบบ: yyyy-MM-ddTHH:mm:ss±HH:mm ตัวอย่าง: 2020-12-17T10:55:00+07:00 หมายเหตุ: ต้องเป็นเวลาปัจจุบันของเซิร์ฟเวอร์ ±5 นาที
X-SIGNATURE	M	String	ลายเซ็นดิจิทัลสำหรับยืนยันตัวตนของคำขอ ดูเพิ่มเติมที่ การสร้างลายเซ็น (Signature Generation)
X-PARTNER-ID	M	String	รหัสร้านค้าที่ระบบกำหนดให้ รูปแบบ: ตัวอักษรและตัวเลข (Alphanumeric) ใช้สำหรับยืนยันตัวตนร้านค้าและการจัดเส้นทางธุรกรรม ให้ใส่ค่า merchantID

พารามิเตอร์ใน Body

Field	Required	Type	Description
accountNo	M	String(128)	หมายเลขบัญชีของร้านค้าที่ใช้สำหรับสอบถามยอดคงเหลือ รูปแบบ: ตัวอักษรและตัวเลข (Alphanumeric) ความยาวสูงสุด: 128 ตัวอักษร ใช้ระบุบัญชีที่ต้องการดึงข้อมูลยอดคงเหลือโดยเฉพาะ
balanceTypes	M	List(String)	รายการประเภทยอดคงเหลือที่ต้องการสอบถาม รูปแบบ: อาร์เรย์ของรหัสประเภทยอดคงเหลือที่ระบบกำหนดไว้ล่วงหน้า ค่าเริ่มต้น: ["BALANCE"] ตัวอย่าง: BALANCE ใช้ระบุว่าต้องการสอบถามยอดคงเหลือประเภทใดบ้าง

ข้อควรทราบที่สำคัญ

1. สภาพแวดล้อม Sandbox: accountNo ใน Sandbox จะเป็นสตริงที่ระบบสุ่มสร้างขึ้นเพื่อให้ใช้งานสำหรับการทดสอบ
2. สภาพแวดล้อม Production: ค่า accountNo สามารถดึงได้จากระบบหลังบ้านของร้านค้า
ดูเพิ่มเติมที่ วิธีขอหมายเลขบัญชี Production
3. บัญชีรับเงิน (Pay-In Account): ใช้สำหรับรับเงินจากธุรกรรมรับชำระทั้งหมด
4. บัญชีจ่ายเงิน (Pay-Out Account): ใช้สำหรับทำธุรกรรมโอน/จ่ายออกและการถอนเงิน
5. การโอนระหว่างบัญชี: สามารถโอนยอดคงเหลือระหว่างประเภทบัญชีต่าง ๆ ภายในระบบได้
ดูคู่มือการโอนเงินบัญชี

ตัวอย่าง Body – คำขอสอบถามยอดคงเหลือ (Balance Inquiry Request):

Content-type: application/json
X-TIMESTAMP: 2020-12-18T15:06:00+07:00
X-SIGNATURE: 85be817c55b2c135157c7e89f52499bf0c25ad6eeebe04a986e8c862561b19a5
X-PARTNER-ID: 20001

{
     "accountNo": "21120030202403071031",
     "balanceTypes": [
          "BALANCE"
     ]
}

Response

HTTP Response

Field	Required	Type	Description
Content-Type	M	String	ระบุรูปแบบข้อมูลของ HTTP ในการตอบกลับ ค่าคงที่: application/json แสดงว่าข้อมูลที่ตอบกลับเป็นรูปแบบ JSON
X-TIMESTAMP	M	String	เวลาประทับของการตอบกลับในรูปแบบ ISO 8601 พร้อมส่วนต่างเขตเวลา รูปแบบ: yyyy-MM-ddTHH:mm:ss±HH:mm ตัวอย่าง: 2020-12-17T10:55:00+07:00

พารามิเตอร์ใน Body

Field	Required	Type	Description
code	M	String	รหัสสถานะการทำงานของ API รูปแบบ: สตริงตัวเลขสองหลัก Success: "00", ค่ารหัสอื่นหมายถึงเกิดข้อผิดพลาด ใช้สำหรับให้ระบบนำไปประมวลผลต่อโดยอัตโนมัติ
message	M	String	ข้อความแสดงผลลัพธ์ในลักษณะที่มนุษย์อ่านเข้าใจได้ รูปแบบ: สตริง UTF-8 ให้รายละเอียดเพิ่มเติมเกี่ยวกับผลการทำงานของคำขอ อาจปรับข้อความตามภาษาของคำขอ
accountNo	O	String	หมายเลขบัญชีของร้านค้าที่ใช้ในการสอบถามยอดคงเหลือ รูปแบบ: ตัวอักษรและตัวเลข (Alphanumeric) ต้องตรงกับค่า accountNo ที่ส่งมาในคำขอ ใช้สำหรับยืนยันและระบุตัวตนบัญชี
name	O	String	ชื่อเจ้าของบัญชีหรือคำอธิบายบัญชี รูปแบบ: สตริง UTF-8 ใช้แสดงชื่อบัญชีเพื่อให้อ่านและตรวจสอบได้ง่าย
balanceTypes	O	Array	รายการประเภทยอดคงเหลือที่ร้องขอ รูปแบบ: อาร์เรย์ของรหัสประเภทยอดคงเหลือที่กำหนดไว้ล่วงหน้า ตัวอย่าง: ["BALANCE"] ใช้ระบุว่าระบบตอบข้อมูลของยอดคงเหลือประเภทใดบ้าง
accountInfos	M	Object	ข้อมูลรายละเอียดของยอดคงเหลือในบัญชีที่สอบถาม ประกอบด้วยยอดคงเหลือรวมและยอดคงเหลือที่สามารถใช้ทำธุรกรรมได้
balanceType	M	String	ประเภทของยอดคงเหลือที่รายงาน รูปแบบ: รหัสประเภทยอดคงเหลือที่กำหนดไว้ล่วงหน้า ตัวอย่าง: BALANCE ใช้ระบุหมวดหมู่ของยอดคงเหลือที่แสดง
amount	M	Object	ยอดคงเหลือรวมของบัญชีทั้งหมด ภายในประกอบด้วยข้อมูลสกุลเงินและมูลค่า ดูรายละเอียดโครงสร้างที่ Money Model
currency	M	String	รหัสสกุลเงินตามมาตรฐาน ISO 4217 ค่าคงที่: USDT (Tether USD) ใช้ระบุหน่วยของยอดคงเหลือ
value	M	String	มูลค่ายอดคงเหลือรวมในรูปแบบสตริงตัวเลข ตัวอย่าง: "250000" หมายถึง 250000 USDT ใช้แสดงค่าตัวเลขอย่างแม่นยำ
availableBalance	M	Object	ยอดคงเหลือที่สามารถใช้ทำธุรกรรมได้ในขณะนั้น ภายในประกอบด้วยข้อมูลสกุลเงินและมูลค่า อาจแตกต่างจากยอดรวมเนื่องจากยอดที่ถูกกันไว้หรือมีเงื่อนไขจำกัดการใช้
currency	M	String	รหัสสกุลเงินตามมาตรฐาน ISO 4217 ค่าคงที่: USDT (Tether USD) ใช้ระบุหน่วยของยอดคงเหลือที่สามารถใช้ได้
value	M	String	มูลค่ายอดคงเหลือที่สามารถใช้ได้ในรูปแบบสตริงตัวเลข ตัวอย่าง: "250000" หมายถึง 250000 USDT ใช้แสดงค่าตัวเลขอย่างแม่นยำ
additionalInfo	O	Object	ข้อมูลเพิ่มเติมของบัญชีและเมทาดาทาอื่น ๆ (ถ้ามี) รูปแบบ: วัตถุ JSON ใช้เก็บข้อมูลเสริมเกี่ยวกับบัญชี

Content-type: application/json 
X-TIMESTAMP: 2020-12-17T10:55:00+07:00

{
     "code": "00",
     "message": "Successful",
     "accountNo": "21120030202403071031",
     "name": "Sandbox Test",
     "balanceTypes": [
          "BALANCE"
     ],
     "accountInfos": {
          "balanceType": "BALANCE",
          "amount": {
               "currency": "USDT",
               "value": "250000"
          },
          "availableBalance": {
               "currency": "USDT",
               "value": "250000"
          }
     }
}