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 as UTC format;

• All API requests must pass the header Content-type: application/JSON;

API Structure

API Return example

{
  "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/false to indicate if the request was successfully processed
result	The json response for your API call
responseException	In case the isError is true, the exception indicating the problem

INFO

For most uses-cases, our customers check if the response isError is true, if not, then checking the statusCode will help you identify the next step.

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.

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

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

• All API endpoints return a 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.

Example API Response

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

For successful responses (isError is false), consult the statusCode for subsequent actions.

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.