Interaction concepts

Overview

When the Data API is used, access rights are managed with the help of API tokens.

Each of these tokens is generated in the Dashboard interface and is associated with a specific user account and its permissions which regulate access to the merchant's projects. Alongside the token, a secret key is generated to be used for signing requests together with this token and for verifying responses to these requests (to learn more, see Using signatures).

Figure: Generated token and secret key

In the payment platform, managing tokens of the Dashboard user accounts is carried out in compliance with the following requirements:

• Each token is a string, 30 characters long, encoded in UTF-8.
• Each token is valid from the moment of its generation and till the moment when the new token has been generated or when this token has been deactivated. Keep in mind that a deactivated token cannot be reactivated.
• Any number of tokens can be generated for one user account; however, the only vaild token is the one which has been generated last.
• A valid token can be used any number of times without any restrictions imposed on its lifetime.
• In the payment platform, the token inherits the permissions of the user account it is associated with, thanks to which if the permissions granted to a certain user account are modified, generating a new token is not necessary.
• Users authorized to manage tokens can generate and deactivate tokens for their user accounts without any specific constrains.
• If the user account is deleted, the token is not deactivated automatically. However, the data access rights this token has inherited are revoked; hence, if the request is sent with this token, the platform returns the response stating that the access has been denied (401 Authorization Required).

In the merchant's web service, managing tokens and keys may require additional regulations, in compliance with the company's security policies.

Granting permissions to manage tokens

Similarly to other cases of granting permissions to work with Dashboard, only the user whose user account has been assigned the Merchant admin role can grant and withdraw permissions to manage tokens.

Only the user in the Merchant admin role can grant and withdraw the permissions to manage tokens. To grant this right, such user should:

To grant the right to manage tokens, the user with the Merchant admin role should:

1. Go to the My team section.
2. Open the tab of the target user account by clicking the button in the corresponding row of the registry.
3. Check the box Manage API tokens and click the Save changes button thereby confirming the changes that were made.
   
   
4. Make sure that the appropriate permissions were granted: the user account tab should now have the box Manage API tokens checked.

To withdraw the right to manage tokens, the user should go to My team section, open the tab of the target user account, uncheck the box Manage API tokens, save changes and make sure that they have been applied. In this case, the permission to generate a new token and to deactivate the token which is currently valid is no longer available for this user account; however, the permission to use the valid one remains available.

Generating and deactivating tokens

Generating and deactivating tokens is available only for the user accounts authorized to manage tokens.

To generate a token and a secret key, the user whose user account has the appropriate permissions should:

1. Go to the My profile section by clicking the user account name on the right in the main menu of the interface and selecting My profile.
2. Click the New token button on the API Tokens panel.

   If the New token button is absent, it means that this user account was not granted the permission to manage tokens.

3. Copy and save the value of the token and the secret key in accordance with the internal informational security guidelines of the merchant.
   Restriction: The secret key is displayed explicitly only until the page is updated following which it gets hidden and is no longer available. If necessary, when the secret key was lost or compromised, for example, a new token-key pair should be generated.

To deactivate a token, in the user account profile the user should click the Delete button on the API Tokens panel. Afterwards, the token is no longer valid and cannot be used to access the Data API.

Overview

To interact with the payment platform via the Data API, all data from the merchant's web service must be passed in requests—HTTP messages in a specific format—using the POST method. This section covers the general structure of such requests; for the information about the data structure of the specific requests, see the Data API Specification.

Structure

Each HTTP request to the payment platform must include the following elements in the specified order:

• The start line which indicates the HTTP method of the request (POST), the endpoint in the Data API (for example, v1/operations/get ), the protocol and its version (HTTP/1.1).
• The header with the Host field which contains the domain name of the Data API (data.ecommpay.com/v1).
• An empty line which serves as a separator between the message header and the body.
• The message body which contains the JSON string encoded in UTF-8 with request data including the signature.

In addition to the mandatory Host field, the header may include any other fields supported by HTTP version 1.1. Below you will find a sample HTTP request with the recommended header fields and required parameters. The JSON string is formatted for better readability.

POST v1/balance/get HTTP/1.1
User-Agent: curl/7.29.0
Host: data.ecommpay.com/v1
Accept: */*
Content-Length: 179
Content-Type: application/x-www-form-urlencoded
                    
{
    "token":"ZOyTL5shY8...dQyplRPJYmGV7Kv",
    "signature":"...dQcIbv94Z0nPTYX9s2XqYrY9bzkfcBGQ==..."
}                

Addressing parameters

The generated requests must include the base and the relative URLs. The base URL for the Data API requests is the domain name data.ecommpay.com/v1, and the relative URL is the path to the target endpoint in the interface according to the specification.

Message body

The message body must contain the request data in the JSON format. The JSON string follows the format "<parameter name>": <parameter value>. To prevent data loss as a result of spillage or spoofing when data is transferred to the payment platform, the JSON string must include the token and the signature with the request data, and the TLS 1.2 encryption protocol must be used to secure the data transfer. For more information about generating tokens, see Data access model, and to learn more about generating a signature, see Using signatures.

Overview

The ecommpay payment platform responds with an HTTP response message to each request within one HTTP session. The requested data of the response body includes:

• The requested information, if the the request was accepted and executed.
• The information about the error that occurred, if the request cannot be handled.

This section covers the general structure of such responses as well as codes used for communicating the request status. For the information about the data structure of responses to specific requests, see the Data API specification.

Structure

Each HTTP response includes the following elements listed in the order they appear:

• The status line which indicates the protocol and its version (HTTP/1.1), the response status code and the reason phrase (for example, 200 OK).
• Header fields.
• An empty line which serves as a separator between the message header and the body.
• The message body which contains the JSON string encoded in UTF-8 with the response data.

Status codes

HTTP status codes are used in the status line of each response to state the result of the request acceptance and execution or the cause of the error that occurred. In case of the Data API, the following status codes and reason phrases are used.

Error description

If the request contained an error, then the status line indicates the response status code with the cause of the error (in the example below it is 401 Authorization Required), while the message body contains the extended description of this error:

• An explanatory phrase for the response header in the name parameter (in the example—Authorization Required).
• Description of the error in the message parameter (if the error has been processed in the plaform; in the example—You have no access to project_id = 22).
• The service code in the code parameter with the fixed value of 0.
• The code from the response header in the status parameter (in the example, 401).

POST /v1/balance/get HTTP/1.1         // Request from the web service to retrieve balances
                    
HTTP/1.1 400 Bad Request                 //  Response from the payment platform
Server: nginx/1.14.2
Date: Thu, 17 August 2020 10:21:45 GMT
Content-Type: application/json; charset=UTF-8
Transfer-Encoding: chunked
Connection: keep-alive
X-Powered-By: PHP/7.0.33
Expires: Thu, 17 August 2020 10:21:45 GMT
Cache-Control: no-cache
Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: DNT,X-CustomHeader,Keep-Alive,
User-Agent,X-Requested-With,If-Modified-Since,Cache-Control,Content-Type

{
	"name":"Bad Request",
	"message":"You have no access to project_id = 22",
	"code":"0",
	"status":"400"
}