Bank – Cashonrails Documentation

Server to Server Bank Transfer

Overview

Process bank transfers directly through your server using Cashonrails S2S APIs.

Integration Steps

List Available Banks
Initialize Bank Transfer
Verify Transaction
Cancel Transaction

Each step has specific requirements. Follow the detailed guides below for implementation.

Base URL

https://api.cashonrails.com/api/v1/s2s

1. List Available Banks

Retrieve list of available banks for transfer:


curl --location '{{baseurl}}/banktransfer/list' \
--header 'Authorization: Bearer YOUR_SECRET_KEY'

Sample Response:


{
  "success": true,
  "status": "00",
  "data": [
    {
      "code": "110005",
      "name": "3LINE CARD MANAGEMENT LIMITED"
    },
    {
      "code": "090504",
      "name": "ZIKORA MICROFINANCE BANK"
    }
  ]
}

2. Initialize Bank Transfer

Initialize a bank transfer transaction:


curl --location '{{baseurl}}/banktransfer/initialize' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_SECRET_KEY' \
--data-raw '{
    "email": "test@email.com",
    "amount": "100",
    "currency": "NGN",
    "reference": "{{reference}}",
    "provider": "vfd"
}'

Parameter	Type	Required	Description
email	string	Yes	Customer’s email address
amount	string	Yes	Amount to transfer
currency	string	Yes	Currency code (e.g., NGN)
reference	string	Yes	Unique transaction reference
provider	string	Yes	Bank code from banks list

Sample Response:


{
    "success": true,
    "message": "Account generated successfully",
    "data": {
        "total_amount": "100",
        "account_name": "John Doe Test",
        "account_number": 14771243030,
        "bank_name": "VFD (Test)",
        "expires": "2026-01-02T10:52:05.763658Z",
        "_links": {
            "url": "https://api.cashonrails.com/api/v1/checkout/verify-transaction/s2sref_768706372376985",
            "method": "GET"
        }
    }
}

3. Verify Transaction

Always verify the transaction status:


curl -X GET '{{baseurl}}/transaction/verify/{reference}' \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Sample Response:


{
    "status": true,
    "message": "Transaction verified successfully",
    "data": {
        "reference": "COR_202402210123456789",
        "amount": "100",
        "currency": "NGN",
        "status": "success",
        "payment_method": "bank_transfer"
    }
}

Always verify transaction status before confirming payment. Bank transfers may take a few minutes to complete.

4. Cancel Transaction

You can cancel a transaction that is still pending or in progress:


curl -X GET {{baseurl}}/transaction/cancel/{reference} \
-H "Authorization: Bearer YOUR_SECRET_KEY"

Replace {reference} with your transaction reference.

Cancellation Rules

Only pending or processing transactions can be cancelled
Completed transactions cannot be cancelled (use refund instead)
Failed transactions are already inactive and don’t need cancellation
Once cancelled, a transaction cannot be resumed