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

Refunds API

ภาพรวม​

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

การคืนเงินคืออะไร?​

การคืนเงินคือออบเจกต์ที่แสดงถึงเงินที่คืนให้ลูกค้า:

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

คุณสมบัติหลัก​

ตัวเลือกการคืนเงินที่ยืดหยุ่น​

  • เต็มจำนวนหรือบางส่วน - คืนเงินจำนวนใดก็ได้จนถึงยอดเรียกเก็บเงินเดิม
  • การคืนเงินหลายครั้ง - แบ่งการคืนเงินเป็นหลายธุรกรรม
  • รองรับ Metadata - เพิ่มข้อมูลที่กำหนดเองสำหรับการติดตาม
  • การดำเนินการทันที - การคืนเงินถูกดำเนินการทันที

การจัดการที่ง่ายดาย​

  • รายการคืนเงิน - ดูการคืนเงินทั้งหมดสำหรับการเรียกเก็บเงิน
  • ติดตามสถานะ - ตรวจสอบการดำเนินการคืนเงิน
  • ค้นหาการคืนเงิน - ค้นหาธุรกรรมการคืนเงินเฉพาะ
  • บันทึกการตรวจสอบ - ประวัติการคืนเงินทั้งหมด

การจัดการอัตโนมัติ​

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

การทำงานของการคืนเงิน​

ขั้นตอนมาตรฐาน​

┌─────────┐         ┌─────────┐         ┌─────────┐
│ เซิร์ฟ  │         │ Omise   │         │ ธนาคาร  │
│ เวอร์   │         │ API     │         │ ลูกค้า  │
└────┬────┘         └────┬────┘         └────┬────┘
     │                   │                   │
     │ 1. สร้างการคืนเงิน │                   │
     ├──────────────────>│                   │
     │                   │                   │
     │ 2. คืนการคืนเงิน  │                   │
     │<──────────────────┤                   │
     │                   │                   │
     │                   │ 3. ดำเนินการคืนเงิน│
     │                   ├──────────────────>│
     │                   │                   │
     │                   │ 4. คืนเงินแล้ว    │
     │                   │<──────────────────┤
     │                   │                   │
     │ 5. แจ้งเตือน      │                   │
     │    Webhook        │                   │
     │<──────────────────┤                   │
     │                   │                   │

ไทม์ไลน์การคืนเงิน​

  1. ทันที: การคืนเงินถูกสร้างในระบบ Omise
  2. กำลังดำเนินการ: ส่งไปยังเครือข่ายบัตร (ทันที)
  3. ลูกค้าเห็น: โดยทั่วไป 5-10 วันทำการ
  4. ส่ง Webhook: เมื่อการคืนเงินเสร็จสมบูรณ์

API Endpoints​

เมธอดEndpointคำอธิบาย
POST/charges/:id/refundsสร้างการคืนเงินสำหรับ charge
GET/refunds/:idดึงรายละเอียดการคืนเงิน
GET/charges/:id/refundsรายการการคืนเงินทั้งหมดสำหรับ charge

เริ่มต้นอย่างรวดเร็ว​

การคืนเงินเต็มจำนวน​

// คืนเงินทั้งหมดของ charge
const refund = await omise.charges.refund('chrg_test_5xuy4w91xqz7d1w9u0t');

console.log('สร้างการคืนเงินแล้ว:', refund.id);
console.log('จำนวนเงิน:', refund.amount);
console.log('สถานะ:', refund.status);

การคืนเงินบางส่วน​

// คืนเงินบางส่วนของ charge
const refund = await omise.charges.refund('chrg_test_5xuy4w91xqz7d1w9u0t', {
  amount: 50000  // คืนเงิน ฿500 จาก charge ฿1000
});

console.log('คืนเงินแล้ว:', refund.amount);
console.log('ยอดเดิม:', refund.charge.amount);

การคืนเงินบางส่วนหลายครั้ง​

// ออกการคืนเงินหลายครั้งสำหรับ charge เดียวกัน
const refund1 = await omise.charges.refund(chargeId, { amount: 30000 });
const refund2 = await omise.charges.refund(chargeId, { amount: 20000 });

// ตรวจสอบยอดรวมที่คืนเงิน
const charge = await omise.charges.retrieve(chargeId);
console.log('ยอดรวมที่คืน:', charge.refunded_amount);
console.log('คงเหลือ:', charge.amount - charge.refunded_amount);

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

การคืนสินค้า​

// ลูกค้าคืนสินค้า
const refund = await omise.charges.refund(chargeId, {
  amount: productPrice,
  metadata: {
    reason: 'product_return',
    order_id: 'ORDER-123',
    return_tracking: 'TRACK-456'
  }
});

การยกเลิกคำสั่งซื้อ​

// ยกเลิกคำสั่งซื้อ คืนเงินเต็มจำนวน
const refund = await omise.charges.refund(chargeId, {
  metadata: {
    reason: 'order_cancelled',
    cancelled_by: 'customer'
  }
});

การคืนเงินบางส่วน (สินค้าเสียหาย)​

// คืนเงินบางส่วนสำหรับสินค้าที่เสียหาย
const refund = await omise.charges.refund(chargeId, {
  amount: damageCompensation,  // เช่น 30% ของยอดเดิม
  metadata: {
    reason: 'partial_damage',
    compensation_rate: 0.3
  }
});

กฎการคืนเงิน​

ระยะเวลา​

  • สามารถคืนเงินได้: ทุกเวลาหลังจากการเรียกเก็บเงินสำเร็จ
  • ไม่สามารถคืนเงินได้: charge ที่ล้มเหลวหรืออยู่ระหว่างดำเนินการ
  • ไม่มีขีดจำกัดเวลา: ไม่มีขีดจำกัด (สามารถคืนเงินได้หลายปีต่อมา)

จำนวนเงิน​

  • ขั้นต่ำ: 1 หน่วยในสกุลเงิน (1 สตางค์สำหรับ THB)
  • สูงสุด: จำนวนเงินเรียกเก็บเงินเดิมหักการคืนเงินก่อนหน้า
  • หลายครั้ง: สามารถออกการคืนเงินบางส่วนหลายครั้ง
  • ยอดรวม: ไม่สามารถเกินจำนวนเงินเรียกเก็บเงินเดิม

คุณสมบัติที่ต้องมี​

  • Charge ที่สำเร็จ - สามารถคืนเงินได้
  • Charge ที่อยู่ระหว่างดำเนินการ - ไม่สามารถคืนเงินได้
  • Charge ที่ล้มเหลว - ไม่สามารถคืนเงินได้
  • คืนเงินบางส่วนแล้ว - สามารถคืนเงินจำนวนที่เหลือได้

ค่าธรรมเนียมธุรกรรม​

การจัดการค่าธรรมเนียม​

  • การคืนเงินเต็มจำนวน: ค่าธรรมเนียมธุรกรรมอาจถูกคืน (ขึ้นอยู่กับนโยบาย)
  • การคืนเงินบางส่วน: โดยทั่วไปค่าธรรมเนียมไม่ถูกคืน
  • ตรวจสอบนโยบาย: ติดต่อฝ่ายสนับสนุนสำหรับนโยบายค่าธรรมเนียมการคืนเงินของบัญชีคุณ

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

ควรทำ​

  • เพิ่ม metadata สำหรับเหตุผลการคืนเงิน
  • ตรวจสอบสถานะ charge ก่อนคืนเงิน (ต้องเป็น successful)
  • ตรวจสอบจำนวนเงินที่สามารถคืนได้ (ยอดเดิม - ที่คืนเงินไปแล้ว)
  • แจ้งลูกค้า เมื่อออกคำสั่งคืนเงิน
  • ติดตามรหัสการคืนเงิน ในระบบของคุณ
  • ตั้งค่า webhooks สำหรับการแจ้งเตือนการคืนเงิน
  • จัดการข้อผิดพลาด อย่างเหมาะสม (เงินไม่เพียงพอ ฯลฯ)

ไม่ควรทำ​

  • อย่าคืนเงิน charge ที่อยู่ระหว่างดำเนินการ (จะล้มเหลว)
  • อย่าเกินจำนวนเงินเดิม (จะล้มเหลว)
  • อย่าคาดหวังเครดิตทันที (ใช้เวลา 5-10 วัน)
  • อย่าคืนเงินโดยไม่ตรวจสอบ (ให้แน่ใจว่าถูกต้อง)
  • อย่าข้ามการติดตามเหตุผล (ใช้ metadata)

การทดสอบ​

การคืนเงินในโหมด Test​

// การคืนเงินในโหมด test ทำงานเหมือนโหมด live
const refund = await omise.charges.refund('chrg_test_xxx', {
  amount: 50000
});

// ตรวจสอบการคืนเงินในแดชบอร์ด test
console.log('การคืนเงิน test:', refund.id);

รหัสความล้มเหลวของการคืนเงิน​

เมื่อการคืนเงินล้มเหลว แอตทริบิวต์ failure_code จะระบุเหตุผล:

รหัสข้อความคำอธิบาย
failed_refund"refund failed"ข้อผิดพลาดในการดำเนินการคืนเงิน
not_refundable"charge cannot be refunded"สถานะ charge ไม่อนุญาตให้คืนเงิน
insufficient_refundable_amount"amount exceeds refundable balance"จำนวนเงินมากกว่าที่มี
invalid_amount"invalid amount"จำนวนเงินเป็นศูนย์หรือติดลบ
refund_limit_exceeded"refund limit exceeded"ถึงจำนวนการคืนเงินสูงสุดแล้ว
charge_not_found"charge not found"ไม่มีรหัส Charge
charge_expired"charge expired"ไม่สามารถคืนเงิน charge ที่หมดอายุได้

ข้อจำกัดการคืนเงิน​

ข้อจำกัดการคืนเงิน
  • ขีดจำกัดเวลา: การคืนเงินต้องทำภายใน 365 วัน ของการเรียกเก็บเงินเดิม
  • การคืนเงินบางส่วน: สูงสุด 15 การคืนเงินบางส่วน ต่อ charge
  • จำนวนเงิน: ไม่สามารถเกินจำนวนเงินเรียกเก็บเงินเดิมหักการคืนเงินก่อนหน้า

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

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

รหัสข้อผิดพลาดสถานะ HTTPคำอธิบายวิธีแก้ไข
not_refundable400ไม่สามารถคืนเงิน Charge ได้ตรวจสอบสถานะ charge (ต้องเป็น successful)
insufficient_refundable_amount400จำนวนเงินเกินยอดที่คืนได้ตรวจสอบ refunded_amount บน charge
invalid_amount400จำนวนเงินไม่ถูกต้องตรวจสอบว่า amount > 0 และเป็น integer
refund_limit_exceeded400การคืนเงินบางส่วนมากเกินไปสูงสุด 15 การคืนเงินบางส่วนต่อ charge

API Reference​

แหล่งข้อมูลที่เกี่ยวข้อง​

ต้องการความช่วยเหลือ? ดู คู่มือการคืนเงิน ของเราหรือติดต่อ support@omise.co