Initiatetransfer – Cashonrails Documentation

Initiate Bank Transfer

The Initiate Bank Transfer endpoint allows you to start a bank transfer by providing the necessary details, such as the recipient’s bank account information and the amount to be transferred.

Step 1: Set Up Request Headers

Include the following headers in your request:

Header	Type	Description
Authorization	string	Bearer token with your secret key
Content-Type	string	Must be `application/json`
X-Signature	string	Base64 RSA-SHA256 signature for the exact request body
Idempotency-Key	string	Stable unique key for safe retries. Use the payout reference when possible

Step 2: Sign the Request Body

Payout requests should be signed with your RSA private key. Upload your public key first, then sign the exact request body you send and pass the generated value in the X-Signature header.

See RSA Request Signing for key generation, public key upload, language examples, and security requirements.

The JSON string used to generate X-Signature must match the request body you send exactly. If your account has API encryption enabled, sign the encrypted body because the API verifies the raw bytes it receives.

Currency Specific Instructions

Select the currency you are transferring to view the specific parameters and examples.

NGN

Step 3: Prepare Request Body (NGN)

Parameter	Type	Description
account_number	string	The bank account number of the recipient
account_name	string	The name of the recipient
bank_code	string	The bank code of the recipient’s bank
amount	string	The amount to be transferred
currency	string	NGN
sender_name	string	The name of the sender
narration	string	A description or note for the transfer
reference	string	Your unique identifier for the transfer

Step 4: Sample Request (NGN)


{
    "account_number": "0123456789",
    "account_name": "John Doe",
    "bank_code": "000013",
    "amount": "100",
    "currency": "NGN",
    "sender_name": "Jane Smith",
    "narration": "Payment for services",
    "reference": "ngn_ref_123"
}

Step 5: Sample cURL Request (NGN)


curl -X POST https://api.cashonrails.com/api/v1/bank_transfer \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "X-Signature: YOUR_BASE64_RSA_SIGNATURE" \
-H "Idempotency-Key: ngn_ref_123" \
-d '{"account_number":"0123456789","account_name":"John Doe","bank_code":"000013","amount":"100","currency":"NGN","sender_name":"Jane Smith","narration":"Payment for services","reference":"ngn_ref_123"}'

ZAR

Step 3: Prepare Request Body (ZAR)

Parameter	Type	Description
account_number	string	The bank account number of the recipient
account_name	string	The name of the recipient
bank_code	string	The bank code of the recipient’s bank
amount	string	The amount to be transferred
currency	string	ZAR
sender_name	string	The name of the sender
narration	string	A description or note for the transfer
reference	string	Your unique identifier for the transfer
type	string	Required. Transfer type: `EFT` or `RTC`

Step 4: Sample Request (ZAR)


{
    "account_number": "1234567890",
    "account_name": "Jane Doe",
    "bank_code": "632005",
    "amount": "500",
    "currency": "ZAR",
    "sender_name": "John Smith",
    "narration": "Transfer to Jane",
    "reference": "zar_ref_001",
    "type": "EFT"
}

Step 5: Sample cURL Request (ZAR)


curl -X POST https://api.cashonrails.com/api/v1/bank_transfer \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "X-Signature: YOUR_BASE64_RSA_SIGNATURE" \
-H "Idempotency-Key: zar_ref_001" \
-d '{"account_number":"1234567890","account_name":"Jane Doe","bank_code":"632005","amount":"500","currency":"ZAR","sender_name":"John Smith","narration":"Transfer to Jane","reference":"zar_ref_001","type":"EFT"}'

KES

Step 3: Prepare Request Body (KES)

Parameter	Type	Description
account_number	string	The bank account number or Mobile Number
account_name	string	The name of the recipient
bank_code	string	The bank code or Mobile Provider Paybill
amount	string	The amount to be transferred
currency	string	KES
sender_name	string	The name of the sender
narration	string	A description or note for the transfer
reference	string	Your unique identifier for the transfer
type	string	Required. Transfer type: `B2C` or `B2B`

Step 4: Sample Request (KES)


{
    "account_number": "254712345678",
    "account_name": "Kenyatta",
    "bank_code": "12345",
    "amount": "1000",
    "currency": "KES",
    "sender_name": "Safari Ltd",
    "narration": "Mobile Money Transfer",
    "reference": "kes_ref_001",
    "type": "B2C"
}

Step 5: Sample cURL Request (KES)


curl -X POST https://api.cashonrails.com/api/v1/bank_transfer \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "X-Signature: YOUR_BASE64_RSA_SIGNATURE" \
-H "Idempotency-Key: kes_ref_001" \
-d '{"account_number":"254712345678","account_name":"Kenyatta","bank_code":"12345","amount":"1000","currency":"KES","sender_name":"Safari Ltd","narration":"Mobile Money Transfer","reference":"kes_ref_001","type":"B2C"}'

Others

Step 3: Prepare Request Body (Others)

Parameter	Type	Description
account_number	string	The bank account number of the recipient
account_name	string	The name of the recipient
bank_code	string	The bank code of the recipient’s bank
amount	string	The amount to be transferred
currency	string	The currency code
sender_name	string	The name of the sender
narration	string	A description or note for the transfer
reference	string	Your unique identifier for the transfer

Step 4: Sample Request (Others)


{
    "account_number": "0123456789",
    "account_name": "John Doe",
    "bank_code": "000013",
    "amount": "100",
    "currency": "GHS",
    "sender_name": "John",
    "narration": "Transfer",
    "reference": "ghs_ref_123"
}

Step 5: Sample cURL Request (Others)


curl -X POST https://api.cashonrails.com/api/v1/bank_transfer \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "X-Signature: YOUR_BASE64_RSA_SIGNATURE" \
-H "Idempotency-Key: ghs_ref_123" \
-d '{"account_number":"0123456789","account_name":"John Doe","bank_code":"000013","amount":"100","currency":"GHS","sender_name":"John","narration":"Transfer","reference":"ghs_ref_123"}'

Step 6: Sample Response

Here is an example of a successful response:


{
    "success": true,
    "status": "00",
    "message": "Transfer Initiated Successfully",
    "data": {
        "transfer_id": "12345",
        "reference": "x01234yz",
        "status": "pending"
    }
}

Response Fields

Field	Type	Description
success	boolean	Indicates if the request was successful
status	string	Status code of the request
message	string	Message describing the result
data	object	Contains the transfer details
data.transfer_id	string	Unique identifier for the transfer
data.reference	string	Your unique identifier for the transfer
data.status	string	The status of the transfer

Use this endpoint to initiate a bank transfer, ensuring that all necessary details are provided for a successful transaction.