Async Verify — Bank

ตรวจสอบสลิปโอนเงินธนาคารไทยแบบ อะซิงโครนัส (asynchronous) แทนที่จะรอผลลัพธ์ใน HTTP Response คุณจะส่งสลิปเข้าคิวหนึ่งหรือหลายรายการ แล้วรับผลลัพธ์ผ่าน Webhook Callback (พร้อมทางเลือกแบบ Polling สำรอง)

ระบบนี้ทำงาน คู่ขนาน กับ POST /verify/bank แบบซิงโครนัส — Endpoint แบบ sync ไม่มีการเปลี่ยนแปลง ใช้แบบ async เมื่อคุณต้องการ:

• ตรวจสอบ จำนวนมาก (bulk) (ส่งได้สูงสุด 100 สลิปในครั้งเดียว)
• แยกการรับคำขอกับการตรวจด้วยคิว แต่ Async ไม่ได้ข้าม rate limit: ตอนส่งอาจได้ 429 RATE_LIMIT_EXCEEDED และงานที่รับแล้วอาจรอ capacity ของ worker
• ตรวจสอบสลิปที่ข้อมูล มาช้า (เช่น ธนาคารกรุงเทพ) โดย Job จะ retry เบื้องหลังภายในจำนวนรอบที่ระบุด้านล่าง

Base URL

https://api.easyslip.com/v2

การยืนยันตัวตน

จำเป็น ใช้ API Key ของ Branch เดียวกัน กับ Endpoint การตรวจสอบสลิปแบบซิงโครนัส ดูคู่มือการยืนยันตัวตน

Authorization: Bearer YOUR_API_KEY

Endpoints

Endpoint	Method	คำอธิบาย
/verify/bank/async	POST	ส่ง 1 สลิปเข้าคิว → 202 พร้อม jobId
/verify/bank/batch	POST	ส่ง หลาย สลิป (สูงสุด 100) → 202 พร้อม batchId + jobs
/verify/bank/jobs/:jobId	GET	ดึงสถานะ/ผลลัพธ์ของ Job (ทางสำรองหากพลาด Webhook)

แต่ละสลิปที่เข้าคิวจะสร้าง Webhook Callback 1 ครั้ง — รวมถึงแต่ละสลิปใน Batch ด้วย (1 callback ต่อ 1 สลิป ไม่ใช่ 1 ต่อ batch)

หลักการทำงาน

1. ส่งเข้าคิว ด้วย POST /verify/bank/async (หรือหลายรายการด้วย /batch) คุณจะได้ jobId กลับมาทันที (202 Accepted) — สลิปยัง ไม่ ถูกตรวจสอบ
2. เมื่อทุกธนาคารคืน not_found หรือ BBL pending จะ retry สูงสุด 4 ครั้ง เว้น 30/60/120/240 วินาที (ตรวจรวม 5 ครั้ง) เวลารอตามตารางรวม 7 นาที 30 วินาที ยังไม่รวมประมวลผล/รอคิว พบสลิปแล้วจบทันที
3. EasySlip เข้าคิวส่ง Webhook เป็น success, not_found หรือ failed เมื่อสำเร็จ data เหมือน sync เมื่อ failed จะมี data: null และ error.code/message ที่ปลอดภัย กรณี billing จะส่งล้มเหลวหลังใช้ retry ของ billing ครบแล้ว
4. หากคุณพลาด Webhook ให้เรียก GET /verify/bank/jobs/:jobId เพื่อดึงข้อมูล Job (เก็บไว้ ~7 วัน)

การระบุ Callback URL

แต่ละคำขอสามารถระบุ callbackUrl ได้ หากไม่ระบุ จะใช้ Default Webhook URL ที่ตั้งค่าไว้ของ Branch

กฎ	พฤติกรรม
ระบุ callbackUrl	Webhook ผลลัพธ์จะถูก POST ไปที่นั่น (แทนที่ default ของ branch)
ไม่ระบุ callbackUrl	ใช้ Default Webhook URL ที่ตั้งค่าไว้ของ Branch
ไม่ได้ตั้งทั้งคู่	400 VALIDATION_ERROR
ไม่ใช่ https	400 INVALID_CALLBACK_URL
ชี้ไปยัง address ภายใน/private	400 INVALID_CALLBACK_URL

HTTPS เท่านั้น

callbackUrl ต้อง เป็น URL แบบ https:// สาธารณะ URL ที่ไม่ใช่ HTTPS และ URL ที่ชี้ไปยัง private/internal IP range จะถูกปฏิเสธเพื่อความปลอดภัย

Default Webhook URL และ Secret สำหรับเซ็นลายเซ็นตั้งค่าได้ในการตั้งค่า Webhook ของ Branch ดูวิธีตรวจสอบลายเซ็นที่หน้า Webhook Callback

Quota และรายการซ้ำ

การตรวจสอบแบบ async คิดค่าใช้จ่ายเหมือนแบบ sync:

• Quota — เฉพาะการตรวจสอบที่ สำเร็จ เท่านั้นที่หัก quota รายการที่ล้มเหลวหรือซ้ำจะไม่หัก
• รายการซ้ำ — ส่ง checkDuplicate: true เพื่อรับ isDuplicate ของสลิปที่ Branch เดิม เคยตรวจผ่าน sync หรือ async ค่าเริ่มต้นเป็น false ซึ่งไม่ส่งฟิลด์นี้กลับ รายการซ้ำใน Branch เดิมไม่หัก quota ซ้ำ

รหัส Error

รหัส	HTTP Status	คำอธิบาย
VALIDATION_ERROR	400	Body ไม่ถูกต้อง, สลิปว่าง, Batch เกิน 100 สลิป หรือไม่มี callbackUrl และไม่มี default ของ branch
INVALID_CALLBACK_URL	400	callbackUrl ไม่ใช่ https หรือชี้ไปยัง address ภายใน/private
JOB_NOT_FOUND	404	ไม่พบ Job / Job หมดอายุ หรือ Job ไม่ได้เป็นของ Branch คุณ

ข้อผิดพลาดการยืนยันตัวตนมาตรฐาน (MISSING_API_KEY, INVALID_API_KEY, SERVICE_EXPIRED, QUOTA_EXCEEDED ฯลฯ) มีผลด้วยเช่นกัน ดูอ้างอิงรหัส Error