Chains API (マーケットプレイス)

Chains APIは、マーケットプレイスおよびプラットフォームビジネスが、プラットフォームと加盟店間で支払いを分割することを可能にします。自動手数料処理を備えた複数当事者間の支払いフローを構築できます。

利用可能なエンドポイント

• チェーン課金の作成 - POST /charges (with destination)
• チェーン送金の作成 - POST /transfers (with merchant_id)
• チェーン一覧の取得 - GET /chains
• チェーン送金の取得 - GET /chains/:id/transfer

概要

Chains（Omise Linkとも呼ばれる）により以下が可能になります：

• 支払い分割 - プラットフォームと加盟店間で自動分割
• 手数料処理 - 加盟店への支払い前にプラットフォーム手数料を控除
• 複数加盟店への課金 - 顧客に課金し、複数の受取人に分配
• マーケットプレイスフロー - Uber、Airbnb、Shopifyスタイルの支払いフローを構築
• 透明な追跡 - 課金から送金までの支払いチェーン全体を追跡

Chainsの仕組み

1. 顧客が支払う - 送金先（受取人）を指定して課金を作成
2. プラットフォームが受け取る - 全額がプラットフォームアカウントに入金
3. 手数料が控除される - プラットフォーム手数料が自動計算
4. 加盟店が受け取る - 残額が受取人に送金
5. チェーンを追跡 - フロー全体がチェーンIDで連携

前提条件

• チェーン対応アカウント - マーケットプレイス機能を有効にするにはOmiseにお問い合わせください
• 認証済み受取人 - 送金を受け取る前に受取人が認証されている必要があります
• KYCコンプライアンス - 受取人は本人確認を完了する必要があります

認証

すべてのChains APIエンドポイントはシークレットキーを使用した認証が必要です。

手数料計算

プラットフォーム手数料は固定金額および/またはパーセンテージで指定できます：

固定手数料

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

実装例

チェーン課金の作成

// Node.js example
const charge = await omise.charges.create({
  amount: 1000000, // ฿10,000
  currency: 'thb',
  card: 'tokn_test_123',
  description: 'Order #1234 - Platform Marketplace',

  // Destination merchant
  destination: {
    amount: 950000, // ฿9,500 (after ฿500 platform fee)
    recipient: 'recp_test_merchant_456'
  },

  // Platform fee
  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は課金金額からプラットフォーム手数料を引いた額以下である必要があります
• 送金先金額の合計は課金金額を超えることはできません
• プラットフォーム手数料は送金先金額から控除されます
• 送金が開始されるまで、資金はプラットフォームアカウントに保持されます

チェーンステータスのライフサイクル

チェーンは以下の段階を経て進行します：

1. 課金作成 - 顧客の支払いが処理される
2. 課金成功 - 支払いが確認される
3. 送金保留中 - 送金スケジュールを待機中
4. 送金作成 - 加盟店への送金が開始される
5. 送金済み - 資金が受取人の銀行に送金される
6. 支払完了 - 加盟店が資金を受け取る

複数受取人

複数の加盟店に支払いを分割できます：

{
  amount: 1000000, // ฿10,000
  destinations: [
    {
      amount: 400000, // ฿4,000 to merchant A
      recipient: 'recp_test_merchant_a'
    },
    {
      amount: 350000, // ฿3,500 to merchant B
      recipient: 'recp_test_merchant_b'
    }
  ],
  platform_fee: {
    fixed: 250000 // ฿2,500 platform keeps
  }
}

Webhookイベント

Webhookでチェーンの進行状況を監視します：

• charge.complete - 顧客の支払いが成功
• transfer.create - 加盟店への送金が開始
• transfer.sent - 加盟店への資金が送金
• transfer.paid - 加盟店が資金を受け取る

エラー処理

エラー	説明	解決策
chain_not_enabled	アカウントでチェーンが有効になっていない	サポートに連絡して有効化
invalid_destination	受取人が見つからないか非アクティブ	受取人が存在しアクティブであることを確認
destination_amount_exceeds_charge	送金先合計 > 課金金額	送金先金額を減らす
insufficient_balance	送金に十分な残高がない	送金前に課金を完了させる

ベストプラクティス

1. 事前に受取人を確認

チェーン課金を作成する前に、すべての受取人が認証されていることを確認します：

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

2. 追跡にメタデータを使用

注文と加盟店の詳細を保存します：

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

3. 失敗した送金の処理

すべての送金が成功するとは限りません。Webhookを監視し、必要に応じて再試行します：

if (transfer.status === 'failed') {
  // Log failure reason
  console.error('Transfer failed:', transfer.failure_code);

  // Notify merchant
  await notifyMerchant(transfer.recipient, transfer.failure_message);
}

4. 毎日照合

正確な会計のために課金と送金を毎日照合します：

• 日付範囲のすべてのチェーンをリスト
• 各課金に対応する送金があることを確認
• 手数料合計を追跡

制限事項

• 最小送金額: ฿20 (2,000サタン)
• 課金あたりの最大受取人数: 10
• プラットフォーム手数料は課金金額を超えることはできません
• 受取人は認証済みの銀行口座が必要です
• 送金は標準決済スケジュールに従います（タイ7日、日本21日）

関連リソース

• Recipients API - 加盟店受取人の作成と管理
• Transfers API - 手動送金操作