API Keys
Cashonrails issues separate credentials for test and live traffic. Use the dashboard environment toggle to view or generate credentials for the selected mode.
Credential Types
| Credential | Where to use it | Security handling |
|---|---|---|
| Public key | Browser checkout, mobile SDKs, identifying a business in public flows. | Can be exposed to clients, but should still be scoped to Cashonrails usage. |
| Secret key | Server-side Merchant API and S2S API requests. | Never expose publicly. Store only in a backend secret manager. |
| Encryption key | AES-256-GCM payload encryption for businesses enrolled in API encryption. | 32-byte secret. Store like a password. |
| Webhook key | Merchant-side verification of outbound Cashonrails webhooks when enabled. | Store server-side only. |
| RSA public key | Uploaded to Cashonrails to verify payout request signatures. | Public by design. |
| RSA private key | Used by your backend to sign payout request bodies. | Never upload or share. Rotate immediately if exposed. |
Secret keys and encryption keys are shown only when generated or regenerated. If a secret is lost, regenerate the affected credentials and deploy the new values to your backend.
Test and Live Modes
Test keys create test-mode resources and can be used for QA without moving real money. Live keys create live resources and can move real funds.
Do not mix keys across environments. A transaction or payout reference created in test mode should be verified with a test secret key; a live reference should be verified with a live secret key.
Key Rotation
Rotate keys when onboarding a new production environment, after staff changes that affect secret access, after a suspected exposure, or as part of your regular security calendar.
Recommended rotation pattern:
- Generate new credentials in the dashboard.
- Store them in your secret manager.
- Deploy the backend with the new values.
- Run smoke tests for transaction initialization, verification, payout signing, and webhooks.
- Remove old credentials from runtime environments and CI secrets.
Dashboard Settings
Configure these values from Settings > API Keys and Webhook:
| Setting | Purpose |
|---|---|
| Test callback URL | Default redirect URL for test checkouts. |
| Test webhook URL | Test-mode webhook destination. |
| Live callback URL | Default redirect URL for live checkouts. |
| Live webhook URL | Live-mode webhook destination. |
| RSA PEM key | Public key used by Cashonrails to verify signed payout requests. |
Common Pitfalls
- Using a public key in the
Authorizationheader. Use the secret key. - Sending live traffic with test keys.
- Regenerating keys without updating all worker and scheduler environments that also call Cashonrails.
- Treating the encryption key as an HMAC key. AES encryption and HMAC/webhook signatures are separate mechanisms.