Merchant API
Introduction
About service
FreedomPay is a universal payment acceptance tool for businesses.
The service provides the ability to accept payments, payouts to bank cards, as well as save cards. Basic scenarios are described in the "Payment scenarios" section.
The scenarios are divided into three parts:
About service
FreedomPay is a universal payment acceptance tool for businesses.
The service provides the ability to accept payments, payouts to bank cards, as well as save cards. Basic scenarios are described in the "Payment scenarios" section.
The scenarios are divided into three parts:
- Acceptance of payments. This section describes the mechanics in which FreedomPay deducts money in favor of the merchant and subsequently transfers it to the appropriate current account.
- Payouts. This section describes the mechanics when FreedomPay pays money to the user's bank card.
- Save cards. Basic mechanics for saving cards. Further, the saved cards can be used both for receiving payments and for payments.
Query Mechanics
The API supports GET requests and POST requests with Content-type equal to form-data or x-www-form-urlencoded
Data can be sent:
The API supports GET requests and POST requests with Content-type equal to form-data or x-www-form-urlencoded
Data can be sent:
- GET method - data is passed in GET parameters; when transferring complex structured data, such as multidimensional arrays, the following notation format is used: https://api.freedompay.kz/script.php?param_1=val¶m_2[subParam_1]=val2& param_2[subParam_2]=val3¶m_3=val4
- POST method - data is transmitted in POST parameters. Structural data when working via POST are formed in a similar way.
- Via XML - requests are also transmitted by the Post method, only in the only pg_xml parameter, presented in XML form:
Пример:
<?xml version="1.0" encoding="utf-8"?><request><pg_param1>value1</pg_param><pg_param2>value2</pg_param></request>
Signature generation
Any messages (requests and responses) between FreedomPay and the merchant are signed. To form a signature, you must concatenate with the delimiter ;
It is necessary to calculate md5 from the string received as a result of concatenation and add it to the request or response as an additional parameter pg_sig. The MD5 hash is written as a lowercase hexadecimal string (32 characters).
Any party can add additional parameters to the request or response that are not specified in the documentation. These parameters are also involved in the signature calculation. The message is not signed, and accordingly the pg_salt and pg_sig fields are missing only in one case - when FreedomPay could not identify the merchant and therefore does not know its secret_key. In this case, the pg_error_code field (numerical error code) takes the value 101.
Any messages (requests and responses) between FreedomPay and the merchant are signed. To form a signature, you must concatenate with the delimiter ;
- name of the called script (from the last / to the end or ?)
- all message fields in alphabetical order, including a random string pg_salt, consisting of an arbitrary number of digits and Latin letters, while: a. for nested tags, this rule is applied recursively (XML only) b. fields with the same name are taken in the order in which they appear in the message
- and payment password secret_key, which is set in the store settings and is known only to the merchant and FreedomPay.
It is necessary to calculate md5 from the string received as a result of concatenation and add it to the request or response as an additional parameter pg_sig. The MD5 hash is written as a lowercase hexadecimal string (32 characters).
Any party can add additional parameters to the request or response that are not specified in the documentation. These parameters are also involved in the signature calculation. The message is not signed, and accordingly the pg_salt and pg_sig fields are missing only in one case - when FreedomPay could not identify the merchant and therefore does not know its secret_key. In this case, the pg_error_code field (numerical error code) takes the value 101.
All new merchants are initially in test mode, then after testing is completed and the merchant sends the signed Act of connection to FreedomPay, the administration of FreedomPay switches the merchant into working mode.
In test mode, you can use only test payment methods, while in production mode, on the contrary, payment by test payment methods is not possible.
After the merchant switches to production mode, you can create separate transactions in test mode by passing the pg_testing_mode parameter in requests to create a payment and to receive a list of payment methods. The value pg_testing_mode=1 enables test mode for one specific transaction. To conduct test transactions in production mode, you need to contact the manager to clarify the details. If the merchant itself is in test mode, then the value of the passed pg_testing_mode flag is irrelevant. Enabling and disabling the test mode in the merchant settings is carried out only by the FreedomPay administration.
After the transaction is created, no automatic actions take place with it. In order to test the further passage of the transaction, you need to go to the administrative panel and enter the transaction. Then control its actions using the test buttons.
As the name of the card, you must specify at least 2 words in the English layout.
Password for 3-D Secure verification: 12345678 List of test cards:
In test mode, you can use only test payment methods, while in production mode, on the contrary, payment by test payment methods is not possible.
After the merchant switches to production mode, you can create separate transactions in test mode by passing the pg_testing_mode parameter in requests to create a payment and to receive a list of payment methods. The value pg_testing_mode=1 enables test mode for one specific transaction. To conduct test transactions in production mode, you need to contact the manager to clarify the details. If the merchant itself is in test mode, then the value of the passed pg_testing_mode flag is irrelevant. Enabling and disabling the test mode in the merchant settings is carried out only by the FreedomPay administration.
After the transaction is created, no automatic actions take place with it. In order to test the further passage of the transaction, you need to go to the administrative panel and enter the transaction. Then control its actions using the test buttons.
As the name of the card, you must specify at least 2 words in the English layout.
Password for 3-D Secure verification: 12345678 List of test cards:
Test phone numbers
The mechanics of mobile commerce involves testing within a number of operators. Below will be provided the numbers and their corresponding OTP codes for testing
List of rooms:
The mechanics of mobile commerce involves testing within a number of operators. Below will be provided the numbers and their corresponding OTP codes for testing
List of rooms: