Recipients API
Recipients APIを使用すると、送金先の銀行口座を管理できます。Recipientは、Omise残高から支払いを受け取ることができる認証済み銀行口座を表します。
概要
Recipientを使用すると、以下のことが可能です：
- 銀行口座情報を安全に保存 - 繰り返しの送金に使用
- 口座所有権を確認 - 詐欺やエラーを防止
- 支払先を管理 - マーケットプレイスの販売者、ベンダー、アフィリエイト向け
- 複数の銀行をサポート - 異なる国の銀行に対応
- Recipientメタデータを追跡 - 分類やレポート用
Recipientのタイプ
個人Recipient
個人向けの銀行口座。必要な情報：
- 氏名（銀行口座と一致）
- 銀行口座情報
- メールアドレス（任意だが推奨）
法人Recipient
企業または法人向けの銀行口座。必要な情報：
- 会社名（銀行口座と一致）
- 納税者番号または登記番号
- 銀行口座情報
- メールアドレス
Recipientのライフサイクル
- 作成 - 銀行口座情報で新しいRecipientを追加
- 確認 - 口座所有権を確認（自動または手動）
- 有効 - Recipientが送金を受け取れる状態
- 更新 - Recipientの詳細またはメタデータを変更
- 削除 - Recipientを削除（送金に使用不可）
銀行口座情報
Recipientには銀行口座情報が必要です：
- 銀行コード - 銀行コード（bbl, scb, kbank, ktb, bayなど）
- 口座番号 - 完全な銀行口座番号
- 口座名義 - 口座名義人名（銀行記録と一致する必要があります）
- 支店（任意） - 一部の国では銀行支店が必要
対応銀行（タイ）
| 銀行コード | 銀行名 |
|---|---|
| bbl | バンコク銀行 |
| kbank | カシコン銀行 |
| scb | サイアム商業銀行 |
| ktb | クルンタイ銀行 |
| bay | アユタヤ銀行（クルンシィ） |
| tmb | TMB銀行 |
| citi | シティバンク |
| smbc | 三井住友銀行 |
| sc | スタンダードチャータード銀行 |
確認プロセス
Recipientは送金を受け取る前に確認が必要です：
自動確認
- Omiseが銀行で口座情報を確認
- 通常数分で完了
- Recipientのステータスが
verified: trueに変更
手動確認
- 複雑なケースや特定の銀行タイプ向け
- 追加書類が必要な場合あり
- 手動確認についてはサポートにお問い合わせください
確認ステータス
verified: false- 確認待ちverified: true- 確認済みで送金準備完了- 確認失敗は送金作成時にエラーが発生
認証
すべてのRecipientエンドポイントにはシークレットキーによる認証が必要です。シークレットキーをクライアントサイドのコードで公開しないでください。
利用可能なエンドポイント
| メソッド | エンドポイント | 説明 |
|---|---|---|
| POST | /recipients | 新しいRecipientを作成 |
| GET | /recipients/:id | 特定のRecipientを取得 |
| GET | /recipients | すべてのRecipientを一覧表示 |
| PATCH | /recipients/:id | Recipient情報を更新 |
| DELETE | /recipients/:id | Recipientを削除 |
| PATCH | /recipients/:id/verify | Recipient口座を確認 |
一般的な使用例
マーケットプレイスの支払い
各販売者のRecipient口座を作成し、売上に基づいて定期的に支払いを処理します。
ベンダー管理
自動請求書支払いと経費精算のためにベンダーの銀行口座を保存します。
アフィリエイトプログラム
コミッション支払い用のアフィリエイトパートナーの銀行口座を管理します。
従業員経費精算
経費精算と給与支払い用の従業員の銀行口座を保存します。
多通貨支払い
異なる通貨と銀行システムを持つ海外のRecipientをサポートします。
ベストプラクティス
- 作成後すぐにRecipientを確認
- Recipient IDをデータベースに保存
- 識別しやすい説明的な名前を使用
- 通知と確認用にメールアドレスを追加
- 分類用にメタデータを使用（vendor_type、regionなど）
- 確認失敗を適切に処理
- 大きな送金の前に少額でテスト
- Recipient情報を最新に保つ（銀行情報変更時に通知）
Recipientの失敗コード
Recipientの作成または確認が失敗した場合、failure_code属性が理由を示します：
| コード | メッセージ | 説明 |
|---|---|---|
name_mismatch | "name mismatch" | 口座名義が銀行記録と一致しない |
account_not_found | "account not found" | 銀行口座が見つからない |
bank_not_found | "bank not found" | 指定された銀行コードが無効 |
invalid_bank_account | "invalid bank account" | 銀行口座情報が不正 |
invalid_recipient | "invalid recipient" | Recipientデータが無効 |
verification_failed | "verification failed" | 口座確認に失敗 |
セキュリティに関する考慮事項
- PCI準拠 - 銀行口座データは保存時に暗号化
- 口座確認 - 不正な送金を防止
- アクセス制御 - シークレットキー認証を使用
- 監査証跡 - すべてのRecipient変更を追跡
- データ保持 - 不要になったRecipientは削除可能
関連リソース
- Transfers API - Recipientに資金を送る
- Balance API - 利用可能残高を確認
- Transactions API - 送金取引を表示
- Webhooks - Recipient確認イベントを受信
サポートが必要ですか？ 銀行口座確認、対応銀行、統合支援については support@omise.co までお問い合わせください。