คำถามที่พบบ่อย
การเชื่อมต่อ & API
ต้องมีอะไรบ้างเพื่อเริ่มต้น?
คุณต้องมี API Key (จากหน้าจัดการ ในส่วน Store) และ callback URL (endpoint POST สาธารณะ) เพื่อรับ webhook จากนั้นเรียก POST https://api.payerscan.com/payment/crypto เพื่อสร้างใบแจ้งหนี้และเปลี่ยนเส้นทางลูกค้าไปที่ url_payment ดู เริ่มต้นใช้งาน
Base URL ของ API คืออะไร?
Base URL อย่างเป็นทางการของ API คือ https://api.payerscan.com คำขอ API ทั้งหมดต้องใช้ HTTPS
สร้างใบแจ้งหนี้ได้โดยไม่ส่ง callback_url ไหม?
ได้ แต่คุณจะไม่ได้รับ webhook completed/expired คุณสามารถตรวจสอบสถานะผ่าน GET https://api.payerscan.com/invoice/:trans_id (polling) เท่านั้น
ขีดจำกัดอัตราการเรียกคือเท่าไร?
- POST /payment/crypto: 5 คำขอ/วินาที, สูงสุด 60 คำขอ/นาที (ต่อ API Key, fallback เป็น IP)
- GET /invoice/:trans_id: 20 คำขอ/วินาที, สูงสุด 200 คำขอ/นาที
เกินขีดจำกัด → HTTP 429 พร้อม retry_after_seconds ใน body ดู ขีดจำกัดอัตราการเรียก
request_id คืออะไร และ idempotency ทำงานอย่างไร?
request_id เป็นฟิลด์ทางเลือกที่คุณแนบเมื่อสร้างใบแจ้งหนี้ — โดยปกติคือ ID คำสั่งซื้อภายในของคุณ (เช่น "ORDER-12345") หรือ สตริงสุ่มที่ไม่ซ้ำ ที่มีเพียง backend ของคุณและ PayerScan เท่านั้นที่รู้
ทำไมต้องใช้? ถ้าเซิร์ฟเวอร์ของคุณล่มหรือ timeout ระหว่างส่ง request คุณสามารถ retry ได้อย่างปลอดภัยด้วย request_id เดิม API รับประกันไม่สร้างใบแจ้งหนี้ซ้ำ — จะส่งคืนใบแจ้งหนี้ที่มีอยู่พร้อม "idempotent": true ใน response
จับคู่ webhook กับคำสั่งซื้อ: request_id จะถูกส่งกลับมาใน webhook callback (completed / expired) ด้วย ทำให้ backend ของคุณสามารถระบุได้ว่าการชำระเงินนั้นเป็นของใบแจ้งหนี้ (ธุรกรรม, คำสั่งซื้อ) รายการใด
ไม่ใช้ request_id: ทุกครั้งที่ POST จะสร้างใบแจ้งหนี้ใหม่ แม้ body จะเหมือนกัน คุณเสี่ยงสร้างใบแจ้งหนี้ซ้ำสำหรับคำสั่งซื้อเดียวกันถ้า retry
amount ใช้สกุลเงินอะไร?
amount เป็น USD (ดอลลาร์สหรัฐ) เสมอ ระบบจะแปลงเป็นจำนวนเงินคริปโตที่สอดคล้องกันโดยอัตโนมัติตามอัตราแลกเปลี่ยนแบบเรียลไทม์ ณ เวลาที่ชำระเงิน
หมายเหตุ: อัตราแลกเปลี่ยนมาจากหนึ่งในสี่แหล่ง — Binance, Coinbase, CoinGecko หรือ CoinMarketCap — ที่ลูกค้าเลือกบนหน้าชำระเงิน
ขีดจำกัดของ amount คือเท่าไร?
amount ของใบแจ้งหนี้ (USD) ต้องเป็นจำนวนบวกและไม่เกิน 1,000,000 สามารถส่งเป็น string หรือ number ได้
completed_url และ expired_url คืออะไร?
เป็น URL เปลี่ยนเส้นทางทางเลือกสำหรับเบราว์เซอร์ของลูกค้า:
completed_url— ลูกค้าจะถูกเปลี่ยนเส้นทางมาที่นี่หลังชำระเงินสำเร็จexpired_url— ลูกค้าจะถูกเปลี่ยนเส้นทางมาที่นี่หากใบแจ้งหนี้หมดอายุ
ใช้สำหรับการเปลี่ยนเส้นทาง frontend เท่านั้น ไม่ได้แทนที่ webhook callback_url
การชำระเงิน & การยืนยัน
เกิดอะไรขึ้นถ้าลูกค้าส่งจำนวนเงินไม่ถูกต้อง?
ระบบยืนยันเมื่อธุรกรรมบล็อกเชนตรงกันพอดีกับจำนวนเงิน (token_amount) ที่อยู่ถูกต้อง และอยู่ในกรอบเวลา การส่งน้อยเกินไปหรือมากเกินไปจะไม่ถือว่าชำระสำเร็จ ใบแจ้งหนี้อาจหมดอายุหรือลูกค้าต้องสร้างใบแจ้งหนี้ใหม่
การยืนยันใช้เวลานานเท่าไร?
โดยปกติไม่กี่วินาทีถึงไม่กี่นาที ขึ้นอยู่กับเครือข่ายและวิธีการ:
- EVM (BSC, ETH, Polygon, ...): 3-15 วินาที
- Tron (TRC20): 3-5 วินาที
- ฝากผ่านตลาด (Binance, OKX, Bybit, ...): เกือบจะทันที
- Binance Pay: เกือบจะทันที
เมื่อพบธุรกรรมที่ตรงกัน ระบบจะอัปเดตใบแจ้งหนี้และส่ง webhook ทันที
ใบแจ้งหนี้หมดอายุเมื่อไร?
ตามค่าเริ่มต้นของการตั้งค่า Store (เช่น 15 นาที) เมื่อสร้างใบแจ้งหนี้ response จะมี expires_in_minutes หลังจากเวลานั้น ใบแจ้งหนี้จะเปลี่ยนเป็น expired และ (ถ้ามี callback_url) คุณจะได้รับ webhook ที่มี status: "expired"
สถานะใบแจ้งหนี้ที่เป็นไปได้มีอะไรบ้าง?
| สถานะ | คำอธิบาย |
|---|---|
waiting | ใบแจ้งหนี้ถูกสร้างแล้ว รอลูกค้าชำระเงิน |
completed | การชำระเงินได้รับการยืนยันบนบล็อกเชน |
expired | ใบแจ้งหนี้หมดอายุโดยไม่ได้รับการชำระเงิน |
สามารถยกเลิกใบแจ้งหนี้ได้ไหม?
ไม่ได้ ใบแจ้งหนี้ไม่สามารถยกเลิกผ่าน API ได้ จะหมดอายุอัตโนมัติหลังเวลาที่กำหนด (expires_in_minutes) ถ้าลูกค้าไม่ชำระเงิน ให้ปล่อยให้หมดอายุ
Webhook
เหตุการณ์ใดที่เรียก webhook?
ระบบส่ง webhook สำหรับสองเหตุการณ์:
- completed — เมื่อการชำระเงินที่ตรงกันได้รับการยืนยันบนบล็อกเชน
- expired — เมื่อใบแจ้งหนี้หมดอายุโดยไม่ได้รับการชำระเงิน
Webhook timeout คือเท่าไร?
10 วินาที ถ้าเซิร์ฟเวอร์ร้านค้าไม่ส่ง HTTP 2xx กลับภายในเวลานี้ คำขอถือว่าล้มเหลวและจะถูก retry
ต้องส่ง body เฉพาะกลับมาไหม?
ไม่ต้อง แค่ส่ง HTTP 2xx (เช่น 200 OK) body เป็นอะไรก็ได้ (ว่างหรือ "OK")
Webhook มีการ retry เมื่อล้มเหลวไหม?
มี เมื่อคุณส่งข้อผิดพลาดหรือ timeout กลับมา ระบบ retry ตามกำหนดการ: 10s → 30s → 30s → 60s → 60s (สูงสุด 5 ครั้ง) ให้แน่ใจว่า endpoint จัดการแบบ idempotent (เรียกด้วย trans_id เดียวกันหลายครั้งปลอดภัย)
ข้อผิดพลาด & การแก้ไขปัญหา
NO_PAYMENT_METHOD หมายความว่าอะไร?
Store ของคุณยังไม่ได้กำหนดวิธีการชำระเงิน ไปที่การจัดการ Store → เพิ่มอย่างน้อยหนึ่งที่อยู่กระเป๋าเงินหรือเชื่อมต่อแพลตฟอร์มแลกเปลี่ยนก่อนสร้างใบแจ้งหนี้
INSUFFICIENT_BALANCE หมายความว่าอะไร?
ยอดเงินในบัญชีไม่เพียงพอที่จะจ่ายค่าบริการสำหรับใบแจ้งหนี้นั้น ค่าธรรมเนียมคำนวณจาก amount (USD) ของใบแจ้งหนี้ตามอัตราค่าธรรมเนียมของบัญชี (ส่วนลดอาจลดอัตรา) เติมเงินบน Dashboard แล้วลองใหม่ ตรวจสอบฟิลด์ details ใน response ข้อผิดพลาดสำหรับจำนวนเงินที่ขาดที่แน่นอน
หมายเหตุ: ในช่วงทดลองใช้ฟรี (7 วันแรก)
INSUFFICIENT_BALANCEจะไม่ปรากฏ — ค่าบริการทั้งหมดจะได้รับการยกเว้น
INVALID_MERCHANT_ID คืออะไร?
merchant_id ใน body ไม่ตรงกับ Store ของ API Key ที่ใช้อยู่ ตรวจสอบ merchant_id ในการจัดการ Store แล้วส่งค่าที่ถูกต้องในคำขอ
ค้นหาใบแจ้งหนี้ได้ 404?
สาเหตุที่เป็นไปได้: (1) trans_id ผิด (2) ใบแจ้งหนี้เป็นของ Store อื่น (API Key ต่างกัน) หรือ (3) ไม่มีอยู่ ตรวจสอบ trans_id และ API Key
วิธีการชำระเงิน
ระบบรองรับวิธีการชำระเงินอะไรบ้าง?
PayerScan รองรับหลายวิธีการชำระเงิน:
- กระเป๋าเงิน on-chain: EVM (BSC, Ethereum, Polygon, Base, Arbitrum), Tron (TRC20), Solana
- แพลตฟอร์มแลกเปลี่ยน: Binance Pay, Binance Deposit, OKX, Bybit, MEXC, Gate.io, Bitget, Upbit, Bitkub
ดู เครือข่าย & โทเค็น สำหรับรายการเต็ม
Binance Pay ทำงานอย่างไร?
Binance Pay ให้ลูกค้าชำระเงินผ่าน Binance — ไม่มีค่า gas ยืนยันทันที ร้านค้าต้องกำหนด Binance API Key และ Secret Key ในหน้าจัดการ
ต้องกำหนดอะไรบ้างสำหรับแพลตฟอร์มแลกเปลี่ยน?
- สร้าง API Key บนตลาด (เปิดสิทธิ์ที่จำเป็น)
- ในหน้าจัดการ → กำหนด API Key, Secret Key และ ID แพลตฟอร์ม สำหรับ Store
รายละเอียด: ตั้งค่า Binance Pay
ความปลอดภัย
ควรส่ง API Key จาก frontend ไหม?
ไม่ API Key ควรใช้บนเซิร์ฟเวอร์ (backend ของร้านค้า) เท่านั้น เรียก POST /payment/crypto และ GET /invoice จากเซิร์ฟเวอร์ frontend รับเฉพาะ url_payment สำหรับเปลี่ยนเส้นทาง ไม่ต้องใช้ API Key
Callback URL ต้องมีการยืนยันตัวตนไหม?
แนะนำ: ตรวจสอบ merchant_id หรือ trans_id กับข้อมูลภายในเพื่อให้แน่ใจว่าคำขอถูกต้อง ใช้ HTTPS เพื่อป้องกันการดักฟัง
สามารถมีหลาย Store ได้ไหม?
ได้ แต่ละ Store มี API Key, merchant_id, วิธีการชำระเงิน และการตั้งค่าของตัวเอง คุณสามารถสร้างหลาย Store เพื่อแยกธุรกิจหรือสภาพแวดล้อมที่แตกต่างกัน (เช่น production vs. testing)