Recipients API
Recipients APIを使用すると、Transferの銀行口座の送金先を管理できます。Recipientは、Omise残高から支払いを受け取ることができる確認済みの銀行口座を表します。
概要
Recipientsでは以下のことができます：
- 銀行口座の詳細を安全に保存して繰り返しTransferを実行
- 口座所有者を確認して不正やエラーを防止
- 受取人を管理（マーケットプレイスの販売者、ベンダー、アフィリエイト）
- 複数の銀行をサポート（さまざまな国）
- RecipientのMetadataを追跡してカテゴリ化とレポートを実行
Recipientのタイプ
個人Recipient
個人用の銀行口座。以下が必要です：
- 氏名（銀行口座と 一致）
- 銀行口座の詳細
- メールアドレス（オプションですが推奨）
法人Recipient
企業または法人の銀行口座。以下が必要です：
- 会社名（銀行口座と一致）
- 税IDまたは登録番号
- 銀行口座の詳細
- メールアドレス
Recipientのライフサイクル
- 作成 - 銀行口座の詳細を含む新しいRecipientを追加
- 確認 - 口座所有者を確認（自動または手動）
- アクティブ - RecipientはTransferを受け取ることができる
- 更新 - Recipientの詳細またはMetadataを変更
- 削除 - Recipientを削除（Transferには使用不可）
銀行口座情報
Recipientには銀行口座の詳細が必要です：
- 銀行ブランド - 銀行コード（bbl、scb、kbank、ktb、bayなど）
- 口座番号 - 完全な銀行口座番号
- 口座名義 - 口座名義人の名前（銀行記録と一致する必要があります）
- 支店（オプション） - 一部の国の銀行支店
サポートされている銀行（タイ）
| Bank Code | Bank Name |
|---|---|
| bbl | Bangkok Bank |
| kbank | Kasikornbank |
| scb | Siam Commercial Bank |
| ktb | Krung Thai Bank |
| bay | Bank of Ayudhya (Krungsri) |
| tmb | TMB Bank |
| citi | Citibank |
| smbc | Sumitomo Mitsui Banking Corporation |
| sc | Standard Chartered |
確認プロセス
RecipientはTransferを受け取る前に確認する必要があります：
自動確認
- Omiseが銀行で口座の詳細を確認
- 通常は数分以内に完了
- Recipientステータスが
verified: trueに変更
手動確認
- 複雑なケースまたは特定の銀行タイプの場合
- 追加のドキュメントが必要な場合があります
- 手動確認についてはサポートにお問い合わせください
確認ステータス
verified: false- 確認保留中verified: true- 確認済みでTransfer可能- 確認失敗の場合、Transfer作成時にエラーが発生
認証
すべてのRecipientエンドポイントには、認証のためにSecret Keyが必要です。クライアント側のコードでSecret Keyを公開しないでください。
利用可能なエンドポイント
| Method | Endpoint | Description |
|---|---|---|
| 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をデータベースに保存する
- わかりやすい名前を使用して識別しやすくする
- メールアドレスを追加して通知と確認を行う
- Metadataを使用してカテゴリ化（vendor_type、regionなど）
- 確認失敗を適切に処理する
- 少額でテストしてから大規模なTransferを実行
- Recipient情報を最新に保つ（銀行の詳細が変更された場合に通知）
セキュリティに関する考慮事項
- PCI準拠 - 銀行口座データは保存時に暗号化
- 口座確認 - 不正なTransferを防止
- アクセス制御 - Secret Key認証を使用
- 監査証跡 - すべてのRecipient変更を追跡
- データ保持 - 不要になったRecipientは削除可能
関連リ ソース
- Transfers API - Recipientに資金を送金
- Balance API - 利用可能残高を確認
- Transactions API - Transfer取引を表示
- Webhooks - Recipient確認イベントを受信
サポートが必要ですか？ 銀行口座の確認、サポートされている銀行、または統合のサポートについては、support@omise.coまでお問い合わせください。