Utility Functions

Utility helpers are useful, but your database should remain the source of truth for references and reconciliation IDs.

Generate References

const reference = client.generateReference('PAY');

Use references that are unique per business and environment. Store the reference before calling Cashonrails so retries can reuse the same value.

Amount Formatting

const amount = client.utils.formatAmount('1000.567');

Send amounts in the unit expected by the endpoint and currency. Do not rely on formatting helpers to enforce business limits; the API still validates limits server-side.

Account Number Checks

const looksValid = client.utils.validateBankAccount('0123456789');

Local format checks are not a replacement for POST /api/v1/account_name, which validates account details with the configured provider.

Recommended Reference Pattern

function paymentReference(orderId) {
  return `order_${orderId}_${Date.now()}`;
}

Avoid putting raw customer PII in references because references appear in logs, dashboards, webhook payloads, and reconciliation exports.