Skip to main content

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
}