Response format

The service response is a JSON document in UTF‑8, see The application/json Media Type for JavaScript Object Notation (JSON) and official JSON site. The contents depend on the request results.

Successful response example

HTTP/1.1 200 OK
Content-Type: application/json
Content-Length: 51
Expires: Thu, 01 Dec 2019 16:00:00 GMT
Cache-Control: no-cache

{
    "param1":"value1",
    "param2":"value2"
}

The response has HTTP headers to forbid proxy servers and local browsers to cache the content.

The response may contain extra fields not described in this protocol. The application is to ignore them.

If authorization fails, the server responds with a 4xx HTTP code. Possible reasons for rejection:

The request cannot be parsed;
The request does not include the HTTP Authorization header;
The Authorization header specifies a nonexistent, invalid or expired token;
The token does not have permissions for the requested operation.

The response contains the WWW-Authenticate header (in accordance with The OAuth 2.0 Authorization Framework: Bearer Token Usage).

When authorization of the request is denied, the following fields are present in the response:

Field	Description
error	Code of the reason for authorization refusal.
error_description	Additional text description of the reason for refusal.

Codes for reasons for authorization refusal:

HTTP response code	Value of the error field	Description
400	invalid_request	HTTP request does not conform to protocol format. Unable to parse HTTP request, or the `Authorization` header is missing or has an invalid value.
401	invalid_token	Nonexistent, expired, or revoked token specified.
403	insufficient_scope	The token does not have permissions for the requested operation.

Response example for missing header

HTTP/1.1 400 Bad Request
WWW-Authenticate: Bearer error="invalid_request"

Response example for expired token

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Bearer error="invalid_token", error_description="The access token has expired"

Response example for token without required permissions

HTTP/1.1 403 Forbidden
WWW-Authenticate: Bearer error="insufficient_scope", error_description="Payment forbidden by application authorization parameters"

If a technical error occurs, the server responds with the HTTP code 500 Internal Server Error. The application should repeat the request with the same parameters later.