Overview

Environments

Zūm Rails provides two environments to make API requests - a sandbox environment for testing, and a live environment where payments are processed.

Environment	Portal URL	API Base URL
Sandbox	https://sandbox.zumrails.com	https://api-sandbox.zumrails.com
Production	https://app.zumrails.com	https://api-app.zumrails.com

The two environments are separate and do not share information.

Production:

• Live Portal: https://app.zumrails.com

• Live API base URL: https://api-app.zumrails.com

• Requests limits*:

  • 1000 requests/5 min for the /api/authorize;

  • 100 requests/5 min for the filter endpoints;

  • 100 requests/5 min for the GET/api/transaction/*;

Sandbox:

• Sandbox Portal: https://sandbox.zumrails.com

• Sandbox API base URL: https://api-sandbox.zumrails.com

• Request limits*:

  • 300 requests/5 min for all endpoints;

*When limits are exceeded, the IP will be blocked for 5 minutes

API Standards

• All datetime fields are stored and returned in UTC format.

• All API requests must pass Content-type: application/json in the header.

API Structure

Example API Response

{
  "statusCode": 200,
  "message": "POST Request successful.",
  "isError": false,
  "result": {}
}

All API endpoints return the same response, containing 4 important pieces of information:

Field	Description
statusCode	The HTTP status code.
message	A message describing if the response was successful.
isError	true or false to indicate if the request was successfully processed.
result	The JSON response for the API call.
responseException	When isError is true, the exception message indicating the problem.

INFO

We recommend first checking if isError is true. If not, use the statusCode to determine the appropriate next steps. For successful responses (isError: false), the statusCode will guide your subsequent actions.

Follow these steps to quickly get started with the Zūm Rails API:

Once you have access to your sandbox portal:

1. Login in your sandbox portal, navigate to Settings -> Webhook & API Settings. Grab your API username and password

2. Download and install the Postman app

3. Install the Zūm Rails Postman Collection. Click the "Run in Postman" button below to install

4. In Postman find the endpoint /Authorize, paste your API username and password and it's all set.

▶ Run in Postman

NOTE

This Postman Collection is already prepared to set the authorization token as an environment variable, so that you don't need to copy and paste the authorization token every time. If you need to change this configuration, go to Authorize endpoint in the Postman Collection, and open the Tests tab to view how this tweak is done.

Postman Collection

To get started with the Zūm Rails API:

1. Login in the sandbox portal.

2. Navigate to Settings -> Webhook & API Settings page, and copy the API username and password.

3. Download and install the Postman app.

4. For your region, click the "Run in Postman" button below to install the Zūm Rails Postman Collection.

5. Open the Postman Collection, find the endpoint /Authorize, and paste your API username and password.

Region

Canada

Postman Collection

Region

United States

Postman Collection

Each Postman Collection is already prepared to set the authorization token as an environment variable, so you don't need to copy and paste the authorization token every time. If you need to change this configuration, go to the Authorize endpoint in the Postman Collection, and review the Scripts tab.