Overview

General information

This documentation provides detailed information on the available methods for managing various types of cards and transactions.
Payment Cards – Covers methods for issuing and managing bank cards issued by a partner bank. This section provides information about API methods designed for managing bank cards. You can use these methods to issue new cards, check balances, retrieve card information, and perform other card-related operations. The API enables seamless integration of card functionalities into your systems, ensuring convenient and secure access to card data. In addition to standard card operations, the API provides functionality for validating cardholder identity. This includes verifying that the personal details provided by a user (first name, last name, and phone number) match the information registered with the system for a given card token.
Gift Cards – Describes methods for issuing gift cards, which are based on prepaid bank cards.
Transactions – Provides an overview of transaction methods designed for debiting and funding issued cards.
This API allows seamless integration of card issuance and transaction functionalities into your system, ensuring a secure and efficient payment experience.

Query Mechanics

ENV	Request method	Request body format	Request URL
PROD	POST	JSON	https://api.freedompay.kz
TEST	POST	JSON	https://test-api.freedompay.kz

Request Header

Name	Value	Description
Content-type	application/json	Request body format
JWS-Signature	string	Request signature

Request-Id must be unique. If duplicates are found, an error will be returned and the request will not be processed.

Authorization

Request authorization occurs by generating and passing the JWS token in the X-JWS-Signature header.
The JWS is the part of the JWT token that contains only the header and signature.
Request type application/json.

Signature generation example

Request Body:

{
    "request_id": "828cf71d-a447-4a67-a149-c1df8bc197ca"
}

JWT token header:

{
  "uri": "/v5/card-api/request/status",
  "auth_id": "123456",
  "method": "POST",
  "params": "",
  "alg": "HS512"
}

The partner key can be secret. In this case, the following JWT token can be generated:

eyJ1cmkiOiIvdjUvY2FyZC1hcGkvcmVxdWVzdC9zdGF0dXMiLCJhdXRoX2lkIjoiMTIzNDU2IiwibWV0aG9kIjoiUE9TVCIsInBhcmFtcyI6IiIsImFsZyI6IkhTNTEyIn0.eyJyZXF1ZXN0X2lkIjoiODI4Y2Y3MWQtYTQ0Ny00YTY3LWExNDktYzFkZjhiYzE5N2NhIn0.f1sQoeIpX_ZjOaykQzSeylvvKaVrEQV4gNM2ACFbEMkFDUV9Zk5WO1yQGEWez-vnQMVHodLBDVEyh5Xm2-3MjQ

The partner needs to cut out the part containing payload from the JWT token and get the following line:

eyJ1cmkiOiIvdjUvY2FyZC1hcGkvcmVxdWVzdC9zdGF0dXMiLCJhdXRoX2lkIjoiMTIzNDU2IiwibWV0aG9kIjoiUE9TVCIsInBhcmFtcyI6IiIsImFsZyI6IkhTNTEyIn0..f1sQoeIpX_ZjOaykQzSeylvvKaVrEQV4gNM2ACFbEMkFDUV9Zk5WO1yQGEWez-vnQMVHodLBDVEyh5Xm2-3MjQ

This string is the signature of the request and must be passed in the X-JWS-Signature request header parameter.
Supported signature encryption algorithm HS512.

General information#

Query Mechanics#

Request Header#

Authorization#

Signature generation example#

General information

Query Mechanics

Request Header

Authorization

Signature generation example