Merchant API: payments on the Freedom Pay payment page or in your own interface, payouts, saved cards, payments from the mobile balance, invoices.
The client enters card data on Freedom Pay pages, not on yours: connection does not require a PCI DSS certificate.
Sign every request: see «Signature».
Freedom Pay reports the result of a payment or a payout to your server: see «Callbacks».
HTTP method: POST or GET. Use POST: with GET all parameters, including the signature, are passed in the URL.
The response is XML in any request format, see «Response format and errors» below.
The request can be sent in any of these formats:| Format | How to pass nested parameters (for example pg_receipt_positions) |
|---|
application/x-www-form-urlencoded | pg_receipt_positions[0][name]=value |
multipart/form-data | pg_receipt_positions[0][name]=value |
application/json | JSON array [{…}, {…}] |
| GET, parameters in the query string | pg_receipt_positions[0][name]=value |
XML in the pg_xml parameter (application/x-www-form-urlencoded) | use another format for requests with nested parameters |
In JSON, pass all values as strings, for example "pg_amount": "100.50".
A JSON number is converted before the signature check (100.50 becomes 100.5), so a signature calculated from the original value does not match and the API returns a signature error.
XML example (the pg_xml value):<?xml version="1.0" encoding="utf-8"?>
<request>
<pg_merchant_id>12345</pg_merchant_id>
<pg_order_id>order_1001</pg_order_id>
<pg_amount>100</pg_amount>
<pg_description>Order #1001</pg_description>
<pg_salt>a1b2c3d4</pg_salt>
<pg_sig>…</pg_sig>
</request>
Signature#
Every request and every successful response is signed with pg_salt and pg_sig.
Check pg_sig of a response before using it.
Treat a response without pg_sig as an error: do not use it to confirm a payment or a payout.
To build pg_sig, concatenate with the separator ;:1.
The script name — the last segment of the URL path, exactly as in the request URL: init_payment.php for {domain}/init_payment.php, init_payment for {domain}/init_payment.
2.
The values of all request parameters except pg_sig, sorted by parameter name in alphabetical order. pg_salt (a random string of Latin letters and digits) takes part like any other parameter.
3.
The secret key of the merchant.
Calculate MD5 of the resulting string and pass it in pg_sig as 32 lowercase hexadecimal characters.
Any additional parameters sent in the request, including your own parameters without the pg_ prefix, also take part in the signature.
A parameter added to the request after the signature is calculated makes the signature invalid: the API returns a signature error.Secret key. The merchant has two keys:| Key | Methods |
|---|
| Payment key | all methods except the ones below, see Payments |
| Payout key | reg2nonreg, reg2reg, to_iban, payment_status2, balance_status, see Payouts |
Nested parameters (for example pg_receipt_positions): see «Example with nested parameters» below. Use the code below: it handles nesting.Response signature is calculated by the same rules with the same script name and key: take all fields of <response> except pg_sig.Example#
Request to {domain}/init_payment.php, secret key test_secret_key:String to sign (parameters sorted by name: pg_amount, pg_currency, pg_description, pg_merchant_id, pg_order_id, pg_salt):init_payment.php;100;KZT;Order #1001;12345;order_1001;a1b2c3d4;test_secret_key
pg_sig = MD5 of this string = b9ad75871668ca040f80f5f6b530e6edExample with nested parameters#
The same request with pg_receipt_positions = [{"count": "1", "name": "Book", "tax_type": "0", "price": "100"}].
The nested values take the place of pg_receipt_positions in the sorted list, and are sorted by name among themselves: count, name, price, tax_type.init_payment.php;100;Order #1001;12345;order_1001;1;Book;100;0;a1b2c3d4;test_secret_key
pg_sig = 895bb645704260ac46cf3986038cdca5Python#
PHP#
The response body is XML (Content-Type: text/xml) with the root element <response>.
pg_status — result of the request: ok or error. Some methods also return other statuses; see the method description.
On error: pg_error_code (numeric code) and pg_error_description (text).
pg_error_description is a text for people and may be in Russian whatever pg_language is: handle errors by pg_error_code.
Errors without a signature.
These responses may come without pg_salt and pg_sig:pg_error_code | When | What to do |
|---|
9998 | pg_sig is missing or invalid, or pg_merchant_id is not found. | Check the merchant ID, the script name, the parameters, the order of values and the secret key. |
1100 | pg_merchant_id is not passed. | Pass pg_merchant_id. |
94031 | A required parameter is missing or a parameter has an invalid value. | Check the parameters against the method description. |
Methods also have their own codes, for example 11005 for an invalid amount; see the method description.<?xml version="1.0" encoding="utf-8"?>
<response>
<pg_status>error</pg_status>
<pg_error_code>9998</pg_error_code>
<pg_error_description>Некорректная подпись запроса</pg_error_description>
</response>
| HTTP status | Body | When | What to do |
|---|
200 | XML <response> | Every API answer, including errors. | Check pg_status; on error, see pg_error_code. |
403, 404 | Not XML <response>, for example an HTML page | The URL is wrong or the request was blocked before reaching the API. | Check the host and the path. |
| Any other | Not XML <response> | The API did not return its answer: network, gateway or server failure. | The result of the operation is unknown. Request the status by pg_order_id with Get payment status before sending the request again. |
For the full list of pg_error_code values, see Error codes.
Callbacks#
Freedom Pay sends the result of a payment to pg_result_url, the result of a payout to pg_post_link.
Confirm the order by this callback or by Get payment status: the client may not return to pg_success_url.
Test mode#
To make a test payment, pass pg_testing_mode = 1 in the payment request. Test mode can also be enabled for the whole merchant: contact your account manager.
Requests in test mode go to the same host and are signed the same way.
In test mode use the cards and phone numbers below. Expiry date for all cards: 12/30.
Cards for purchase#
— the operation succeeds, — the payment system declines it with error 99999.| Card number | 3DS | Payment and card saving | Capture | Cancel before capture | Refund |
|---|
| 4716047261941981 | No | | | | |
| 4916307416334310 | Yes | | | | |
| 4939770956154989 | No | | | | |
| 5367654276102126 | Yes | | | | |
| 5555555555555599 | No | | | | |
| 4400444400004444 | Yes | | | | |
| 6224466455690681278 | No | | | | |
| 623275279933273424 | No | | | | |
| 62528733472390953 | No | | | | |
Capture is needed only for a two-step payment (pg_auto_clearing = 0). A one-step payment is captured right away with any card from the table.
Cancel before capture: cancelling a two-step payment that is not captured yet. Cancelling a captured payment is a refund: see the Refund column.
No Visa or Mastercard card supports every operation. To test capture and refund, use 4716047261941981. To test cancel before capture, use 4939770956154989. UnionPay cards support every operation.
Cards that decline the payment#
The payment is declined with the error code from the table.| Card number | Error code |
|---|
| 5335215945367703 | 99999 |
| 4916109830832246 | 100066 |
| 5548398681700148 | 10009 |
| 5475102935853613 | 11036 |
| 5555555555555557 | 11024 |
| 4444444444444422 | 10001 |
| 4444444411111111 | 10022 |
| 4444444499999999 | 10018 |
| 5484458131482832 | 10004 |
There is no test card for errors 11008, 9014 and 8889 (3DS failed) that the payment page accepts.Cards for payout#
| Card number | Result |
|---|
| 4671593866478252 | Success. |
| 6204500338419360939 | Success. |
| 629656013969216940 | Success. |
| 62861819783765929 | Success. |
| 5325349472901311 | Declined with error 10000. |
| 4556046085041740 | Declined with error 10001. |
| 5543974702876045 | Declined with error 11052. |
| 5507841999732294 | Status process first, then success. |
| 4532676596620704 | Status process first, then declined with error 10000. |
Phone numbers for mobile balance payments#
| Operator | Phone number | SMS code |
|---|
| Kcell | +77017777777 | 111111 |
| Activ | +77027777777 | 111111 |
| Tele2 | +77037777777 | 111111 |
| Altel | +77047777777 | 111111 |
Support#
If you find an inaccuracy in the documentation or need help with the integration, write to support@freedompay.kz. For connection and merchant settings, contact your account manager.