# Overview

<figure><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2FcZvcZuAo3uhojK6Y6XTf%2Fimage.png?alt=media&#x26;token=edf9c5ee-fdcd-4915-8a5a-7c0580ce36cc" alt=""><figcaption></figcaption></figure>

## Environments

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

<table><thead><tr><th width="166">Environment</th><th width="279">Portal URL</th><th>API Base URL</th></tr></thead><tbody><tr><td>Sandbox</td><td><a href="https://sandbox.zumrails.com/">https://sandbox.zumrails.com</a></td><td><a href="https://api-sandbox.zumrails.com/">https://api-sandbox.zumrails.com</a></td></tr><tr><td>Production</td><td><a href="https://app.zumrails.com/">https://app.zumrails.com</a></td><td><a href="https://api-app.zumrails.com/">https://api-app.zumrails.com</a></td></tr></tbody></table>

The two environments are separate and do not share information.&#x20;

Production:

* Live Portal: [https://app.zumrails.com](https://app.zumrails.com/)
* Live API base URL: [https://api-app.zumrails.com](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](https://sandbox.zumrails.com/)
* Sandbox API base URL: [https://api-sandbox.zumrails.com](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**

{% tabs %}
{% tab title="Example API Response" %}

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

{% endtab %}
{% endtabs %}

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

<table><thead><tr><th width="186.20001220703125">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>statusCode</code></td><td>The HTTP status code.</td></tr><tr><td><code>message</code></td><td>A message describing if the response was successful.</td></tr><tr><td><code>isError</code></td><td><code>true</code> or <code>false</code> to indicate if the request was successfully processed.</td></tr><tr><td><code>result</code></td><td>The JSON response for the API call.</td></tr><tr><td><code>responseException</code></td><td>When <code>isError</code> is <code>true</code>, the exception message indicating the problem.</td></tr></tbody></table>

{% hint style="info" %}
**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.
{% endhint %}

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](https://god.postman.co/run-collection/10947695989d0c951b02?action=collection%2Fimport)

{% hint style="info" %}
**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.
{% endhint %}

## 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.

<table data-view="cards"><thead><tr><th>Region</th><th>Postman Collection</th><th data-hidden data-card-target data-type="content-ref"></th></tr></thead><tbody><tr><td>Canada</td><td><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2FbcevEbwe1GCscTgX7mzP%2Fbutton.svg?alt=media&#x26;token=a372d570-a954-4ef1-84b6-e7d96b182ec0" alt=""></td><td><a href="https://god.postman.co/run-collection/10886392-036e1f78-a103-4fbe-88ec-b1bfdf9fc255?action=collection%2Fimport">https://god.postman.co/run-collection/10886392-036e1f78-a103-4fbe-88ec-b1bfdf9fc255?action=collection%2Fimport</a></td></tr><tr><td>United States</td><td><img src="https://1258268478-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FKJSaSy1sLkMkigNL7ONH%2Fuploads%2FbcevEbwe1GCscTgX7mzP%2Fbutton.svg?alt=media&#x26;token=a372d570-a954-4ef1-84b6-e7d96b182ec0" alt=""></td><td><a href="https://god.postman.co/run-collection/28802020-61bb02e8-2e3e-46e7-a293-4d70fc65010a?action=collection%2Fimport">https://god.postman.co/run-collection/28802020-61bb02e8-2e3e-46e7-a293-4d70fc65010a?action=collection%2Fimport</a></td></tr></tbody></table>

{% hint style="info" %}
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.
{% endhint %}