Getting Started

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.

Terms used in API

User - 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.

Recurring 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.

How to start?

Step 1. Read the documentation

First of all, before continuing you should read the documentation to find out if it's the right tool, which you are looking for.

Step 2. Get Paysera account

At this time recurring billing API is only available in Production, which is used as a real environment. To obtain an account register in Paysera.

Посмотреть видео инструкцию

Step 3. Create Checkout project

Create a Checkout project and fill all the required information.

Посмотреть видео инструкцию

Step 4. Contact Paysera

Contact Paysera with a description of how are you going to implement Recurring Billing API and your project ID. We will determine if there are no problems with enabling this API for your business.

Step 5. Get API credentials

If your business is compatible, we will configure API client and send credentials to you. You can now begin to integrate Recurring Billing API.

Step 6. Get your business reconfigured

In order to collect real payments, contact Paysera, so we can reconfigure your business.

Authentication

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:   Opb2XVb-gEh4aGcR09Ko5Wb8V_6vueDM
mac_id:        wkVd93h2uS
mac_key:       IrdTc8uQodU7PRpLzzLTW6wqZAO6tAMU
mac_algorithm: hmac-sha-256

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

• 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 HTTP/1.1
Host: checkout-eu-a.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="B3iRmOP5pZCTt5AdhJDnOj9O1F3U/oZ5z7Z6WgbG6h4="

Calculating MAC value

Normalized request string

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.

GET /notification/rest/v1/notifications/ABcJDZe-rWzLgQKxZTamdfZRApsrPuyE HTTP/1.1
Host: checkout-eu-a.paysera.com
User-Agent: Paysera WalletApi PHP library
Authorization: MAC id="wkVd93h2uS", ts="1343811600", nonce="nQnNaSNyubfPErjRO55yaaEYo9YZfKHN", mac="3WhLKS7daZvTA0c/GP6H+ORnIo5WPDamhHRcUCtwTF0="

1343811600\n
nQnNaSNyubfPErjRO55yaaEYo9YZfKHN\n
GET\n
/notification/rest/v1/notifications/ABcJDZe-rWzLgQKxZTamdfZRApsrPuyE\n
checkout-eu-a.paysera.com\n
443\n
\n

MAC calculation algorithm

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.