Chains API（マーケットプレイス）

Chains APIは、マーケットプレイスとプラットフォームビジネスがプラットフォームとマーチャント間で決済を分割できるようにします。自動手数料処理を伴うマルチパーティ決済フローを構築します。

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

• Charge Chainの作成 - POST /charges（destinationあり）
• Transfer Chainの作成 - POST /transfers（merchant_idあり）
• Chainsの一覧取得 - GET /chains
• Chain Transferの取得 - GET /chains/:id/transfer

概要

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

• 決済分割 - プラットフォームとマーチャント間で自動的に分割
• 手数料処理 - マーチャントへの支払い前にプラットフォーム手数料を差し引く
• マルチマーチャントCharge - 顧客に請求し、複数の受取人に配分
• マーケットプレイスフロー - Uber、Airbnb、Shopifyスタイルの決済フローを構築
• 透明な追跡 - ChargeからTransferまでの決済チェーン全体を追跡

Chainsの仕組み

1. 顧客が支払い - 宛先（受取人）を指定してChargeを作成
2. プラットフォームが受領 - 全額がプラットフォームアカウントに入金
3. 手数料を差し引き - プラットフォーム手数料が自動的に計算されます
4. マーチャントが受領 - 残額が受取人に転送されます
5. Chainを追跡 - Chain IDを介して全フローがリンクされます

前提条件

• Chain対応アカウント - マーケットプレイス機能を有効にするために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%を差し引きます。

計算例

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, // マーチャントAに฿4,000
      recipient: 'recp_test_merchant_a'
    },
    {
      amount: 350000, // マーチャントBに฿3,500
      recipient: 'recp_test_merchant_b'
    }
  ],
  platform_fee: {
    fixed: 250000 // プラットフォームが保持する฿2,500
  }
}

Webhookイベント

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

• `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": {
    "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 - 手動転送操作