Transfers

Transfers initiate payouts from your Cashonrails wallet. Production payout integrations should validate account details, sign payout creation requests with RSA, send Idempotency-Key, and reconcile using webhooks plus fetch-by-reference.

Validate Account Name


const account = await client.transfer.validateAccountName({
  account_number: '0123456789',
  bank_code: '000013',
  currency: 'NGN'
});

Required fields: account_number, bank_code, and currency.

Initiate Transfer


const reference = 'payout_10045';
 
const transfer = await client.transfer.toBank({
  account_number: '0123456789',
  account_name: 'John Doe',
  bank_code: '000013',
  amount: 100,
  currency: 'NGN',
  sender_name: 'Merchant Name',
  narration: 'Vendor settlement',
  reference
}, {
  idempotencyKey: reference
});

The HTTP request must include:


Authorization: Bearer <secret_key>
X-Signature: <base64-rsa-sha256-signature>
Idempotency-Key: payout_10045

Current successful response shape:


{
  "success": true,
  "status": "32",
  "message": "Transfer Pending",
  "trx": "2025032514551037062256",
  "sessionId": null
}

pending is a normal initial state. Wait for webhook confirmation or fetch transfer details before treating the payout as final.

Payout Fields

Field	Required	Notes
`account_name`	Yes	Recipient account name.
`bank_code`	Yes	Bank or provider code.
`amount`	Yes	Numeric. Runtime rejects values below `1`.
`currency`	Yes	Currency code.
`sender_name`	Yes	Sender display name.
`narration`	Yes	Transfer narration.
`reference`	Yes	Unique reference, 3 to 100 characters.
`account_number`	Required unless `currency` is `USDT`	Recipient account number.
`address`	Required for `USDT`	Wallet address.
`type`	Optional	For `ZAR`: `EFT` or `RTC`. For `KES`: `B2C` or `B2B`.

Other Transfer Operations


const fee = await client.transfer.getTransferFee({ amount: 1000, currency: 'NGN' });
const banks = await client.transfer.bankList('NGN');
const balance = await client.transfer.getWalletBalance('NGN');
const payout = await client.transfer.fetchTransferDetails('payout_10045');
const transfers = await client.transfer.fetchTransfers({ page: 1, limit: 20 });

Failure Handling

HTTP 403 can mean payout access denied or invalid RSA signature.
HTTP 503 means payout processing is temporarily unavailable; retry later with the same idempotency key.
Response status 03 means failed, 32 means pending, and 00 means successful.