Libraries and SDKsNode.jsUtility Functions

Utility Functions

The Cashonrails library provides several utility functions to help with common tasks when integrating with the API.

Generate Reference

The generateReference function creates unique transaction references for payments, transfers, and other operations.

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

Parameters

ParameterTypeRequiredDescription
prefixstringNoCustom prefix for the reference (default: ‘COR’)

Response

Returns a string in the format: {prefix}_XXXXXXXXXXXXX where X is an alphanumeric character.

Format Amount

Formats monetary amounts to ensure proper decimal places:

const amount = client.utils.formatAmount('1000.567');
console.log('Formatted Amount:', amount); // Output: 1000.57

Parameters

ParameterTypeRequiredDescription
amountstring|numberYesAmount to format
decimalsnumberNoNumber of decimal places (default: 2)

Validate Bank Account

Validates bank account number format:

const isValid = client.utils.validateBankAccount('0123456789');
console.log('Is Valid Account:', isValid); // Output: true or false

Parameters

ParameterTypeRequiredDescription
accountNumberstringYesAccount number to validate

Error Handling

try {
  const reference = client.generateReference();
} catch (error) {
  console.error('Error generating reference:', error.message);
}

Best Practices

  • Always store generated references for future reference
  • Use try-catch blocks when calling utility functions
  • Validate inputs before processing
  • Use formatted amounts for consistency in monetary values

Complete Example

const { CashOnRailsClient } = require('cashonrails-node');
 
const client = new CashOnRailsClient('YOUR_SECRET_KEY');
 
async function utilityExample() {
  try {
    // Generate unique reference
    const reference = client.generateReference('PAY');
    console.log('Payment Reference:', reference);
 
    // Format amount
    const amount = client.utils.formatAmount('1000.567');
    console.log('Formatted Amount:', amount);
 
    // Validate account number
    const isValid = client.utils.validateBankAccount('0123456789');
    console.log('Valid Account:', isValid);
  } catch (error) {
    console.error('Error:', error.message);
  }
}
Customer ManagementDeveloper Resources