Overview

FreedomPay is a universal payment acceptance tool for businesses.

Each documentation script includes all the queries that can be executed to implement the chosen script.

You should read the Overview topic before start.

Call your manager, if you have any questions.

Attention!
Connection doesn't require a PCI DSS certificate

Request format

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 ;:

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.

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.

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) are expanded: each nested value takes part in the signature in the position of its parent parameter, nested values are ordered the same way. 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 = b9ad75871668ca040f80f5f6b530e6ed

Python

PHP

Test cards and mobile phones

Use these cards for payments in test mode (pg_testing_mode = 1).
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`.

Mobile phones

Code	Description	OTP code
Kcell	+77017777777	111111
Activ	+77027777777	111111
Tele2	+77037777777	111111
Altel	+77047777777	111111

Response format and errors

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

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.

Example:

<?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 statuses.

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.

Support

If you found an inaccuracy or need help, feel free to reach out! 👋

Email: support@freedompay.kz

Request format#

Signature#

Example#

Python#

PHP#

Test cards and mobile phones#

Cards for purchase#

Cards that decline the payment#

Cards for payout#

Mobile phones#

Response format and errors#

Support#

Request format

Signature

Example

Python

PHP

Test cards and mobile phones

Cards for purchase

Cards that decline the payment

Cards for payout

Mobile phones

Response format and errors

Support