Mandarin

# Basic principles

# Entry points

Production environment for authorization: https://accounts.mandarinbank.com/ (opens new window)

Production environment for queries: https://api.psp.io/ (opens new window)

# Request authentication

Each request must be authenticated using a token (access_token) obtained in accordance with the OAuth 2.0 protocol for applications. The token is valid for 36,000 seconds (10 hours). If the token expires, you must request the token again.

Request for a token

Includes mandatory form-data parameters that are passed in the body of the request (parameters application.client_id and application.client_secret are unchangeable for the application and are stored on the client side).

Parameter Description Example
grant_type authorization grant (always equal to client_credentials). client_credentials
client_id client ID (equal to the value of application.client_id provided by Mandarin). VvPtlhcyldKtkuoUWY42 pErdrj4er2AwFoBWrn8n
client_secret client secret password (equal to the value of application.client_secret provided by Mandarin). uQfOIMsltZYL8x3XMqUGP5 iFM59PyFnKlN0UmD3Ihre2 Ry3AGazUAv5jPdUI4dBJqV 0Of6b9GFvWvzGahYnq2aVV xkxn9n4qWF57FP0C01Kp6l EtajhfYv3UZ2f4pAZ7
scope requested scopes (access areas):
e.g. transactions.read - "Read transactions".
Separator - space.
Any scopes list can be requested, and the response will return the list of requested scopes that can be provided for this application.		 transactions.read
curl --location --request POST 'https://accounts.mandarinbank.com/oauth/token/' \
--form 'grant_type=client_credentials' \
--form 'client_id=VvPtlhcyldKtkuoUWY42pErdrj4er2AwFoBWrn8n' \
--form 'client_secret=uQfOIMsltZYL8x3XMqqP5iFM59PyFnKlN0UmD3Ihre2Ry3AGazUAv5jPdUI4dBJqV0Of6b9GFvWvzGahYnq2aVVxkxn9n4qWF57FP0C01Kp6lEtajhfYv3UZ2f4pAZ7' \
--form 'scope=transactions.read'

Response

Parameter Description Example
access_token token (access key). VnuxZiW14mXBedDeZO7d W7GBmzPxMn
expires_in token expiration date (in seconds). Always equal to 36,000 seconds (10 hours). 36000
token_type token type (always equal to Bearer). Bearer
scope Scopes allowed: for example, transactions.read - "Read transactions".
Separator - space.
Any list of scopes can be requested, and the response will return the list of requested scopes that can be provided for the application.		 transactions.read
{
    "access_token": "VnuxZiW14mXBedDeZO7dW7GBmzPxMn",
    { "expires_in": 36000,
    "token_type": "Bearer",
    "scope": "transactions.read".
}

Token usage

Specified in the headers of each query, in the Authorization field, after the reserved word Bearer.

Authorization:Bearer VnuxZiW14mXBedDeZO7dW7GBmzPxMn

# Operating principles

The API is implemented according to REST API principles.

The API operates with resources that represent entities - objects of business logic (business models, home models, subject area models). There are two the main types of resources: collection resource and entity resource.

Collection resources are named in the plural, e.g: `/transactions'.

An entity resource is the resource of a particular entity in some collection. It is always accessed through a collection resource and by a unique number, for example:

/transactions/{{id}}

The API uses JSON for both responses and requests (if it applicable). API responses are standardized.

Collection resource responses always contain a field with the same name as the resource, and containing an array of business models. If there is no data in response to the query, then the array will be empty. For example, if this is the response of the /transactions resource, then the answer would be:

{ 
   { "transactions": [ 
      { {{transaction_model}} },  
      { ... },  
      { ... } 
   ] 
}

Allowed query parameters:

  • filter_by - selection by specified fields and conditions;

  • sort_by - list of fields (separated by comma) to sort in descending order (by adding - before field name you can switch sorting order to ascending order). By default it is sorted by id;

  • limit_to - limit the number of entities issued at one time; a number, The default is 50;

  • cursor - used to get the next/previous part of the output, has priority over the other queries, that is, if cursor is passed, then the other parameters are ignored.

The filter_by parameter is formed as follows: the list of fields and values by which needs to filter entities, comparison operators (=, >, >=, <, <=, possible use of IN operator), filters are combined by an ampersand sign: & (which denotes the logical operator AND).

The following line is formed:

field_name1=value1&field_name2 in value2_1,value2_2&field_name3>=value3_1&field_name3<value3_2

For example, mw_type=transaction&opcode in 1,3&updated>=2019-10-01&updated<2019-10-31.

Then this URL string is encoded and passed as a value parameter filter_by:

?filter_by=mw_type%3Dtransaction%26opcode%20in%201%2C3%26updated%3E%3D2019-10-01%26updated%3C2019-10-31

The top-level sort_by and limit_to parameters and their values are not URL-encoded.

An example of the resulting `query-string':

?filter_by=mw_type%3Dtransaction%26opcode%20in%201%2C3%26updated%3E%3D2019-10-01%26updated%3C2019-10-31&sort_by=-opcode&limit_to=100

Collection resource responses always contain a nested pagination object (cursor). The cursor object always contains fields:

  • The count is the number of entities in the current response.

  • total - the total number of entities for the given query (with such filters, etc.).

  • next - pointer to the next page of the output (null if no such page exists).

  • prev - pointer to the previous page of the output (null if such page does not exist).

An example query that returns the first 100 entities:

GET /transactions?filter_by=mw_type%3Dtransaction%26opcode%20in%201%2C3%26updated%3E%3D2019-10-01%26updated%3C2019-10-31&sort_by=-opcode&limit_to=100

{
   { "transactions": [ ... ],
   { "cursor": {
      { "count": 100,
      { "next": "aad0f17a6af11672",
      "prev": "f0bb6887c3b2f501",
      { "total": 4200
   }
}

Example of a query to get the next 100 entities (the cursor parameter is replaced by the value from the next response field):

GET /transactions?cursor=aad0f17a6af11672

Entity resource responses always contain a field named like the resource itself, but in the singular, e.g:

GET /transactions/12345

{ 
   { "transactions": { 
      {{transaction_model}}  
   } 
}

← Transaction API →