Cashonrails - Developer 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 `encryption key`
Signature	string	HMAC 512 signature using your `encryption key` as the hashing key

Step 2: Generate Signature

To generate the HMAC 512 signature, use your encryption key as the hashing key and the request payload as the message.

Sample Node.js Code

const crypto = require('crypto');
 
const secretKey = 'YOUR_SECRET_KEY';
const payload = JSON.stringify({
    account_number: "0123456789",
    account_name: "John",
    bank_code: "000013",
    amount: "100",
    currency: "NGN",
    sender_name: "John",
    narration: "John",
    reference: "x01234yz"
});
 
const signature = crypto.createHmac('sha512', secretKey).update(payload).digest('hex');
console.log(signature);

Step 3: Prepare Request Body

Include the following parameters in your request body:

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 (e.g. NGN, 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 (recommended to start with your business shortname)
type	string	Required for ZAR only. Transfer type: `EFT` or `RTC`. Defaults to `RTC` if not provided

Step 4: Sample Request

Here is an example of how your request body should look:

{
    "account_number": "0123456789",
    "account_name": "John",
    "bank_code": "000013",
    "amount": "100",
    "currency": "NGN",
    "sender_name": "John",
    "narration": "John",
    "reference": "x01234yz"
}

For ZAR transfers, include the type parameter:

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

Step 5: Sample cURL Request

Use the following cURL command to initiate the transfer:

curl -X POST https://mainapi.cashonrails.com/api/v1/bank_transfer \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Signature: YOUR_HMAC_SIGNATURE" \
-d '{
  "account_number": "0123456789",
  "account_name": "John",
  "bank_code": "000013",
  "amount": "100",
  "currency": "NGN",
  "sender_name": "John",
  "narration": "John",
  "reference": "x01234yz"
}'

For ZAR transfers:

curl -X POST https://mainapi.cashonrails.com/api/v1/bank_transfer \
-H "Content-Type: application/json" \
-H "Authorization: Bearer YOUR_SECRET_KEY" \
-H "Signature: YOUR_HMAC_SIGNATURE" \
-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_transfer_001",
  "type": "EFT"
}'

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
transfer_id	string	Unique identifier for the transfer
reference	string	Your unique identifier for the transfer
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.

Get Bank List Get Wallet Balance