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

Chains API (Marketplace)

Chains API ช่วยให้ธุรกิจ marketplace และแพลตฟอร์มสามารถแบ่งการชำระเงินระหว่างแพลตฟอร์มและร้านค้า สร้างขั้นตอนการชำระเงินหลายฝ่ายพร้อมการจัดการค่าคอมมิชชั่นอัตโนมัติ

Endpoints ที่มีให้บริการ​

ภาพรวม​

Chains (หรือเรียกว่า Omise Link) ช่วยให้:

  • แบ่งการชำระเงิน - แบ่งอัตโนมัติระหว่างแพลตฟอร์มและร้านค้า
  • จัดการค่าคอมมิชชั่น - หักค่าธรรมเนียมแพลตฟอร์มก่อนจ่ายให้ร้านค้า
  • เรียกเก็บเงินหลายร้านค้า - เรียกเก็บเงินจากลูกค้าและกระจายให้ผู้รับหลายราย
  • ขั้นตอน Marketplace - สร้างขั้นตอนการชำระเงินแบบ Uber, Airbnb, Shopify
  • ติดตามอย่างโปร่งใส - ติดตามขั้นตอนการชำระเงินทั้งหมดตั้งแต่การเรียกเก็บเงินจนถึงการโอน

การทำงานของ Chains​

  1. ลูกค้าชำระเงิน - สร้างการเรียกเก็บเงินพร้อม destination (ผู้รับ)
  2. แพลตฟอร์มรับเงิน - ยอดเต็มจำนวนเข้าบัญชีแพลตฟอร์ม
  3. หักค่าคอมมิชชั่น - คำนวณค่าธรรมเนียมแพลตฟอร์มอัตโนมัติ
  4. ร้านค้าได้รับเงิน - โอนยอดที่เหลือไปยังผู้รับ
  5. ติดตาม Chain - เชื่อมโยงขั้นตอนทั้งหมดผ่าน chain ID

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

  • บัญชีที่เปิดใช้งาน Chain - ติดต่อ Omise เพื่อเปิดใช้งานฟีเจอร์ marketplace
  • ผู้รับที่ยืนยันแล้ว - ผู้รับต้องได้รับการยืนยันก่อนรับการโอน
  • ปฏิบัติตาม KYC - ผู้รับต้องยืนยันตัวตน

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

Chains API ทุก endpoint ต้องมีการยืนยันตัวตนด้วย secret key ของคุณ

การคำนวณค่าคอมมิชชั่น​

ค่าธรรมเนียมแพลตฟอร์มสามารถระบุเป็นจำนวนคงที่และ/หรือเปอร์เซ็นต์:

ค่าคอมมิชชั่นคงที่​

{
  "platform_fee": {
    "fixed": 50000
  }
}

หัก ฿500.00 (50,000 สตางค์) จากการจ่ายให้ร้านค้า

ค่าคอมมิชชั่นเปอร์เซ็นต์​

{
  "platform_fee": {
    "percentage": 10.5
  }
}

หัก 10.5% จากการจ่ายให้ร้านค้า

ค่าคอมมิชชั่นรวม​

{
  "platform_fee": {
    "fixed": 10000,
    "percentage": 5
  }
}

หัก ฿100 + 5% จากการจ่ายให้ร้านค้า

ตัวอย่างการคำนวณ​

ยอดเรียกเก็บ: ฿10,000 (1,000,000 สตางค์) ค่าธรรมเนียมแพลตฟอร์ม: ฿100 คงที่ + 5% = ฿100 + ฿500 = ฿600 ร้านค้าได้รับ: ฿10,000 - ฿600 = ฿9,400

ตัวอย่างการใช้งาน​

การสร้าง Chain Charge​

// ตัวอย่าง Node.js
const charge = await omise.charges.create({
  amount: 1000000, // ฿10,000
  currency: 'thb',
  card: 'tokn_test_123',
  description: 'Order #1234 - Platform Marketplace',

  // ร้านค้าปลายทาง
  destination: {
    amount: 950000, // ฿9,500 (หลังหักค่าธรรมเนียมแพลตฟอร์ม ฿500)
    recipient: 'recp_test_merchant_456'
  },

  // ค่าธรรมเนียมแพลตฟอร์ม
  platform_fee: {
    fixed: 50000 // ฿500
  },

  metadata: {
    order_id: '1234',
    merchant_id: 'merchant_456',
    customer_email: 'customer@example.com'
  }
});

console.log('Chain ID:', charge.id);
console.log('Status:', charge.status);

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

  • destination.amount ต้องน้อยกว่าหรือเท่ากับยอดเรียกเก็บลบค่าธรรมเนียมแพลตฟอร์ม
  • ยอดรวมของ destination ไม่สามารถเกินยอดเรียกเก็บ
  • ค่าธรรมเนียมแพลตฟอร์มจะถูกหักจาก destination amount
  • เงินจะถูกเก็บไว้ในบัญชีแพลตฟอร์มจนกว่าจะเริ่มการโอน

วงจรสถานะ Chain​

Chains ผ่านขั้นตอนเหล่านี้:

  1. สร้างการเรียกเก็บเงิน - ประมวลผลการชำระเงินของลูกค้า
  2. การเรียกเก็บเงินสำเร็จ - ยืนยันการชำระเงินแล้ว
  3. การโอนรอดำเนินการ - รอกำหนดการโอน
  4. สร้างการโอน - เริ่มการโอนไปยังร้านค้า
  5. ส่งการโอนแล้ว - ส่งเงินไปยังธนาคารของผู้รับ
  6. จ่ายการโอนแล้ว - ร้านค้าได้รับเงินแล้ว

ผู้รับหลายราย​

คุณสามารถแบ่งการชำระเงินให้ร้านค้าหลายราย:

{
  amount: 1000000, // ฿10,000
  destinations: [
    {
      amount: 400000, // ฿4,000 ให้ร้านค้า A
      recipient: 'recp_test_merchant_a'
    },
    {
      amount: 350000, // ฿3,500 ให้ร้านค้า B
      recipient: 'recp_test_merchant_b'
    }
  ],
  platform_fee: {
    fixed: 250000 // ฿2,500 แพลตฟอร์มเก็บไว้
  }
}

Webhook Events​

ติดตามความคืบหน้าของ chain ด้วย webhooks:

  • charge.complete - การชำระเงินของลูกค้าสำเร็จ
  • transfer.create - เริ่มการโอนไปยังร้านค้า
  • transfer.sent - ส่งเงินไปยังร้านค้าแล้ว
  • transfer.paid - ร้านค้าได้รับเงินแล้ว

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

ข้อผิดพลาดคำอธิบายวิธีแก้ไข
chain_not_enabledบัญชีไม่ได้เปิดใช้งาน chainsติดต่อฝ่ายสนับสนุนเพื่อเปิดใช้งาน
invalid_destinationไม่พบผู้รับหรือไม่ได้ใช้งานตรวจสอบว่าผู้รับมีอยู่และใช้งานอยู่
destination_amount_exceeds_chargeยอดรวม destination > ยอดเรียกเก็บลดยอด destination
insufficient_balanceยอดเงินไม่เพียงพอสำหรับการโอนการเรียกเก็บเงินต้องสำเร็จก่อนการโอน

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

1. ยืนยันผู้รับก่อน​

ตรวจสอบว่าผู้รับทั้งหมดได้รับการยืนยันก่อนสร้าง chain charges:

const recipient = await omise.recipients.retrieve('recp_test_123');
if (recipient.verified === false) {
  throw new Error('Recipient not verified');
}

2. ใช้ Metadata สำหรับการติดตาม​

เก็บรายละเอียดคำสั่งซื้อและร้านค้า:

{
  "metadata": {
    "order_id": "ord_123",
    "merchant_id": "merch_456",
    "commission_rate": "5%"
  }
}

3. จัดการการโอนที่ล้มเหลว​

ไม่ใช่ทุกการโอนจะสำเร็จ ติดตาม webhooks และลองใหม่ถ้าจำเป็น:

if (transfer.status === 'failed') {
  // บันทึกเหตุผลความล้มเหลว
  console.error('Transfer failed:', transfer.failure_code);

  // แจ้งร้านค้า
  await notifyMerchant(transfer.recipient, transfer.failure_message);
}

4. ตรวจสอบความถูกต้องรายวัน​

จับคู่การเรียกเก็บเงินกับการโอนรายวันเพื่อการบัญชีที่ถูกต้อง:

  • แสดงรายการ chains ทั้งหมดสำหรับช่วงวันที่
  • ตรวจสอบว่าการเรียกเก็บเงินแต่ละรายการมีการโอนที่สอดคล้องกัน
  • ติดตามยอดรวมค่าคอมมิชชั่น

ข้อจำกัด​

  • ยอดโอนขั้นต่ำ: ฿20 (2,000 สตางค์)
  • ผู้รับสูงสุดต่อการเรียกเก็บเงิน: 10
  • ค่าธรรมเนียมแพลตฟอร์มไม่สามารถเกินยอดเรียกเก็บ
  • ผู้รับต้องมีบัญชีธนาคารที่ยืนยันแล้ว
  • การโอนเป็นไปตามกำหนดการชำระเงินมาตรฐาน (7 วันไทย, 21 วันญี่ปุ่น)

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

  • Recipients API - สร้างและจัดการผู้รับร้านค้า
  • Transfers API - การดำเนินการโอนด้วยตนเอง