Clientconfiguration – Cashonrails Documentation

Client Configuration

Configure the Node.js client with the same environment, base URL, and credentials used by your backend deployment.

Required Values

Value	Description
`secretKey`	Merchant API secret key. Sent as `Authorization: Bearer <secret_key>`.
`environment`	`TEST` or `LIVE`. Must match the key and resources you are working with.
`baseUrl`	`https://api.cashonrails.com` for production or `https://mainapi.stag.cashonrails.com` for staging.

Optional Values

Value	Description
`timeout`	HTTP timeout in milliseconds. Use a practical timeout such as `30000`.
`headers`	Extra request headers. Do not override `Authorization` unless you are intentionally rotating credentials.
`retryCount`	Retries for transient network failures only. Avoid retrying non-idempotent writes unless an idempotency key is used.
`encryptionKey`	32-byte key for businesses enrolled in AES payload encryption.
`rsaPrivateKey`	Private key used to sign payout creation bodies. Keep it out of source control.

Production Configuration Example


import fs from 'node:fs';
import { CashOnRailsClient } from 'cashonrails-node';
 
export const cashonrails = new CashOnRailsClient(process.env.CASHONRAILS_SECRET_KEY, {
  environment: 'LIVE',
  baseUrl: 'https://api.cashonrails.com',
  timeout: 30000,
  encryptionKey: process.env.CASHONRAILS_ENCRYPTION_KEY,
  rsaPrivateKey: fs.readFileSync(process.env.CASHONRAILS_RSA_PRIVATE_KEY_PATH, 'utf8')
});

Retry Guidance

Retry network timeouts, HTTP 429, and temporary 5xx responses with exponential backoff. Do not blindly retry payout creation without an Idempotency-Key; use the payout reference as the idempotency key when possible.

Security Guidance

Load credentials from runtime secrets, not .env files committed to source control.
Use separate credentials for develop, staging, and production.
Rotate credentials after suspected exposure and after staff or vendor access changes.
Keep frontend applications on public-key or access-code flows only.