paystack-transfer-recipients

Paystack 送金先

Transfer Recipients API を使用すると、送金を受け取る受取人を作成、管理できます。送金を開始する前に、受取人を作成する必要があります。

依存関係：paystackRequest ヘルパーを提供する paystack-setup。
関連：受取人に送金する paystack-transfers。

エンドポイント

メソッド	エンドポイント	説明
POST	/transferrecipient	受取人を作成
POST	/transferrecipient/bulk	受取人を一括作成
GET	/transferrecipient	受取人を一覧表示
GET	/transferrecipient/:id_or_code	受取人を取得
PUT	/transferrecipient/:id_or_code	受取人を更新
DELETE	/transferrecipient/:id_or_code	受取人を削除（無効化）

受取人の種類

種類	説明	国
nuban	ナイジェリアの銀行口座（NUBAN）	ナイジェリア
ghipss	ガーナ銀行間決済・精算	ガーナ
mobile_money	モバイルマネーのウォレット	ガーナ、ケニア
basa	南アフリカの銀行口座	南アフリカ
authorization	以前の課金認証を使用	全て

送金先の作成

POST /transferrecipient

口座番号が重複している場合、新しいレコードを作成する代わりに既存のレコードを返します。

パラメーター	型	必須	説明
type	string	はい	nuban、ghipss、mobile_money、または basa
name	string	はい	受取人の名前（口座に登録されている名前）
account_number	string	はい*	銀行口座番号／携帯電話番号（* authorization タイプでは不要）
bank_code	string	はい*	List Banks エンドポイントの銀行コード（* authorization タイプでは不要）
description	string	いいえ	この受取人の説明
currency	string	いいえ	通貨コード（例：NGN、GHS、ZAR）
authorization_code	string	いいえ	過去の取引で使用した認証コード
metadata	object	いいえ	追加の構造化データ

ナイジェリアの銀行口座（NUBAN）

const recipient = await paystackRequest<{
  recipient_code: string;
  name: string;
  type: string;
}>("/transferrecipient", {
  method: "POST",
  body: JSON.stringify({
    type: "nuban",
    name: "Tolu Robert",
    account_number: "0123456789",
    bank_code: "058",    // GTBank — get codes from List Banks endpoint
    currency: "NGN",
  }),
});
// recipient.data.recipient_code → "RCP_m7ljkv8leesep7p"

ガーナの銀行口座（GHIPSS）

await paystackRequest("/transferrecipient", {
  method: "POST",
  body: JSON.stringify({
    type: "ghipss",
    name: "Kwame Asante",
    account_number: "0551234987",
    bank_code: "GH010100",
    currency: "GHS",
  }),
});

モバイルマネー

await paystackRequest("/transferrecipient", {
  method: "POST",
  body: JSON.stringify({
    type: "mobile_money",
    name: "Ama Serwah",
    account_number: "0551234987",
    bank_code: "MTN",      // Mobile money provider code
    currency: "GHS",
  }),
});

認証ベース

await paystackRequest("/transferrecipient", {
  method: "POST",
  body: JSON.stringify({
    type: "authorization",
    name: "Customer Refund",
    authorization_code: "AUTH_ekk8t49ogj",
  }),
});

送金先の一括作成

POST /transferrecipient/bulk

パラメーター	型	必須	説明
batch	array	はい	受取人オブジェクトの配列（作成時と同じパラメーター）

const result = await paystackRequest("/transferrecipient/bulk", {
  method: "POST",
  body: JSON.stringify({
    batch: [
      {
        type: "nuban",
        name: "Habenero Mundane",
        account_number: "0123456789",
        bank_code: "033",
        currency: "NGN",
      },
      {
        type: "nuban",
        name: "Soft Merry",
        account_number: "9876543210",
        bank_code: "50211",
        currency: "NGN",
      },
    ],
  }),
});
// result.data.success[] — successfully created recipients
// result.data.errors[] — failed recipients

送金先の一覧表示

GET /transferrecipient

パラメーター	型	必須	説明
perPage	integer	いいえ	1ページあたりのレコード数（デフォルト：50）
page	integer	いいえ	ページ番号（デフォルト：1）
from	datetime	いいえ	開始日時
to	datetime	いいえ	終了日時

const recipients = await paystackRequest("/transferrecipient?perPage=20&page=1");

送金先の取得

GET /transferrecipient/:id_or_code

const recipient = await paystackRequest(
  `/transferrecipient/${encodeURIComponent("RCP_m7ljkv8leesep7p")}`
);

送金先の更新

PUT /transferrecipient/:id_or_code

パラメーター	型	必須	説明
name	string	はい	更新後の受取人名
email	string	いいえ	更新後の受取人のメールアドレス

await paystackRequest(
  `/transferrecipient/${encodeURIComponent("RCP_m7ljkv8leesep7p")}`,
  {
    method: "PUT",
    body: JSON.stringify({ name: "Rick Sanchez" }),
  }
);

送金先の削除

DELETE /transferrecipient/:id_or_code

受取人を非アクティブ状態にします（論理削除）。

await paystackRequest(
  `/transferrecipient/${encodeURIComponent("RCP_m7ljkv8leesep7p")}`,
  { method: "DELETE" }
);