ข้ามไปยังเนื้อหาหลัก
เวอร์ชัน: ล่าสุด

Schedules API

Schedules API ช่วยให้คุณสามารถสร้างและจัดการการชำระเงินแบบเรียกเก็บซ้ำและการโอนเงินอัตโนมัติตามกำหนดการได้

ปลายทางที่มีให้บริการ​

ภาพรวม​

Schedules ช่วยให้สามารถดำเนินการซ้ำแบบอัตโนมัติได้

  • การเรียกเก็บเงินซ้ำ - เรียกเก็บเงินจากลูกค้าโดยอัตโนมัติตามกำหนดการ
  • การโอนเงินซ้ำ - โอนเงินไปยังผู้รับโดยอัตโนมัติ
  • ความถี่ที่ยืดหยุ่น - กำหนดการรายวัน รายสัปดาห์ รายเดือน
  • การติดตามการดำเนินการ - ติดตามการดำเนินการแต่ละครั้งของกำหนดการ

กรณีการใช้งานทั่วไป​

  • การเรียกเก็บค่าสมาชิก (การเรียกเก็บรายเดือน/รายปี)
  • การจ่ายเงินตามกำหนดการให้กับผู้ขายในตลาดออนไลน์
  • การบริจาคแบบเรียกเก็บซ้ำ
  • ค่าสมาชิก
  • การจ่ายค่าคอมมิชชั่นอัตโนมัติ

กำหนดการทำงานอย่างไร​

  1. สร้างกำหนดการโดยระบุความถี่ (รายวัน รายสัปดาห์ รายเดือน)
  2. กำหนดการจะดำเนินการโดยอัตโนมัติตามช่วงเวลาที่กำหนด
  3. การดำเนินการแต่ละครั้งจะสร้าง "occurrence"
  4. Occurrences เชื่อมโยงกับการเรียกเก็บเงินหรือการโอนเงินจริงที่ถูกสร้างขึ้น
  5. ตรวจสอบสถานะของกำหนดการและผลลัพธ์ของ occurrence

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

ปลายทาง Schedule API ทั้งหมดต้องการการยืนยันตัวตนโดยใช้ secret key ของคุณ

ความถี่ของกำหนดการ​

Schedules รองรับความถี่ดังต่อไปนี้:

Frequencyคำอธิบายตัวอย่างกรณีการใช้งาน
dailyดำเนินการทุกวันในเวลาที่กำหนดการจ่ายเงินรายวัน
weeklyดำเนินการสัปดาห์ละครั้งในวันที่กำหนดการสมัครสมาชิกรายสัปดาห์
monthlyดำเนินการเดือนละครั้งในวันที่กำหนดการเรียกเก็บเงินรายเดือน

วงจรชีวิตของสถานะกำหนดการ​

กำหนดการจะดำเนินผ่านสถานะต่อไปนี้:

  1. active - กำหนดการกำลังทำงานและจะดำเนินการตามกำหนด
  2. suspended - กำหนดการถูกหยุดชั่วคราว (สามารถกลับมาใช้งานได้)
  3. deleted - กำหนดการถูกปิดการใช้งานถาวร
  4. completed - กำหนดการถึงวันที่สิ้นสุดแล้ว

Occurrences​

ทุกครั้งที่กำหนดการดำเนินการ จะสร้าง occurrence ขึ้นมา Occurrences มีสถานะของตัวเอง:

  • scheduled - occurrence อยู่ในคิวรอดำเนินการ
  • running - occurrence กำลังดำเนินการอยู่
  • successful - occurrence เสร็จสมบูรณ์เรียบร้อยแล้ว
  • failed - occurrence ล้มเหลว (การชำระเงินถูกปฏิเสธ ยอดเงินคงเหลือไม่เพียงพอ ฯลฯ)
  • skipped - occurrence ถูกข้าม (เช่น กำหนดการถูกหยุดชั่วคราว)

แนวทางปฏิบัติที่ดีที่สุด​

1. จัดการ Occurrences ที่ล้มเหลว​

การดำเนินการตามกำหนดการทั้งหมดไม่ได้ประสบความสำเร็จเสมอไป ควรใช้งาน webhook handlers สำหรับ:

  • schedule.occurrence.failed - จัดการการชำระเงิน/การโอนเงินที่ล้มเหลว
  • schedule.occurrence.successful - ติดตามการดำเนินการที่สำเร็จ

2. ตรวจสอบสุขภาพของกำหนดการ​

ตรวจสอบสถานะของกำหนดการและ occurrences ล่าสุดเป็นประจำ:

  • อัตราความล้มเหลวที่สูงอาจบ่งชี้ปัญหาการชำระเงินของลูกค้า
  • กำหนดการที่ถูกหยุดชั่วคราวจะไม่ดำเนินการจนกว่าจะถูกเปิดใช้งานใหม่

3. กำหนดวันที่สิ้นสุด​

สำหรับการสมัครสมาชิกที่มีระยะเวลาจำกัด ให้กำหนด end_date:

{
  "period": "month",
  "end_date": "2027-12-31"
}

4. ใช้ Metadata​

เก็บรายละเอียดการสมัครสมาชิกใน metadata เพื่อการค้นหาที่ง่าย:

{
  "metadata": {
    "plan": "premium",
    "customer_id": "cust_123",
    "subscription_id": "sub_456"
  }
}

ข้อจำกัด​

  • ช่วงเวลากำหนดการขั้นต่ำ: 1 วัน
  • จำนวนกำหนดการที่ใช้งานอยู่สูงสุดต่อบัญชี: โปรดติดต่อฝ่ายสนับสนุนสำหรับข้อจำกัด
  • กำหนดการไม่สามารถแก้ไขได้หลังจากสร้าง (ต้องลบและสร้างใหม่)
  • Occurrences ที่ล้มเหลวจะไม่ถูกลองใหม่โดยอัตโนมัติ

การจัดการข้อผิดพลาด​

ข้อผิดพลาดทั่วไปเมื่อทำงานกับกำหนดการ:

รหัสข้อผิดพลาดคำอธิบายวิธีแก้ไข
invalid_frequencyค่าระยะเวลาไม่ถูกต้องใช้ daily, weekly หรือ monthly
invalid_start_dateวันที่เริ่มต้นอยู่ในอดีตใช้วันที่ในอนาคต
insufficient_balanceยอดเงินคงเหลือไม่เพียงพอสำหรับการโอนเงินเพิ่มเงินทุนก่อนที่กำหนดการจะดำเนินการ
invalid_recipientไม่พบผู้รับหรือไม่ได้ใช้งานตรวจสอบว่าผู้รับมีอยู่จริง

ทรัพยากรที่เกี่ยวข้อง​