Libraries and SDKsNode.jsDeveloper Resources

Developer Resources

Error Handling

The library uses Promise-based error handling for all API interactions.

Error Structure

interface CashOnRailsError {
  message: string;
  code: string;
  status: number;
}

Example Error Handling

try {
  const response = await client.payment.checkout.initialize({
    first_name: "John",
    last_name: "Doe",
    email: "johndoe@gmail.com",
    amount: "100",
    currency: "NGN",
    reference: client.generateReference()
  });
  console.log(response);
} catch (error) {
  console.error('Payment failed:', error.message);
}

TypeScript Support

The library includes comprehensive TypeScript definitions for all features.

Basic Usage with TypeScript

import { CashOnRailsClient, CheckoutResponse } from 'cashonrails-node';
 
const client = new CashOnRailsClient('your_api_key', 'your_public_key', {
  environment: 'TEST'
});
 
interface PaymentData {
  first_name: string;
  last_name: string;
  email: string;
  amount: string;
  currency: string;
  reference: string;
}
 
async function initializePayment(data: PaymentData): Promise<CheckoutResponse> {
  return await client.payment.checkout.initialize(data);
}

API Reference

Client Configuration

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

Pagination Support

Many endpoints support pagination with the following structure:

interface PaginationData {
  limit: number;
  offset: number;
  next_offset: number;
  total: number;
  total_offset: number;
}
 
// Example usage
const transfers = await client.transfer.fetchTransfers(10, 2); // 10 items, page 2
console.log(transfers.pagination);

Common Parameters

ParameterTypeDescription
referencestringUnique transaction reference
currencystringCurrency code (e.g., ‘NGN’)
amountstringTransaction amount
emailstringCustomer email

Best Practices

  1. Error Handling

    • Always wrap API calls in try-catch blocks
    • Log errors with relevant context
    • Implement retry logic for transient failures

  2. References

    • Use client.generateReference() for unique references
    • Store references for future transaction lookup
    • Add custom prefixes for better tracking

  3. Testing

    • Use TEST environment for development
    • Test with various scenarios and edge cases
    • Validate responses before proceeding

  4. Security

    • Never expose API keys in client-side code
    • Validate all input data
    • Store sensitive data securely
Utility FunctionsWordPress