How to use API

The API is comprised of various web resources with associated actions that can be used to interact with the system.

Authentication

---

To execute a call within the management API, a user has to be authenticated within the gateway.

After your account is set up, you will receive service user credentials comprised of the username, which starts with "api-", and the password. You have to use these two values for authorization, which can be done via HTTP authentication. To learn more about this method, follow the link. To review examples for HTTP authentication with PHP and Java languages, follow the corresponding links.

Resource URL

---

Resource URL is a value uniquely identifying a particular resource within an API. Note that actual domain name will differ from the one listed in the documentation and always depends on your specific installation. URL is comprised of two types of sub-components: static and dynamic.

Static subcomponents are used for structural purposes and never change.

Dynamic subcomponents represent variables that must be set with appropriate values to access a specific resource or create one that is to be identified by a specific value. Dynamic subcomponents/variables are shown in square brackets (e.g. [variable-name]).

When submitting an API request, you can use either gateway server URL or the Sanitizing Data Filter (Unibroker) server URL as an endpoint.
Requests that contain tokenized card numbers/bank account numbers can be submitted directly to {Unipay} server.
To reduce PCI exposure, requests with non-tokenized (raw) account data should be passed through the sanitizing data filter server. Otherwise, L04 error will be returned (Processing of raw account data is not allowed through the specified API end-point for the current user).
If you don’t have a specific reason, we recommend sending all the requests to the same endpoint (data filter).

Actions

---

Actions are functions associated with resources that perform specific operations. Each action is associated with a single HTTP method. Actions are divided into two groups: implicit and explicit.

Implicit actions can be invoked without explicit indication of the action's name. The name is derived from the HTTP method used. Indicating explicitly name of the action for implicit actions has no negative consequences and can be done if desired.

Explicit actions require action name to be explicitly indicated because HTTP method is not sufficient to conclude that this specific action is desired.

To indicate action's name add / after the owning resource URI, followed by ~ identifying the beginning of the action's name, followed by the name of the action.

Example of calling an action called 'find' on the resource called 'merchants':

https://sandbox-portal.tidypay.com/api/v01/merchants/~find

WADL

---

Dynamic WADL file is available at the following URL:

https://sandbox-portal.tidypay.com/api.wadl?domain=yourdomain

You can specify the value of the domain and generate the file for this domain.

Example of generating WADL file for a particular domain:

https://sandbox-portal.tidypay.com/api.wadl?domain=[server-name].com

Content Type

---

Each action consumes and produces various content types. The following types are supported:

Consumes (request content type):

• json - JSON message
• xml - XML message
• query - query string style parameters
• multipart/binary - binary stream within multi-part request

Produces (response content type):

• json - JSON message
• xml - XML message
• query - query string style parameters
• csv - pipe (|) delimited file
• binary - binary stream

Request content type is derived automatically from the request message sent to the server. Response content type can be identified by appending a dot (.) followed by the name of the content type at the end of the request URL.

Example of calling an action called 'find' on the resource called 'merchants', requesting response content to be xml:

https://sandbox-portal.tidypay.com/api/v01/merchants/~find.xml
When multiple response content types are supported and no preference is indicated by the request, json content type is assumed by default.

Complex Type Parameters

When URL parameter is a complex type, the name of this parameter is derived by concatenation of the original parameters' name and the name of sub-field of the complex type (using dot (.) as a separator).

Handling Special Characters

---

Please note that if you are going to use allowed special characters in API request, they should be encoded.
For example, the filed merchantPassword=Mr.Ap&i O'B"r<ien should be submitted as merchantPassword=Mr.Ap%26i%20O%27B%22r%3Cien.

API Response

API response consists of the header (HTTP status code) and the body.

500 Internal Server Error is returned in the response header if the server encountered an unexpected issue that prevented it from processing and fulfilling the request that you have submitted. In this case, the response is not generated and, thus, the response body is empty.

If the request has been fulfilled on the server, 200 OK is returned in the header, and the API response is generated and returned in the body. The response body may contain an API object - if the request has been processed successfully or a Unipay Exception (response code and error message) - if an application error occurred while processing your request. For example, when processing a sale transaction, 200 OK status code is returned in the header both in the case of approval and decline.