Authentication
Live and Test Mode
There are two environments for your Cashonrails account:
1. Live Mode: This is where real transactions happen using real money. Only switch to Live Mode after thoroughly testing your integration.
2. Test Mode: This is a safe space to test all of Cashonrails’s functionalities without using real funds. You can only use Cashonrails’s provided test cards and bank accounts for transactions in Test Mode. Webhooks, email notifications, and most API functions will still work as expected.
You can easily switch between Live and Test Modes using the toggle button located at the bottom of the menu sidebar. When you switch environments, Cashonrails will automatically update the displayed API keys. Test API keys will always have “_TEST” in the prefix (for example, pk_test_1234567890abcdefghijklmnopqrst).
API Keys
Cashonrails provides two main types of API keys for integration purposes:
1. Public Key: This key is intended for use in public environments like your front-end JavaScript code (e.g., Cashonrails Inline) and Mobile SDKs. It can be used to identify your account and initiate transactions but cannot be used to modify your account settings or perform other actions.
2. Secret Key: This key is highly sensitive and should be treated with the utmost confidentiality. It grants full access to your Cashonrails account and can be used to perform any action, including modifying settings and initiating transactions.
On the settings page of your dashboard under API Keys and Webhook, you will find the following keys:
| Key | Usage |
|---|---|
| Test Secret Key | Used for test environment API authorization |
| Test Public Key | Used for test environment API authorization |
| Live Secret Key | Used for live environment API authorization |
| Live Public Key | Used for live environment API authorization |
Never expose your secret key in public environments such as client-side code.
Here’s a good rule of thumb: If the code is running on the client-side (user’s browser), use the public key. If the code is running on your server, you can use the secret key.
API Parameters
Your dashboard’s settings page under API Keys and Webhook allows you to configure these parameters:
| Parameter | Usage |
|---|---|
| Test Callback URL | Default redirect URL for test checkout sessions |
| Test Webhook URL | URL where test collection and payout webhooks will be sent |
| Live Callback URL | Default redirect URL for live checkout sessions |
| Live Webhook URL | URL where live collection and payout webhooks will be sent |
| Webhook key | A key sent as an authorization header along with all webhooks sent to you |
| Encryption key | Unique key for HMAC 512 encryption |
You can easily switch between Live and Test Modes using the toggle button located at the bottom of the menu sidebar. When you switch environments, Cashonrails will automatically update the displayed API keys. Test API keys will always have “_TEST” in the prefix (for example, pk_test_1234567890abcdefghijklmnopqrst).
How to get your API keys
Cashonrails API keys are essential for successfully interacting with their servers. Here’s how to obtain your keys:
1. Log in to your Cashonrails Dashboard: Access your Cashonrails account dashboard using your login credentials.
2. Navigate to Settings: Locate the “Settings” section within the dashboard interface. This might be represented by a gear icon or a similar menu option.
3. Access API Keys: Within the “Settings” section, find the option labeled “API Credentials” or something similar. This will display your API keys.
Resetting Compromised Keys:
If you believe your secret key has been compromised, you should immediately regenerate it from your Cashonrails dashboard. This will invalidate the old key and ensure the security of your account.
Authenticate your API calls
All API requests to Cashonrails require proper authentication to ensure secure communication.
To successfully interact with Cashonrails’s API, you’ll need to include your secret key in the authorization header of your API requests.
Authorization: Bearer YOUR_SECRET_KEY
Any attempt to access Cashonrails’s servers without authorization will result in a failed request with a status code of.
401: Unauthorized