About Recurring Billing API

Recurring billing is when a merchant automatically charges a cardholder for specified goods or services on a prearranged schedule. Recurring billing requires the merchant to get the cardholder’s permission one time up front for recurring charges.

Important Public registration is not yet available, it's still Beta, please contact our support to register the client for this API. You will be provided with your credentials.

Terms used in API

Most of the terms represent resources, available in API. For more detailed descriptions please refer to the documentation available in other chapters of the specification.
User who pays in your e-commerce project.
Payment Request
Resource which is an entry point in any payment flow. It can be processed via user interaction or automatically using recurring billing method.
Reccuring billing
Payment flow method in which user can be charged without his or her interaction, it can be done only after first user's successful payment.

API Basics

API is based on REST principles. The client makes HTTP requests to Paysera system, providing information about the intended action. HTTP verbs GET, POST, PUT and DELETE are used in this API. In POST and PUT requests content request is usually provided in JSON format by using UTF-8 encoding. If some other format is used, it is specified in the method description.

Paysera system provides JSON encoded response to each request. HTTP status code identifies the status of the request - for successful requests, status code 200 is returned. In case of an error, some information like a code and description is provided to debug the problem more easily, so that the client could try to decode the response even if an error code is returned.

If some elements of returned structure are optional, they can be skipped. That is, null is not returned, the JSON element is entirely skipped. Client should handle these situations and do not assert that the element will definitely exist if it's optional.

Errors and response codes

In case of a success, API returns status code 200. In case of an error, the status code differs from case to case. The client should always check the response status code to know what kind of response is given. In case of an error, response body is the error object. It's structure is provided in the table below.
Parameter Type Remarks Description
error string always Code of the error. One of defined in this API
error_description string not always Description of the error
error_uri string not always Link to the site explaining the error or how to avoid it
Basic error codes (available in all API methods) are the following:
  • invalid_request (status code 400) - Request content is invalid
  • invalid_parameters (status code 400) - Some required parameter is missing or it's format is invalid
  • invalid_state (status code 409) - Requested action cannot be made to the current state of resource
  • unauthorized (status code 401) - Authentication parameters are not provided or are incorrect
  • forbidden (status code 403) - The client has no right to access the requested resource or perform the requested action
  • not_found (status code 404) - Resource was not found
  • internal_server_error (status code 500) - Unexpected internal system error
  • not_acceptable (status code 406) - Unknown request or response format
Some other probable error codes are provided in descriptions of methods.

Error response example

HTTP/1.1 403 Forbidden
Content-type: application/json;charset=utf-8
    "error": "forbidden",
    "error_description": "This resource is assigned to other project, client has no rights to read it"


All API calls must be authenticated. Currently, one authentication scheme is used:

  • By using MAC access authentication - providing the signature of the request as a header in each request. The shared secret key is used, but never sent with the request. This authentication protocol is always used to provide the access token (getting user's information).

In any case, all requests to the Paysera system are made using HTTPS protocol. Paysera system always authenticates the client, but the client needs to be sure that the authentication on Paysera server is performed too.

MAC access authentication

MAC access authentication used in API is based on the OAuth 2.0 Message Authentication Code (MAC) Tokens specification.

Before using API, you must register your app in Paysera system. Public registration is not yet available, please contact our support to register the client for this API. You will be provided with your credentials, for example:

business_id:   IrdTc8uQodU7PRpLzzLTW6wqZAO6tAMU
mac_id:        Opb2XVb-gEh4aGcR09Ko5Wb8V_6vueDM
mac_key:       i-_Qs9Jzn7UqBts7Ts5cEiC2CRROpOag
mac_algorithm: hmac-sha-256
Important mac_key must be kept secret at all times.
Info You are recommended to use provided libraries that do most of the authentication work for you, if one is available for your programming language.
Info All MAC authentication header examples in this specification are valid and generated with these credentials.

At each request to API the client must construct an authentication header by calculating the UNIX timestamp and generating a random string used as a nonce. From these values, together with the HTTP request method, request URI, hostname, port and mac_key, the client has to calculate hash using the algorithm defined by mac_algorithm. This calculated hash is mac value, which must be included in the authorization header.

Authorization header

Authorization header must contain the authorization protocol (MAC) and the following parameters:
  • id - ID assigned to the client making the request (client_id);
  • ts - calculated UNIX timestamp;
  • nonce - randomly generated value; only characters in ranges %x20-21 / %x23-5B / %x5D-7E can be used;
  • mac - calculated hash of request values and mac_key;
  • ext - extension to MAC protocol. May contain parameter body_hash and extra parameters project_id, location_id. Parameters are URL-encoded. body_hash is the result of sha256 and base64 encoded request content if it's present. If there is no content, body_hash should be omitted. ext can be empty if there are no parameters, including body_hash.
POST /checkout/rest/v1/payment-requests
Host: checkout-eu-a.paysera.com
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="Fq2JdkPxXggdNUjjhMuMXD6TNxwyTC8bkG3bJGIx3L4="

Calculating MAC value

mac value is calculated from the normalized request string and mac_key parameter.

Normalized request string

The normalized request string is constructed by concatenating together, in order, the following HTTP request elements, each followed by a new line character (%0A when urlencoded, \n in most of programming languages):
  1. timestamp;
  2. nonce;
  3. HTTP request method in upper case;
  4. HTTP request URI;
  5. Host request header in lower case;
  6. Request port - in this API always 443;
  7. The value of ext field - URL-encoded string containing various extra parameters.
An example - a request and a corresponding normalized request string, \n given just for clarity and represents a new line character:
GET /notification/rest/v1/notifications/ABcJDZe-rWzLgQKxZTamdfZRApsrPuyE
Host: checkout-eu-a.paysera.com
Warning New line character must be put after each of elements, even after the last one when it is just an empty string

MAC calculation algorithm

If MAC algorithm is hmac-sha-256, mac is calculated using HMAC algorithm together with the sha256 hash function:
mac = HMAC-SHA256(mac_key, normalizedRequestString)

Please refer to HMAC and SHA256 specifications for more details on these algorithms.

The result is provided as a binary result, encoded in base64.