cashonrails-node

v1.2.0

Published

2 months ago

CashOnRails Node.js SDK for seamless integration with the CashOnRails API, enabling payments, transfers, reserved accounts, and customer management in both TEST and LIVE environments.

0High
0Medium
0Low

cashonrails

fintech cashonrails

CashOnRails NPM Library

The CashOnRails library provides a seamless way to integrate with the CashOnRails API for payments, transfers, reserved accounts, and customer management. This library is designed for Node.js applications and supports both TEST and LIVE environments.

Installation

Install the library using npm:

npm install cashonrails-node

Or with yarn:

yarn add cashonrails-node

Quick Start

Import the library and initialize the client:

import { CashOnRailsClient } from 'cashonrails-node';

const client = new CashOnRailsClient('your_api_key', 'your_public_key', {
  environment: 'TEST', // Use 'LIVE' for production
});

Generate a unique reference and process a payment:

// Generate a unique reference
const reference = client.generateReference();

// Create a payment checkout
const checkout = await client.payment.checkout.initialize({
  first_name: "John",
  last_name: "Doe",
  email: "[email protected]",
  amount: "100",
  currency: "NGN",
  reference: reference,
  redirectUrl: "https://yourwebsite.com/callback",
  title: "Payment for Order",
  description: "Order #12345",
  logoUrl: "https://yourwebsite.com/logo.png"
});

console.log('Checkout Response:', checkout);

Features

| Feature | Description | |-----------------------|-----------------------------------------------------------------------------| | Payments | Initialize checkout, verify transactions, and process direct charges. | | Transfers | Transfer funds to banks, validate accounts, and fetch transfer history. | | Reserved Accounts | Create and manage reserved accounts for customers. | | Customer Service | Create, retrieve, and manage customer profiles. | | Utilities | Generate unique references and other helper functions. |

API Reference

Payment Service

Initialize Checkout

| Parameter | Type | Description | |----------------|----------|--------------------------------------| | first_name | string | Customer's first name. | | last_name | string | Customer's last name. | | email | string | Customer's email address. | | amount | string | Payment amount. | | currency | string | Payment currency (e.g., NGN). | | reference | string | Unique transaction reference. | | redirectUrl | string | Callback URL after payment. | | title | string | Payment title. | | description | string | Payment description. | | logoUrl | string | URL of your logo. |

const response = await client.payment.checkout.initialize({
  first_name: "John",
  last_name: "Doe",
  email: "[email protected]",
  amount: "100",
  currency: "NGN",
  reference: client.generateReference(),
  redirectUrl: "https://yourwebsite.com/callback",
  title: "Payment for Order",
  description: "Order #12345",
  logoUrl: "https://yourwebsite.com/logo.png"
});

console.log('Checkout Response:', response);

Verify Transaction

| Parameter | Type | Description | |--------------------------|----------|--------------------------------------| | transaction_reference | string | Reference of the transaction to verify. |

const response = await client.payment.checkout.verify('transaction_reference');
console.log('Verify Transaction Response:', response);

Direct Charge via Card

| Parameter | Type | Description | |----------------|----------|--------------------------------------| | email | string | Customer's email address. | | amount | string | Payment amount. | | currency | string | Payment currency (e.g., NGN). | | card | object | Card details (number, cvv, etc.). |

const response = await client.payment.directCharge.card({
  email: "[email protected]",
  amount: "100",
  currency: "NGN",
  card: {
    number: "4111111111111111",
    cvv: "123",
    expiryMonth: "12",
    expiryYear: "25",
    pin: "1234"
  }
});

console.log('Direct Charge Response:', response);

Initialize Bank Transfer

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | account_number | string | Customer's account number. | | bank_code | string | Bank code. | | amount | string | Transfer amount. | | currency | string | Transfer currency (e.g., NGN). | | email | string | Customer's email address. | | reference | string | Unique transaction reference. |

const response = await client.payment.directCharge.initBankTransfer({
  account_number: "1234567890",
  bank_code: "000013",
  amount: "5000",
  currency: "NGN",
  email: "[email protected]",
  reference: client.generateReference()
});

console.log('Bank Transfer Response:', response);

List Available Banks

const banks = await client.payment.directCharge.listAvailableBanks();
console.log('Available Banks:', banks);

Charge with Mobile Money

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | phone_number | string | Customer's phone number. | | provider | string | Mobile money provider (e.g., mtn). | | amount | string | Payment amount. | | currency | string | Payment currency (e.g., NGN). | | email | string | Customer's email address. | | reference | string | Unique transaction reference. |

const response = await client.payment.directCharge.chargeWithPhone({
  phone_number: "08012345678",
  provider: "mtn",
  amount: "2000",
  currency: "NGN",
  email: "[email protected]",
  reference: client.generateReference()
});

console.log('Mobile Money Charge Response:', response);

Transfers

Transfer to Bank

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | account_number | string | Recipient's account number. | | account_name | string | Recipient's account name. | | bank_code | string | Recipient's bank code. | | amount | string | Transfer amount. | | currency | string | Transfer currency (e.g., NGN). | | sender_name | string | Sender's name. | | narration | string | Transfer narration. | | reference | string | Unique transfer reference. |


const response = await client.transfer.toBank({
  account_number: "1234567890",
  account_name: "John Doe",
  bank_code: "000013",
  amount: "100",
  currency: "NGN",
  sender_name: "Your Business Name",
  narration: "Payment for services",
  reference: client.generateReference()
});

console.log('Transfer to Bank Response:', response);

Get Wallet Balance

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | currency | string | Currency code (e.g., NGN). |


const balance = await client.transfer.getWalletBalance('NGN');
console.log('Wallet Balance:', balance);

Validate Account Name

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | account_number | string | Account number to validate. | | bank_code | string | Bank code. | | currency | string | Currency code (e.g., NGN). |

const accountInfo = await client.transfer.validateAccountName({
  account_number: "1234567890",
  bank_code: "000013",
  currency: "NGN"
});

console.log('Account Validation Response:', accountInfo);

Get Transfer Fee

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | amount | string | Transfer amount. | | currency | string | Currency code (e.g., NGN). |

const fee = await client.transfer.getTransferFee({
  amount: "1000",
  currency: "NGN"
});

console.log('Transfer Fee:', fee);

Fetch Transfers

const transfers = await client.transfer.fetchTransfers();
console.log('Transfers:', transfers);

Fetch Transfer Details

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | reference | string | Transfer reference ID. |

const transferDetails = await client.transfer.fetchTransferDetails("COR_251010143052940856");
console.log('Transfer Details:', transferDetails);

Sample Response:

{
  "success": true,
  "status": "00",
  "data": {
    "id": 392364,
    "trx": "202510101430895228355",
    "reference": "COR_251010143052940856",
    "transactionRef": null,
    "sessionid": "999999251010143217777199179287",
    "currency": "NGN",
    "amount": "100",
    "fee": "10",
    "account_name": "Scott Lexium",
    "account_number": "0000000000",
    "bank_name": "OPAY",
    "bank_code": "100004",
    "narration": "Payment for test Cashonrails",
    "domain": "live",
    "status": "success",
    "created_at": "2025-10-10T13:30:53.000000Z",
    "updated_at": "2025-10-10T13:32:24.000000Z"
  }
}

Get Bank List

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | currency | string | Currency code (e.g., NGN). |

const banks = await client.transfer.bankList({
  currency: "NGN"
});

console.log('Bank List:', banks);

Reserved Accounts

Create Reserved Account

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | customer_code | string | Unique customer code. | | provider | string | Bank provider (e.g., wema). |

const account = await client.reservedAccounts.create({
  customer_code: "CUS_12345",
  provider: "wema"
});

console.log('Reserved Account Creation Response:', account);

Retrieve All Reserved Accounts

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | page | number | Page number (default: 1). | | limit | number | Number of results per page. |

const accounts = await client.reservedAccounts.retrieveAll(1, 20);
console.log('All Reserved Accounts:', accounts);

Retrieve One Reserved Account

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | account_id | string | ID of the reserved account. |

const account = await client.reservedAccounts.retrieveOne('account_id');
console.log('Reserved Account Details:', account);

Get Account Providers

const providers = await client.reservedAccounts.accountProviders();
console.log('Account Providers:', providers);

Customer Service

Create Customer

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | email | string | Customer's email address. | | first_name | string | Customer's first name. | | last_name | string | Customer's last name. | | phone | string | Customer's phone number. |

const customer = await client.customerService.create({
  email: "[email protected]",
  first_name: "John",
  last_name: "Doe",
  phone: "08012345678"
});

console.log('Customer Creation Response:', customer);

Retrieve All Customers

const customers = await client.customerService.retrieveAll();
console.log('All Customers:', customers);

Retrieve One Customer

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | customer_code | string | Unique customer code. |

const customer = await client.customerService.retrieveOne({ customer_code: "CUS_12345" });
console.log('Customer Details:', customer);

Utilities

Generate Reference

| Parameter | Type | Description | |------------------|----------|--------------------------------------| | prefix | string | Optional prefix for the reference. |

const reference = client.generateReference('COR');
console.log('Generated Reference:', reference);

Pagination

Some endpoints, such as fetching transfers or retrieving reserved accounts, support pagination. The pagination object in the response contains the following properties:

| Property | Type | Description | |----------------|----------|--------------------------------------------------| | limit | number | The maximum number of items per page. | | offset | number | The starting point for the current page. | | next_offset | number | The offset for the next page, if available. | | total | number | The total number of items available. | | total_offset | number | The total number of pages available. |

Example: Fetch Transfers with Pagination

const transfers = await client.transfer.fetchTransfers(10, 2); // Fetch 10 transfers starting from page 2

console.log('Transfers with Pagination:', transfers.pagination);

You can use the pagination object to navigate through the results.

Error Handling

The library uses Promise-based error handling:

try {
  const response = await client.payment.checkout.initialize({
    // Payment details
  });
  console.log(response);
} catch (error) {
  console.error('Payment failed:', error.message);
}

TypeScript Support

The library includes TypeScript definitions for all functions and data structures, providing complete type safety and autocompletion in compatible editors.

Contributing

Contributions are welcome! Please read the Contributing Guide for details on how to get started.

License

This project is licensed under the MIT License. See the LICENSE file for details.

Support

For support, please contact [email protected] or visit our documentation.