การแจ้งเตือน Callback

เมื่อคำสั่ง pay-in หรือถอนเงินถึงสถานะสุดท้าย Smilepayz จะส่งการแจ้งเตือน HTTP POST ไปยังเซิร์ฟเวอร์ของคุณ คู่มือนี้อธิบายการตั้งค่า URL callback การทดสอบ sandbox การตรวจสอบลายเซ็น และวิธีตอบกลับ

ภาพรวม

Callback ช่วยให้ระบบของคุณ:

• รับการอัปเดตสถานะ pay-in และการถอนเงิน แบบอะซิงโครนัส
• ยืนยันผลคำสั่งโดยไม่ต้อง polling API inquiry
• อัปเดตสถานะคำสั่งภายในหลังตรวจสอบลายเซ็นแล้ว

เฉพาะคำสั่ง API

ระบบส่ง callback เฉพาะคำสั่งที่สร้างผ่าน API Pay-in / Pay-out เท่านั้น คำสั่งจาก Payment Link ในแบ็กเอนด์ merchant ไม่สามารถเชื่อมกับการรวมระบบของคุณได้

ข้อกำหนดเบื้องต้น

ก่อนจัดการ callback ตรวจสอบว่ามี:

• URL callback ที่เข้าถึงได้จากอินเทอร์เน็ต (http:// หรือ https:// แนะนำ HTTPS พอร์ต 443)
• Platform Public Key จาก sandbox หรือ production ใน ข้อมูลการรวมระบบ
• ตรรกะฝั่งเซิร์ฟเวอร์สำหรับตรวจสอบลายเซ็นและส่งคืน SUCCESS

ตั้งค่า URL Callback

Sandbox

1. เข้าสู่ระบบ แบ็กเอนด์ merchant
2. สลับสวิตช์ด้านบนเป็น Sandbox
3. เปิด Configuration → API Setting
4. ภายใต้ API Notify Address ตั้งค่า:
   • Payin — URL แจ้งเตือนเมื่อ pay-in เสร็จสิ้น
   • Withdraw — URL แจ้งเตือนเมื่อถอนเงินเสร็จสิ้น
5. คลิก Save

การลองใหม่และ idempotency

แบ็กเอนด์อาจลองส่ง callback ที่ล้มเหลวซ้ำ endpoint ของคุณควรตรวจสอบลายเซ็นทุกครั้ง และจัดการการแจ้งเตือนซ้ำแบบ idempotent ( tradeNo / orderNo เดียวกันไม่ควรประมวลผลซ้ำ)

สำหรับ URL production และการตั้งค่า IP whitelist ดู ข้อมูลการรวมระบบ

การทดสอบ Sandbox

ใน sandbox คุณสามารถทริกเกอร์ callback ทดสอบจากรายการคำสั่งหลังสร้างคำสั่ง API

ขั้นตอนที่ 1: สร้างคำสั่ง API ใน sandbox

สร้างคำสั่ง pay-in ผ่าน API (ดูเอกสารอ้างอิง Pay-in ของภูมิภาค) คำขอต้องมี paymentMethod ที่ไม่ว่าง (เช่น QRIS สำหรับอินโดนีเซีย)

ขั้นตอนที่ 2: จำลอง callback

1. ในแบ็กเอนด์ merchant (Sandbox) ไปที่ Pay-in Order
2. ค้นหาคำสั่งที่สร้าง
3. ในคอลัมน์ Operate คลิก Set Callback เพื่อจำลองการแจ้งเตือน สำเร็จ หรือ ล้มเหลว
4. ตรวจสอบคอลัมน์ Callback Status สำหรับผลการส่ง

ต้องระบุวิธีชำระเงิน

หาก paymentMethod ว่างเมื่อสร้างคำสั่ง sandbox Set Callback อาจทำงานไม่ถูกต้อง โปรดส่งวิธีชำระเงินที่ถูกต้องในคำขอ API

Production

เมื่อการชำระเงินหรือการจ่ายจริงเสร็จสิ้น Smilepayz จะส่ง callback อัตโนมัติ ไม่มีการกด Set Callback ด้วยตนเอง

ตรวจสอบลายเซ็น Callback

แต่ละ callback มี header ลายเซ็น ตรวจสอบด้วย Platform Public Key ก่อนอัปเดตคำสั่ง

Header คำขอ

Header	คำอธิบาย
Content-Type	application/json
X-TIMESTAMP	เวลา เช่น 2020-12-17T10:55:00+07:00
X-SIGNATURE	ลายเซ็น RSA (Base64)

สตริงที่ใช้เซ็น

Smilepayz เซ็นด้วยคีย์ส่วนตัวของแพลตฟอร์ม คุณตรวจสอบด้วยคีย์สาธารณะของแพลตฟอร์ม:

stringToSign = tradeNo + "|" + X-TIMESTAMP
X-SIGNATURE = SHA256withRSA(smilepayz_private_key, stringToSign)

ขั้นตอนการตรวจสอบ

1. อ่าน X-SIGNATURE และ X-TIMESTAMP จาก header
2. อ่าน tradeNo จาก body JSON
3. สร้าง stringToSign เป็น tradeNo + "|" + X-TIMESTAMP
4. ตรวจสอบ X-SIGNATURE ด้วย Platform Public Key โดยใช้ SHA256withRSA
5. หากถูกต้อง ประมวลผลการอัปเดตสถานะ มิฉะนั้นปฏิเสธคำขอ

ใช้ checkSha256RsaSignature จาก เอกสาร Tools / SDK หรือดู การยืนยันตัวตนด้วยลายเซ็น สำหรับรูปแบบการเซ็นแบบเต็ม

Body ของ Callback (JSON)

Body POST ของ callback เป็น JSON ฟิลด์หลักรวมถึง orderNo, tradeNo, merchantId, status, money, และ transactionTime

รูปแบบ transactionTime: yyyy-MM-ddTHH:mm:ss (เขตเวลาของภูมิภาคที่สร้างคำสั่ง)

รายการฟิลด์แบบเต็มอยู่ในเอกสารอ้างอิง Pay-in หรือ Pay-out ของภูมิภาค หัวข้อ Notification/Callback → Body Parameters

ตอบกลับ Callback

หลังตรวจสอบและประมวลผลสำเร็จ ส่งคืนสตริงข้อความธรรมดา:

SUCCESS

อย่าส่งคืน JSON หรือเนื้อหาอื่น Smilepayz จะถือว่าการส่งล้มเหลวและอาจลองใหม่

รายการตรวจสอบการใช้งาน

1. ตั้งค่า URL — กำหนดที่อยู่แจ้งเตือน pay-in และการถอนใน sandbox/production
2. รับ Platform Public Key — จาก ข้อมูลการรวมระบบ
3. ตรวจสอบทุก callback — ตรวจ X-SIGNATURE ก่อนเชื่อถือ body
4. อัปเดตสถานะคำสั่ง — แมป status กับ workflow ภายใน
5. ส่งคืน SUCCESS — หลังบันทึกการอัปเดตอย่างปลอดภัยฝั่งคุณแล้วเท่านั้น

หมายเหตุสำคัญ

• ตรวจสอบลายเซ็นเสมอ — อย่าเชื่อถือ body callback ที่ยังไม่ได้ตรวจสอบ
• ใช้คีย์สาธารณะที่ถูกต้อง — คีย์ sandbox และ production ต่างกัน
• จัดการแบบ idempotent — การลองใหม่อาจส่งการแจ้งเตือนเดิมซ้ำ
• เฉพาะคำสั่ง API — คำสั่ง payment link ในพอร์ทัล merchant ไม่ทริกเกอร์ callback การรวมระบบ

การแก้ปัญหา

ปัญหา	แนวทาง
ไม่ได้รับ callback	ยืนยันว่าบันทึก URL แจ้งเตือนแล้ว ตรวจ firewall และใบรับรอง HTTPS
ตรวจสอบลายเซ็นล้มเหลว	ใช้ Platform Public Key ของสภาพแวดล้อมเดียวกัน ตรวจลำดับ tradeNo และ X-TIMESTAMP ใน stringToSign
ไม่มี Set Callback ใน sandbox	สร้างคำสั่งผ่าน API ก่อน ต้องไม่ปล่อย paymentMethod ว่าง
callback ลองส่งซ้ำเรื่อยๆ	ส่งคืนข้อความ SUCCESS พร้อม HTTP 200 หลังประมวลผลแล้ว

การสนับสนุน

• เอกสาร: เอกสารอ้างอิง API ตามภูมิภาค และ การยืนยันตัวตนด้วยลายเซ็น
• ฝ่ายสนับสนุนทางเทคนิค: ปัญหา URL callback และลายเซ็น
• ฝ่ายบริการลูกค้า: การเข้าถึงบัญชีและสภาพแวดล้อม