Cashonrails Merchant Developer API
Use the Merchant API to accept payments, create and manage customers, provision reserved accounts, verify transactions, initiate payouts, and receive asynchronous webhooks.
This documentation is aligned to the current mainApi Merchant API implementation. Where examples use placeholders, replace them with values from your Cashonrails dashboard.
Base URLs
| Environment | Base URL |
|---|---|
| Production | https://api.cashonrails.com |
| Staging | https://mainapi.stag.cashonrails.com |
Merchant API endpoints are served under /api/v1. For example, initialize a hosted checkout with:
POST https://api.cashonrails.com/api/v1/transaction/initializeFastest Safe Integration Path
- Create a Cashonrails merchant account and enable the products your integration needs.
- Generate test keys in Settings > API Keys and Webhook.
- Send all server-side API requests with
Authorization: Bearer <secret_key>. - Initialize a test transaction with
POST /api/v1/transaction/initialize. - Verify the transaction from your backend with
GET /api/v1/transaction/verify/{reference}. - Configure your webhook URL and verify webhook signatures before updating local order state.
- For payouts, upload your RSA public key, sign the exact request body, and use an idempotency key.
- Repeat the same flow with live keys only after test payments, payout failure cases, and webhooks pass QA.
Core Integration Patterns
| Use case | Recommended pattern |
|---|---|
| Hosted payment page | Create a transaction, redirect the customer to authorization_url, then verify server-side and wait for webhook confirmation. |
| Server-to-server collections | Use /api/v1/s2s/* only when your product access is enabled and your backend can handle provider-specific authorization steps. |
| Payouts | Validate account name first, sign payout creation with RSA, send Idempotency-Key, and treat pending as the normal initial outcome. |
| Reserved accounts | Create or reuse a customer first, then create a reserved account for that customer. |
| Webhooks | Verify signatures using the raw request body, persist by event/reference, acknowledge quickly with HTTP 200, and process asynchronously. |
Source-of-Truth Notes
The Merchant API currently enforces bearer secret-key authentication, optional merchant IP allowlisting, product access checks, optional AES-256-GCM payload encryption for enrolled businesses, RSA request signing for payout creation when a public key is configured, rate limits, and webhook resend throttles.
See API Basics, API Keys, API Encryption, RSA Request Signing, and API Reference before building production traffic.