Page - Freedom Pay

Request

Body Params multipart/form-data

pg_order_id

string

required

Payment ID in the merchant system. It is recommended to keep this field unique.

Example:

00102

pg_merchant_id

integer

required

Merchant ID in {{project}} issued upon connection.

pg_amount

number

required

Payment amount in pg_currency. Minimum 0.01

Example:

10

pg_description

string

required

Description of the product or service. Displayed to the customer during the payment process.

Example:

Ticket

pg_salt

string

required

Random string.

Example:

some random string

pg_sig

string

required

Request signature.

pg_currency

string

optional

The currency in which the amount is specified. Options: KZT

Example:

KZT

pg_check_url

string

optional

URL to check the possibility of payment. Called before the payment if supported by the payment system. If not specified

pg_result_url

string

optional

URL to report the result of the payment. Called after payment on success or failure. If not specified

pg_request_method

string

optional

Method for calling store scripts (Check URL)

Example:

POST

pg_success_url

string

optional

URL to which the user is sent in case of a successful payment (for online systems only).

pg_failure_url

string

optional

URL to which the user is sent in case of unsuccessful payment (for online systems only).

pg_success_url_method

string

optional

Method for the button submitted to confirm payment. Options: GET or POST. If selected

Example:

GET

pg_failure_url_method

string

optional

Method for the button submitted in case of payment failure. Options: GET or POST. If selected

Example:

GET

pg_state_url

string

optional

URL of the script on the merchant's website where the customer is redirected to wait for a response from the payment system.

Example:

http://site.kz/state

pg_state_url_method

string

optional

Method for state URL submission. Options: GET

Example:

GET

pg_site_url

string

optional

URL of the store's site to show the customer a link to return to the store after creating an invoice. Applies to offline payment systems (cash).

Example:

http://site.kz/return

pg_payment_system

string

optional

Identifier of the payment system. Passed only if the payment system is selected on the merchant's website. If not specified

Example:

EPAYWEBKZT

pg_lifetime

integer

optional

Time in seconds for payment completion. Default is 86400 (1 day). If the payment is not completed within this period

Example:

86400

pg_user_phone

string

optional

The user's phone number (starting with the country code) is required to identify the buyer. If not specified

Example:

77777777777

pg_user_contact_email

string

optional

User's contact email address. If specified

Example:

mail@customer.kz

pg_user_ip

string

optional

Client's IP address. It is necessary for the analysis of disputable situations in case of suspected fraud. The parameter can be omitted when transmitting information through the user's browser

Example:

127.0.0.1

pg_postpone_payment

integer

optional

Create a postpone payment if '1' is passed in this parameter. In this case

Example:

0

pg_language

string <ISO 639-1:2002>

optional

The language of the payment pages on the {{project}} site and (if possible) payment systems

Default:

ru

Examples:

ruenkzkguz

pg_testing_mode

integer

optional

Creating a payment in test mode.

Example:

1

pg_user_id

string

optional

User ID in the merchant system.

Example:

No65GFR755789T

pg_recurring_start

integer

optional

Flag

Example:

1

pg_recurring_lifetime

integer

optional

The time period during which the merchant expects to use the recurring payment profile. The minimum allowed value is 1 (1 month). Maximum allowable value: 156 (13 years old). In case of going beyond the boundary values

Example:

156

pg_receipt_positions[0][count]

integer

optional

Product quantity.

Example:

2

pg_receipt_positions[0][name]

string

optional

Product name.

Example:

Mouse pad

pg_receipt_positions[0][tax_type]

integer

optional

Tax type. Possible values: 0 - Without tax

Example:

0

pg_receipt_positions[0][price]

number

optional

Price per unit product.

Example:

1000

pg_param1

string

optional

Additional parameter 1

Example:

Additional information

pg_param2

string

optional

Additional parameter 2

Example:

Additional information

pg_param3

string

optional

Additional parameter 3

Example:

More info

pg_auto_clearing

integer

optional

If 1 clearing will occur immediately

Example:

1

pg_payment_method

string

optional

Method of payment. Possible values: wallet - Electronic money

Example:

mobile_commerce

pg_timeout_after_payment

integer

optional

Specifies the payment page closing time in seconds.

Example:

10

pg_generate_qr

boolean

optional

In case you want to receive a QR code with a link to the {{project}} payment form in base64 format.

Example:

1

pg_3ds_challenge

integer

optional

Determines the need to complete the Challenge Flow (1 - it is mandatory to conduct the Challenge Requested

Example:

0

pg_commission_discount

boolean

optional

If you want to use a discount on the commission

Example:

1

pg_commission_discount_fix

number

optional

To use a fixed discount amount.

Example:

0

pg_commission_discount_percentage

number

optional

To use a percentage discount.

Example:

0

pg_idempotency_key

string

optional

Idempotency key. Used to prevent duplicate request creation. A unique value within the merchant's scope; the same key cannot be used for different operations.

pg_loyalty_id

string

optional

Identifier in the loyalty system.

pg_loyalty_amount

number

optional

Amount of accrued units in the loyalty system.

pg_freedom_id

string

optional

User identifier in the Freedom ecosystem.

pg_template

string

optional

Payment page template. Options for the values of the pg_template field can be obtained from your manager after signing the contract.

>= 3 characters<= 100 characters

Request samples

Shell

JavaScript

Java

Swift

Go

PHP

Python

HTTP

C

C#

Objective-C

Ruby

OCaml

Dart

R

curl --location --request POST 'https://api.freedompay.kg/init_payment.php' \
--form 'pg_order_id="00102"' \
--form 'pg_merchant_id=""' \
--form 'pg_amount="10"' \
--form 'pg_description="Ticket"' \
--form 'pg_salt="some random string"' \
--form 'pg_sig=""' \
--form 'pg_currency="KZT"' \
--form 'pg_check_url=""' \
--form 'pg_result_url=""' \
--form 'pg_request_method="POST"' \
--form 'pg_success_url=""' \
--form 'pg_failure_url=""' \
--form 'pg_success_url_method="GET"' \
--form 'pg_failure_url_method="GET"' \
--form 'pg_state_url="http://site.kz/state"' \
--form 'pg_state_url_method="GET"' \
--form 'pg_site_url="http://site.kz/return"' \
--form 'pg_payment_system="EPAYWEBKZT"' \
--form 'pg_lifetime="86400"' \
--form 'pg_user_phone="77777777777"' \
--form 'pg_user_contact_email="mail@customer.kz"' \
--form 'pg_user_ip="127.0.0.1"' \
--form 'pg_postpone_payment="0"' \
--form 'pg_language=""' \
--form 'pg_testing_mode="1"' \
--form 'pg_user_id="No65GFR755789T"' \
--form 'pg_recurring_start="1"' \
--form 'pg_recurring_lifetime="156"' \
--form 'pg_receipt_positions[0][count]="2"' \
--form 'pg_receipt_positions[0][name]="Mouse pad"' \
--form 'pg_receipt_positions[0][tax_type]="0"' \
--form 'pg_receipt_positions[0][price]="1000"' \
--form 'pg_param1="Additional information"' \
--form 'pg_param2="Additional information"' \
--form 'pg_param3="More info"' \
--form 'pg_auto_clearing="1"' \
--form 'pg_payment_method="mobile_commerce"' \
--form 'pg_timeout_after_payment="10"' \
--form 'pg_generate_qr="1"' \
--form 'pg_3ds_challenge="0"' \
--form 'pg_commission_discount="1"' \
--form 'pg_commission_discount_fix="0"' \
--form 'pg_commission_discount_percentage="0"' \
--form 'pg_idempotency_key=""' \
--form 'pg_loyalty_id=""' \
--form 'pg_loyalty_amount=""' \
--form 'pg_freedom_id=""' \
--form 'pg_template=""'

Responses

🟢200Success

application/xml

Body

pg_status

string

required

Shows the result of the query

pg_payment_id

integer

required

The unique identifier of the payment transaction in {{project}}; serves as the key for all further work with the transaction.

pg_redirect_url

string

required

The URL to redirect the user to. It can be both on the site {{site}} and on the site of the payment system.

pg_redirect_url_type

string

required

The type of page to which the redirect occurs. Possible values:
need data - dialogue with the buyer to clarify the parameters: payment system, phone number, parameters required for this payment system;
payment system - page of the payment system website or a page with instructions for paying through this payment system. The page with instructions can be located both on the {{site}} site and on the merchant's site.

If the merchant receives a response with pg_redirect_url_type='need data', the merchant may not redirect the buyer to the received URL, but clarify missing parameters on your site. In this case, after specifying the parameters and re-requesting the creation of a payment transaction, a new transaction will be created.

pg_redirect_qr

string

required

URL to redirect the user as a QR code. Transmitted in base64 format.

pg_salt

string

required

Random string.

pg_sig

string

required

Request signature.

Example

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>7999007876</pg_payment_id>
    <pg_redirect_url>https://customer.freedompay.kz/pay.html?customer=200be02010c4f2a54260e5e798605691</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_salt>LNTZ7ciT1xjwzCFr</pg_salt>
    <pg_sig>760767e58ac9c2089e02471638b01111</pg_sig>
</response>

🟢200Error

🟢200Invalid Signature