Introduction

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 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 https //www iso20022 org/standardsrepository https //www mx message com/ (unofficial iso20022 reference) full xsd schemas for the caaa acceptor to acquirer messages 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 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 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 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)