paystack-transfers

Paystack Transfers

Transfers API を使用すると、Paystack の残高から銀行口座やモバイルウォレットに送金できます。送金には、事前に作成した送金先が必要です。

依存関係：paystackRequest ヘルパーには paystack-setup が必要です。
関連：送金前に送金先を作成するには paystack-transfer-recipients を使用します。

エンドポイント

Method	Endpoint	Description
POST	/transfer	送金を開始します
POST	/transfer/finalize_transfer	送金を確定します（OTP）
POST	/transfer/bulk	一括送金を開始します
GET	/transfer	送金一覧を取得します
GET	/transfer/:id_or_code	送金を取得します
GET	/transfer/verify/:reference	送金を検証します

送金の開始

POST /transfer

アカウントで OTP が無効になっている場合はステータス pending を、OTP が必要な場合は otp を返します。

Param	Type	Required	Description
source	string	Yes	balance（唯一の選択肢）
amount	integer	Yes	補助単位（コボ／ペセワ）での金額
recipient	string	Yes	送金先コード（例：RCP_gd9vgag7n5lr5ix）
reference	string	Yes	一意の識別子（16～50 文字、小文字の a～z、0～9、-、_）
reason	string	No	送金理由（顧客の入金通知に表示されます）
currency	string	No	通貨コード（デフォルトは NGN）
account_reference	string	No	ケニアで MPESA Paybill および Till への送金を行う場合に必須です

const transfer = await paystackRequest<{
  transfer_code: string;
  status: string;
  reference: string;
  amount: number;
}>("/transfer", {
  method: "POST",
  body: JSON.stringify({
    source: "balance",
    amount: 100000,          // ₦1,000
    recipient: "RCP_gd9vgag7n5lr5ix",
    reference: `txf_${crypto.randomUUID()}`,
    reason: "Vendor payment for January",
  }),
});
// transfer.data.status → "pending" or "otp"
// transfer.data.transfer_code → "TRF_v5tip3zx8nna9o78"

送金の確定

POST /transfer/finalize_transfer

送金ステータスが otp の場合に必要です。ビジネス用電話に送信された OTP を送信します。

Param	Type	Required	Description
transfer_code	string	Yes	送金開始時のレスポンスに含まれる送金コード
otp	string	Yes	ビジネス用電話に送信された OTP

await paystackRequest("/transfer/finalize_transfer", {
  method: "POST",
  body: JSON.stringify({
    transfer_code: "TRF_v5tip3zx8nna9o78",
    otp: "928783",
  }),
});

一括送金の開始

POST /transfer/bulk

1 回のリクエストで複数の送金をまとめて処理します。このエンドポイントを使用するには、アカウントで OTP を無効にする必要があります。

Param	Type	Required	Description
source	string	Yes	balance
transfers	array	Yes	送金オブジェクトの配列

各送金オブジェクト：

Param	Type	Required	Description
amount	integer	Yes	補助単位での金額
recipient	string	Yes	送金先コード
reference	string	Yes	一意の参照（16～50 文字）
reason	string	No	送金理由

const result = await paystackRequest("/transfer/bulk", {
  method: "POST",
  body: JSON.stringify({
    source: "balance",
    currency: "NGN",
    transfers: [
      {
        amount: 20000,
        recipient: "RCP_gd9vgag7n5lr5ix",
        reference: `txf_${crypto.randomUUID()}`,
        reason: "Bonus for the week",
      },
      {
        amount: 35000,
        recipient: "RCP_m7ljkv8leesep7p",
        reference: `txf_${crypto.randomUUID()}`,
        reason: "January salary",
      },
    ],
  }),
});
// result.message → "2 transfers queued."

送金一覧の取得

GET /transfer

Param	Type	Required	Description
perPage	integer	No	1 ページあたりのレコード数（デフォルト：50）
page	integer	No	ページ番号（デフォルト：1）
recipient	integer	No	送金先 ID で絞り込みます
from	datetime	No	開始日
to	datetime	No	終了日

const transfers = await paystackRequest("/transfer?perPage=20&page=1");

送金の取得

GET /transfer/:id_or_code

const transfer = await paystackRequest(
  `/transfer/${encodeURIComponent("TRF_v5tip3zx8nna9o78")}`
);

送金の検証

GET /transfer/verify/:reference

参照を使用して送金のステータスを検証します。

const result = await paystackRequest(
  `/transfer/verify/${encodeURIComponent(reference)}`
);
// result.data.status → "success" | "failed" | "pending" | "reversed"

送金フロー

// 1. Create recipient (see paystack-transfer-recipients skill)
// 2. Initiate transfer
const transfer = await paystackRequest("/transfer", {
  method: "POST",
  body: JSON.stringify({
    source: "balance",
    amount: 500000,
    recipient: "RCP_gd9vgag7n5lr5ix",
    reference: `txf_${crypto.randomUUID()}`,
  }),
});

// 3. If OTP required, finalize
if (transfer.data.status === "otp") {
  const otp = await getOTPFromUser();
  await paystackRequest("/transfer/finalize_transfer", {
    method: "POST",
    body: JSON.stringify({
      transfer_code: transfer.data.transfer_code,
      otp,
    }),
  });
}

// 4. Listen for webhooks: transfer.success, transfer.failed, transfer.reversed

重要な注意事項

• balance からのみ送金できます。Paystack の残高が十分にあることを確認してください
• 一括送金を行うには OTP を無効にする必要があります（Dashboard → Settings → Preferences）
• 送金の参照は一意で、16～50 文字、小文字と -、_ のみを使用する必要があります
• ケニアの MPESA Paybill／Till では、送金に account_reference を含めてください
• ポーリングではなく、Webhook（transfer.success、transfer.failed）で送金ステータスを必ず確認してください