POST - สร้างใบแจ้งหนี้

สร้างใบแจ้งหนี้ชำระเงินคริปโต ผู้ค้าส่งจำนวนเงิน (USD) ข้อมูลคำสั่งซื้อ และ callback URL ระบบจะส่งคืน trans_id และ url_payment เพื่อเปลี่ยนเส้นทางลูกค้าไปยังหน้าชำระเงิน

Endpoint

POST https://api.payerscan.com/payment/crypto

Headers

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

Request Body (JSON)

ฟิลด์	ประเภท	จำเป็น	ข้อจำกัด	คำอธิบาย
merchant_id	string	ใช่	ไม่ว่าง	รหัสผู้ค้าของร้านค้า (ต้องตรงกับ API Key)
amount	number | string	ใช่	> 0 และ ≤ 1,000,000	จำนวนเงินชำระ (USD) เช่น: 100, "100"
callback_url	string	แนะนำ	สูงสุด 500 ตัวอักษร, URL ที่ถูกต้อง	URL สำหรับรับ webhook เมื่อสถานะ completed หรือ expired
completed_url	string	ไม่	สูงสุด 500 ตัวอักษร, URL ที่ถูกต้อง	URL เปลี่ยนเส้นทางหลังชำระเงินสำเร็จ
expired_url	string	ไม่	สูงสุด 500 ตัวอักษร, URL ที่ถูกต้อง	URL เปลี่ยนเส้นทางเมื่อใบแจ้งหนี้หมดอายุ
name	string	ไม่	สูงสุด 255 ตัวอักษร	ชื่อ/หัวข้อใบแจ้งหนี้
description	string	ไม่	สูงสุด 1000 ตัวอักษร	คำอธิบายใบแจ้งหนี้
request_id	string	ไม่	สูงสุด 255 ตัวอักษร	ID คำสั่งซื้อของผู้ค้าสำหรับการอ้างอิง (ส่งคืนใน response และ webhook) ใช้สำหรับ idempotency ด้วย — ดูหมายเหตุด้านล่าง

ตัวอย่าง Request

{
  "merchant_id": "MID-XXXXXXXXXX",
  "amount": 100,
  "name": "Top-up balance",
  "description": "Top-up the balance for username: [USERNAME]",
  "callback_url": "https://your-server.com/webhook/payment",
  "completed_url": "https://your-website.com/thank-you",
  "expired_url": "https://your-website.com/",
  "request_id": "ORDER_123456"
}

Response

สำเร็จ (HTTP 200)

{
  "status": "success",
  "data": {
    "request_id": "ORDER_123456",
    "trans_id": "TID-ABC123DEF4567890",
    "status": "waiting",
    "amount": "100",
    "url_payment": "https://app.payerscan.com/bill/TID-ABC123DEF4567890",
    "expires_in_minutes": 15
  }
}

ฟิลด์	คำอธิบาย
request_id	ค่าที่คุณส่งใน request
trans_id	รหัสใบแจ้งหนี้ที่ไม่ซ้ำ ใช้สำหรับค้นหาและอ้างอิง webhook
status	เป็น "waiting" เสมอเมื่อสร้างใหม่
amount	จำนวนเงิน USD (string)
url_payment	URL หน้าชำระเงิน — เปลี่ยนเส้นทางลูกค้ามาที่นี่
expires_in_minutes	เวลาหมดอายุใบแจ้งหนี้ (นาที)

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

ข้อผิดพลาดทั้งหมดมีรูปแบบนี้:

{
  "status": "error",
  "message": "คำอธิบายข้อผิดพลาด",
  "error_code": "ERROR_CODE",
  "request_id": "ORDER_123456",
  "details": { }
}

HTTP	error_code	คำอธิบาย
400	VALIDATION_ERROR	Body ไม่ถูกต้อง (ขาดฟิลด์จำเป็น, ประเภทผิด, เกินข้อจำกัด) details.errors มีรายละเอียด
400	INVALID_MERCHANT_ID	merchant_id ไม่ตรงกับ API Key ของร้านค้า
400	NO_PAYMENT_METHOD	ร้านค้ายังไม่ได้กำหนดวิธีชำระเงิน เพิ่มอย่างน้อยหนึ่งที่อยู่กระเป๋าเงินหรือกำหนดค่าแพลตฟอร์มแลกเปลี่ยนก่อนสร้างใบแจ้งหนี้
401	MISSING_API_KEY	ไม่มี header x-api-key
401	INVALID_API_KEY	API key ไม่ถูกต้องหรือไม่มีอยู่
403	ACCOUNT_INACTIVE	บัญชีที่เชื่อมกับ API key นี้ถูกปิดใช้งาน
403	STORE_INACTIVE	ร้านค้าที่เชื่อมกับ API key นี้ถูกปิดใช้งาน
402	INSUFFICIENT_BALANCE	ยอดคงเหลือร้านค้าไม่เพียงพอสำหรับค่าธรรมเนียม details มี current_balance, required_fee, shortage, fee_rate_percent, discount_percent, invoice_amount
429	RATE_LIMIT_EXCEEDED	เกินขีดจำกัดคำขอ (burst หรือ sustained) มี limit_type, retry_after_seconds
500	INTERNAL_ERROR	ข้อผิดพลาดเซิร์ฟเวอร์

รายละเอียดรหัสข้อผิดพลาด: รหัสข้อผิดพลาด API

Rate Limit

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

เกินขีดจำกัด → HTTP 429, body มี error_code: "RATE_LIMIT_EXCEEDED", retry_after_seconds

หมายเหตุ

• วิธีชำระเงิน: ร้านค้าต้องกำหนดค่าอย่างน้อยหนึ่งที่อยู่กระเป๋าเงินหรือแพลตฟอร์มแลกเปลี่ยน (Binance Pay, OKX, Bybit, MEXC, Gate.io, Bitget ฯลฯ) ก่อนสร้างใบแจ้งหนี้ หากยังไม่ได้กำหนด API จะส่งคืนข้อผิดพลาด NO_PAYMENT_METHOD
• Idempotency: หากคุณส่ง request_id ที่มีอยู่แล้วสำหรับร้านค้าเดียวกัน API จะส่งคืนใบแจ้งหนี้ที่มีอยู่แทนที่จะสร้างใหม่ Response จะมี idempotent: true เพื่อระบุสิ่งนี้ ป้องกันการสร้างใบแจ้งหนี้ซ้ำเมื่อ retry
• ค่าธรรมเนียม: ค่าธรรมเนียมคำนวณจาก amount (USD) และหักจากยอดคงเหลือของร้านค้า ตรวจสอบยอดคงเหลือให้เพียงพอก่อนสร้างใบแจ้งหนี้ ในช่วงทดลองใช้ฟรี ค่าธรรมเนียมจะได้รับการยกเว้น
• Callback: ส่ง callback_url เสมอเพื่อรับ webhook completed/expired มิฉะนั้นสามารถตรวจสอบได้ผ่าน GET https://api.payerscan.com/invoice/:trans_id เท่านั้น
• request_id: แนะนำให้ส่งเพื่อจับคู่ webhook กับคำสั่งซื้อและรองรับ idempotency