Main – Cashonrails Documentation

Node.js Backend Integration

Use the Node.js library or your HTTP client from a trusted backend service. This section mirrors the current Merchant API contract: bearer secret-key authentication, optional AES payload encryption, product access gates, RSA payout signing, idempotent payout creation, and webhook verification.

What Belongs on the Backend

Capability	Backend responsibility
Checkout initialization	Create the transaction with `POST /api/v1/transaction/initialize`, store your reference, and return only checkout handoff data to the frontend.
Transaction verification	Call `GET /api/v1/transaction/verify/{reference}` before fulfilment and during reconciliation.
Customer and reserved account management	Create customers and reserved accounts using the merchant secret key.
Payouts	Validate account names, sign payout bodies with RSA, send `Idempotency-Key`, and reconcile by reference.
Webhooks	Verify raw-body signatures, persist events, respond quickly, and process idempotently.

Quick Start


npm install cashonrails-node


import { CashOnRailsClient } from 'cashonrails-node';
 
const client = new CashOnRailsClient(process.env.CASHONRAILS_SECRET_KEY, {
  environment: process.env.NODE_ENV === 'production' ? 'LIVE' : 'TEST',
  baseUrl: process.env.CASHONRAILS_BASE_URL || 'https://api.cashonrails.com',
  timeout: 30000
});

If your installed SDK version still expects a public key as the second constructor argument, pass the public key there and keep the secret key as the first argument. The secret key is the credential used for Merchant API authorization.

Initialize Checkout


const reference = `order_${Date.now()}`;
 
const checkout = await client.payment.checkout.initialize({
  email: 'customer@example.com',
  first_name: 'Ada',
  last_name: 'Lovelace',
  amount: 5000,
  currency: 'NGN',
  reference,
  redirectUrl: 'https://merchant.example/payments/callback',
  title: 'Order #10045'
});
 
return {
  reference: checkout.data.reference,
  transactionRef: checkout.data.transactionRef,
  authorizationUrl: checkout.data.authorization_url,
  accessCode: checkout.data.access_code
};

Verify Before Fulfilment


const verification = await client.payment.checkout.verify(reference);
 
if (verification.status === true && verification.data.status === 'success') {
  // Fulfil the order once, guarded by your local order state.
}

Production Checklist

Store CASHONRAILS_SECRET_KEY, encryption keys, webhook keys, and RSA private keys in a secret manager.
Never expose the backend client to frontend bundles.
Generate and persist your own unique reference before calling Cashonrails.
Treat pending as a normal intermediate state.
Use webhooks plus verification for final state changes.
Retry only transient failures, 429, and 5xx responses with backoff.

See API Reference for the route-level contract.