General principles

The API is based on the JSON-RPC 2.0 remote procedure of call protocol.

Authorization and security

To ensure security, the cryptographic protocol TLS v1, TLS v1.1 or TLS v1.2 is used.
In order to authorize, the payment instrument must send an Auth HTTP header.

Authorization header structure

HTTP header: Auth: service_id-hash-timestamp

• hash – sha1(secret_key + timestamp)
  
• timestamp - UTC Request signing time in milliseconds
  
• service_id - Identifier of the payment instrument in the PaySys system. (Issued upon registration of a payment instrument)
• secret_key -Payment instrument key. (Issued upon registration of a payment instrument)

Example of HTTP header:
Auth: 05e3bab097f42yu0a62ced0b-7f420a62c22fbe3bab09ed0b57874898-1399114284039

Card Token Header Structure

HTTP header Card-Token: token

• token -Card token. Issued upon card registration.

Example of HTTP header:
Card-Token: reethaa7ae2jooqee90t2neiloh8wai2jo

RPC Request

RPC Request - is JSON object with following fields:

• id - Request ID
• method - Method's name on the remote service
• params - Optional object with method parameters. If there are no parameters in the called method, the field can be omitted or give it a null value ATTENTION! Unlike the original JSON-RPC standard, the "params" field contains only named parameters.

Example of RPC requests:

{
  "method": "method.name",
  "params": {
    "param1": "Any String",
    "param2": [
      "list",
      "of",
      "items"
    ]
  },
  "id": "744a0a7a-f33b-4aa6-a609-a8d44206b2d4"
}

RPC Response

RPC Response - is JSON object with following fields:

• error - [Object with information about the error](#example-rpc-request-completed with error). If the method completed without errors parameter will be NULL
• result - Object with method of execution result
• id - Response ID. The value must be the same as in the request

Example of RPC response:

{
  "id": "744a0a7a-f33b-4aa6-a609-a8d44206b2d4",
  "error": null,
  "result": {
    "param1": "Any String",
    "param2": [
      {
        "id": 123,
        "title": "item 123"
      },
      {
        "id": 124,
        "title": "item 124"
      }
    ]
  }
}

Example RPC Request completed with mistake

Response contains:

• code - Error code
• message - Error description
• data - Additional field with error data. May not be sent or contain an object with arbitrary data

{
  "id": 202,
  "error": {
    "code": -32400,
    "message": "System (interior error)",
    "data": {
      "error": 504,
      "message": "Gateway Time Out"
    }
  },
  "result": null
}