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

Chains API (มาร์เก็ตเพลส)

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

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

ภาพรวม​

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

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

Chains ทำงานอย่างไร​

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

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

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

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

ปลายทาง Chains API ทั้งหมดต้องการการยืนยันตัวตนโดยใช้ 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% จากการจ่ายเงินให้ผู้ขาย

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

จำนวนเงิน Charge: ฿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 ต้องน้อยกว่าหรือเท่ากับจำนวนเงิน Charge หักค่าธรรมเนียมแพลตฟอร์ม
  • ผลรวมของจำนวนเงินปลายทางไม่สามารถเกินจำนวนเงิน Charge
  • ค่าธรรมเนียมแพลตฟอร์มถูกหักจากจำนวนเงินปลายทาง
  • เงินจะถูกเก็บไว้ในบัญชีแพลตฟอร์มจนกว่าจะเริ่มการโอนเงิน

วงจรสถานะ Chain​

Chains จะผ่านขั้นตอนต่อไปนี้:

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

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

สามารถแบ่งการชำระเงินให้กับผู้ขายหลายราย:

{
  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​

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

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

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

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

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

1. ตรวจสอบผู้รับก่อน​

ตรวจสอบให้แน่ใจว่าผู้รับทั้งหมดได้รับการตรวจสอบก่อนสร้าง Chain Charge:

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. จัดการการโอนเงินที่ล้มเหลว​

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

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

  // แจ้งเตือนผู้ขาย
  await notifyMerchant(transfer.recipient, transfer.failure_message);
}

4. กระทบยอดรายวัน​

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

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

ข้อจำกัด​

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

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

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