バージョン: 最新版

サブマーチャントAPI

サブマーチャントAPIを使用すると、マーケットプレイスおよびプラットフォームアカウント向けのサブマーチャントを管理できます。サブマーチャントは、プラットフォームを通じて決済を処理する販売者、ベンダー、サービス提供者を表します。

概要

サブマーチャントを使用すると、以下のことが可能になります：

販売者やベンダーをオンボード - プログラムでプラットフォームに登録
決済の分割 - プラットフォームとサブマーチャント間で分配
加盟店詳細の管理 - 事業者情報や銀行口座を含む
取引の追跡 - サブマーチャントごとに個別に追跡
規制への準拠 - 適切な加盟店記録を維持

サブマーチャントのタイプ

個人サブマーチャント

個人販売者向けの個人アカウント。必要な情報：

正式な氏名
国民ID番号またはパスポート番号
銀行口座詳細
連絡先情報

事業者サブマーチャント

法人または事業者向けアカウント。必要な情報：

登記された事業者名
法人登録番号
税務識別番号
銀行口座詳細
権限を持つ代表者情報

サブマーチャントのライフサイクル

作成 - 必要な事業者詳細を入力して新しいサブマーチャントを登録
保留中 - サブマーチャントは認証およびコンプライアンスチェックを受ける
有効 - サブマーチャントはプラットフォームを通じて決済を受け付け可能
一時停止 - 一時的に無効化（コンプライアンス問題、リクエストなど）
無効化 - プラットフォームから永久に削除

プラットフォーム要件

サブマーチャントAPIを使用するには、お客様のアカウントが以下の条件を満たす必要があります：

プラットフォーム/マーケットプレイスアカウントとして承認済み
サブマーチャント管理が有効化済み
現地の決済規制に準拠
適切なKYC/AML手続きを維持

プラットフォーム機能を有効にするには、Omiseサポートにお問い合わせください。

決済フロー

直接決済

決済はサブマーチャントに直接行われ、プラットフォーム手数料は自動的に差し引かれます。

分割決済

決済は設定されたルールに従って、プラットフォームとサブマーチャント間で分割されます。

集約精算

送金コストを削減するため、複数の取引は精算前に集約されます。

認証

すべてのサブマーチャントエンドポイントは認証にシークレットキーを必要とします。シークレットキーをクライアント側のコードで公開しないでください。

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

メソッド	エンドポイント	説明
POST	`/sub_merchants`	新しいサブマーチャントを作成
GET	`/sub_merchants/:id`	特定のサブマーチャントを取得
GET	`/sub_merchants`	すべてのサブマーチャントを一覧表示
PATCH	`/sub_merchants/:id`	サブマーチャントの詳細を更新
DELETE	`/sub_merchants/:id`	サブマーチャントを無効化
GET	`/sub_merchants/search`	サブマーチャントを検索

一般的なユースケース

マーケットプレイスプラットフォーム

販売者をオンボードし、決済処理、手数料、支払いを管理します。

サービスアグリゲーター

個別の決済アカウントを持つサービス提供者（ドライバー、請負業者、フリーランサー）を管理します。

フランチャイズシステム

集中管理でフランチャイズ店舗の決済処理を設定します。

マルチベンダーEC

単一のストアフロントを通じて複数のベンダーが商品を販売でき、精算は個別に行われます。

予約プラットフォーム

自動決済分割機能でホスト、物件オーナー、サービス提供者を管理します。

ベストプラクティス

サブマーチャントを作成する前に事業者情報を検証
参照用にサブマーチャントIDをデータベースに保存
規制に準拠するため適切なKYCを実施
不正防止のためサブマーチャントの活動を監視
カスタム分類のためメタデータを使用（business_type、regionなど）
Webhookで認証ステータスの変更を処理
本番環境に移行する前にテストモードで十分にテスト
事業者情報が変更された場合は記録を最新の状態に維持

サブマーチャントステータスコード

ステータス	説明
`pending`	認証および承認待ち
`active`	認証済みで決済を受け付け可能
`suspended`	一時的に無効化
`deactivated`	永久に削除
`rejected`	認証失敗

失敗コード

サブマーチャントの作成または認証が失敗した場合、failure_code属性が理由を示します：

コード	メッセージ	説明
`invalid_business_info`	"invalid business information"	事業者詳細を認証できませんでした
`document_required`	"additional documents required"	認証に追加の書類が必要
`bank_account_invalid`	"invalid bank account"	銀行口座の認証に失敗
`compliance_failed`	"compliance check failed"	コンプライアンス要件を満たしていない
`duplicate_merchant`	"duplicate merchant"	サブマーチャントが既に存在
`region_not_supported`	"region not supported"	事業地域がサポートされていない

セキュリティに関する考慮事項

データ暗号化 - すべての機密データは保存時および転送時に暗号化
KYCコンプライアンス - サブマーチャントは本人確認を受ける
不正監視 - 取引は不審な活動について監視
アクセス制御 - シークレットキー認証を使用
監査証跡 - コンプライアンスのためすべての変更をログ

概要​

サブマーチャントのタイプ​

個人サブマーチャント​

事業者サブマーチャント​

サブマーチャントのライフサイクル​

プラットフォーム要件​

決済フロー​

直接決済​

分割決済​

集約精算​

認証​

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

一般的なユースケース​

マーケットプレイスプラットフォーム​

サービスアグリゲーター​

フランチャイズシステム​

マルチベンダーEC​

予約プラットフォーム​

ベストプラクティス​

サブマーチャントステータスコード​

失敗コード​

セキュリティに関する考慮事項​

関連リソース​

概要