GET - ดึงข้อมูลใบแจ้งหนี้

ดึงสถานะปัจจุบันและรายละเอียดของใบแจ้งหนี้ตาม trans_id ส่งคืนสถานะการชำระเงิน จำนวนเงิน ข้อมูลโทเค็น/เครือข่าย (หากเลือกแล้ว) และรายละเอียดธุรกรรม (หากเสร็จสมบูรณ์) ส่งคืนเฉพาะใบแจ้งหนี้ที่เป็นของร้านค้าที่เชื่อมกับ API Key เท่านั้น

Endpoint

GET https://api.payerscan.com/invoice/:trans_id

ตัวอย่าง: GET https://api.payerscan.com/invoice/TID-ABC123DEF4567890

Headers

Header	จำเป็น	คำอธิบาย
x-api-key	ใช่	API Key ของร้านค้า

Response

สำเร็จ (HTTP 200)

Response พื้นฐาน (รวมเสมอ):

{
  "status": "success",
  "data": {
    "trans_id": "TID-ABC123DEF4567890",
    "request_id": "ORDER_123456",
    "status": "waiting",
    "amount": "100",
    "name": "Top-up balance",
    "description": "Top-up the balance for username: JohnDoe",
    "created_at": 1738742400,
    "expires_at": 1738746000
  }
}

เมื่อลูกค้าเลือกโทเค็น/เครือข่ายบนหน้าชำระเงิน data จะมีฟิลด์เพิ่มเติม:

{
  "token_symbol": "USDT",
  "network_symbol": "BSC",
  "token_amount": "100.0026",
  "token_price": "1",
  "to_address": "0xc221460115e2CfCa5bF089A7e647b11cb9631efE"
}

เมื่อ status = "completed" data จะมีฟิลด์เพิ่มเติม:

{
  "transaction_hash": "0xd346b32b83b35376d42a2464598fbf565fffb39e...",
  "from_address": "0x8894e0a0c962cb723c1976a4421c95949be2d4e3",
  "fee_amount": "0.2",
  "callback_status": "success"
}

คำอธิบายฟิลด์

ฟิลด์	คำอธิบาย
trans_id	รหัสใบแจ้งหนี้ที่ไม่ซ้ำ
request_id	ID คำสั่งซื้อของคุณ (ถ้ามีตอนสร้าง)
status	waiting | processing | completed | expired
amount	จำนวนเงิน USD (string)
name	ชื่อ/หัวข้อใบแจ้งหนี้ (ถ้ามีตอนสร้าง)
description	คำอธิบายใบแจ้งหนี้ (ถ้ามีตอนสร้าง)
created_at	เวลาสร้าง (Unix timestamp, วินาที)
expires_at	เวลาหมดอายุ (Unix timestamp, วินาที)
token_symbol	โทเค็นที่เลือก (เช่น USDT, BNB) เฉพาะหลังจากลูกค้าเลือก
network_symbol	เครือข่าย (เช่น BSC, TRC20, ETH, BINANCE_PAY) เฉพาะหลังจากลูกค้าเลือก
token_amount	จำนวนคริปโตที่ต้องโอน เฉพาะหลังจากลูกค้าเลือก
token_price	อัตราแลกเปลี่ยนตอนเลือก เฉพาะหลังจากลูกค้าเลือก
to_address	ที่อยู่กระเป๋าเงินรับ เฉพาะหลังจากลูกค้าเลือก
transaction_hash	แฮชธุรกรรมบล็อกเชน เฉพาะเมื่อ status = "completed"
from_address	ที่อยู่กระเป๋าเงินผู้ส่ง เฉพาะเมื่อ status = "completed"
fee_amount	ค่าธรรมเนียมที่หัก (USD) เฉพาะเมื่อ status = "completed"
callback_status	สถานะการส่ง webhook: success | failed | null เฉพาะเมื่อ status = "completed"

ข้อผิดพลาด (4xx / 5xx)

HTTP	error_code	คำอธิบาย
400	MISSING_TRANS_ID	ไม่มี trans_id ใน URL
400	INVALID_TRANS_ID_FORMAT	รูปแบบ trans_id ไม่ถูกต้อง ต้องเป็น: TID-XXXXXXXXXXXXXXXX (16 ตัวอักษรตัวพิมพ์ใหญ่) details มี trans_id และ expected_format
401	MISSING_API_KEY	ไม่มี header x-api-key
401	INVALID_API_KEY	API key ไม่ถูกต้องหรือไม่มีอยู่
403	ACCOUNT_INACTIVE	บัญชีที่เชื่อมกับ API key นี้ถูกปิดใช้งาน
403	STORE_INACTIVE	ร้านค้าที่เชื่อมกับ API key นี้ถูกปิดใช้งาน
404	INVOICE_NOT_FOUND	ไม่พบใบแจ้งหนี้หรือไม่ได้เป็นของ API Key ของร้านค้านี้ details.trans_id มีค่าที่ส่ง
429	RATE_LIMIT_EXCEEDED	เกินขีดจำกัดคำขอ
500	INTERNAL_ERROR	ข้อผิดพลาดเซิร์ฟเวอร์

รูปแบบ body ข้อผิดพลาด:

{
  "status": "error",
  "message": "Invoice not found.",
  "error_code": "INVOICE_NOT_FOUND",
  "details": { "trans_id": "TID-ABC123DEF4567890" }
}

Rate Limit

• Burst: 20 คำขอ/วินาที (ต่อ API Key หรือ IP)
• Sustained: 200 คำขอ/นาที (ต่อ API Key หรือ IP)

กรณีใช้งาน

• Polling: เรียก GET https://api.payerscan.com/invoice/:trans_id เป็นระยะเพื่ออัปเดตสถานะ UI (เมื่อไม่ใช้ webhook เป็นแหล่งหลัก)
• การตรวจสอบยอด: ค้นหาใบแจ้งหนี้ตาม trans_id จากอีเมล ตั๋ว ฯลฯ
• หน้าแสดงสถานะ: หลังจากลูกค้าชำระเงิน แสดงข้อมูลจาก API นี้