---
title: Introduction
slug: introduction
docTags: 
createdAt: 2024-07-11T10:05:50.645Z
---

:::hint{type="warning"}
**Warning: Draft Documentation Only**

This documentation is currently in draft status. The system is under active development and some details may change over time. Where significant changes are anticipated, these will be highlighted with a callout block.
:::

The Toro Gateway exposes an HTTP API which accepts subsets of the the defined Card Payments Exchange messages from the ISO 20022 specification:

- Acceptor to Acquirer (CAAA) messages
- Terminal Management (CATM) messages

# ISO 20022

This documentation is intended to supplement, *but not replace*, the Nexo Standards documentation.

If you are not already familiar with Nexo Standards and ISO 20022, we recommend that you download the relevant documents from [nexo-standards.org](https://www.nexo-standards.org/); in particular the recommended documents are:

- Nexo Acquirer Message User Guide (MUG) v12.0
- Nexo Card Payment Protocols Security v4.0

Developers may also find the following reference material helpful:

- [ISO 20022 Standards Repository](https://www.iso20022.org/standardsrepository)
- [mx-message.com](https://www.mx-message.com/) (unofficial ISO20022 reference)
- Full XSD schemas for the `caaa` Acceptor to Acquirer messages [in the ISO 20022 catalog](https://www.iso20022.org/catalogue-messages/iso-20022-messages-archive?search=caaa#catalog-message-641).

# Basic API information

## Environments

There are two environments available for integrators:

- Live (production environment)
- Sandbox (testing environment used during integration)

Please note the following:

- Credentials issued for one environment are not valid in other environments
- Live cards should only be used in the live environment
- Test cards should **never** be used in the live environment

The base URLs for each environment are:

Live environment: `https://api.torogateway.com`

Sandbox environment: `https://api.torogateway.dev`



## Data format

Request payloads must be formatted as XML (Content-Type: `application/xml`). Support for JSON content may be added in future releases. Please use the `Content-Type` request header to indicate the content type of your request.

Property names should be specified using the ISO20022 abbreviated format. The full abbreviation list is available [on the ISO20022 website](https://www.iso20022.org/sites/default/files/media/file/XML_Tags.pdf). Support for expanded property names may be added in future releases.

XML should always be minified in the request body; it is important to remove all extraneous whitespace including spaces, indentations and newline characters. Examples provided in the documentation are formatted for readability.

## Versioning

Endpoint URLs include a major version number (e.g. `/v1`).

## Rate limiting

To prevent abuse, rate limiting is enforced. If the rate limit is exceeded, response with status code 429 TOO MANY REQUESTS will be sent.

## Authentication

All API requests must be made over HTTPS. Requests made over plain HTTP will fail. API requests without authentication will also fail.

:::hint{type="warning"}
**Draft documentation:**

Future releases may include a requirement for requests to include a valid API Key in the `X-API-Key` header. An API key will be issued during onboarding and must be sent with every request.
:::

Every request message sent to the Toro Gateway API must include a valid Security Trailer.

:::CtaButton{label="Go to Security Trailer documentation" docId="h-sNkeuMSsUkEctBsZn4t" openInNewTab="true"}

:::

# Errors

When an error occurs during the processing of a request, the API will return an HTTP status code

The API uses conventional HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, an authorisation failed, etc.). Codes in the 5xx range indicate an error with the API's servers.

Generally, an error response will include a response body representing the relevant Rejection message type:

- Acceptor to Acquirer messages will receive errors with message type: `AcceptorRejection` (caaa.015.001.06)
- Terminal Management messages will receive errors with message type: `TerminalManagementRejection` (catm.004.001.05)