Create payment

POST

https://api.freedompay.kz/g2g/payment_page/

There are two options for using the method:

direct data transfer from the merchant to FreedomPay

data transfer via the user's browser to FreedomPay

When directly transferring data from the merchant to FreedomPay, the merchant must send data to init_payment.php.
When transferring data via the user's browser to FreedomPay, the merchant must redirect the user with the data to payment.php.

You can transfer arbitrary additional parameters whose names do not begin with pg_. All these parameters will be transferred to pg_check_url and pg_result_url.
The names of additional merchant parameters must be unique.

After receiving the pg_redirect_url parameter, the user is redirected to the payment page, where the payer completes the payment.

If successful, the user will be redirected to the payment page.

If the merchant has not transferred all the parameters necessary to create a payment transaction (payment system, user's phone number and parameters necessary for the selected payment system), they are requested from the user on the freedompay.kz website.

Frame is an embeddable HTML element that loads page content from the Freedom Pay Gateway. It is used to display the payment form (e.g., fields for entering the card number and CVV code) directly on the merchant's page.
To invoke the Frame method, the parameter pg_payment_route = frame must be included in the request to the Freedom Pay Gateway.
To use this method, you should contact your manager.

Interaction diagram

Status: success/error/pending

Request

Body Params multipart/form-data

pg_merchant_id

integer

required

Merchant ID in {{project}}
Issued upon connection

pg_order_id

string

required

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

pg_amount

number

required

Payment amount in pg_currency

>= 0.01

pg_currency

string

optional

Currency in which the amount is specified

pg_description

string

required

Payment description
(These parameters may include parameters from other sections. For the effective operation of SecureBox, it is recommended to follow the validation guidelines and field examples from this section)

pg_testing_mode

integer

optional

Creating a payment in test mode

pg_lifetime

integer

optional

Time (in seconds) during which the payment must be completed

>= 300<= 604800

Default:

86400

pg_language

string <ISO 639-1:2002>

optional

The language of the payment page can be synchronized with the language of your application or website user

Default:

Examples:

ruenkzkguz

pg_user_id

string

optional

User ID in the merchant system

pg_user_ip

string

optional

Client's IP address

pg_user_phone

string

optional

The user's phone number (starting with the country code)

pg_user_contact_email

string

optional

User's contact email address

pg_payment_method

string

optional

Payment method

pg_request_method

string

optional

GET

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_success_url

string

optional

URL to which the user is sent in case of a successful payment

pg_failure_url

string

optional

URL to which the user is sent in case of unsuccessful payment

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

pg_success_url_method

string

optional

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

pg_failure_url_method

string

optional

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

pg_param1

string

optional

Additional parameter 1

pg_param2

string

optional

Additional parameter 2

pg_param3

string

optional

Additional parameter 3

pg_generate_qr

boolean

optional

Generate QR code with a link to the {{project}} payment form in base64 format

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_salt

string

required

Random string consisting of arbitrary numbers and Latin letters

pg_sig

string

required

Request signature

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.freedompay.kz/g2g/payment_page/' \
--form 'pg_merchant_id=""' \
--form 'pg_order_id=""' \
--form 'pg_amount=""' \
--form 'pg_currency=""' \
--form 'pg_description=""' \
--form 'pg_testing_mode=""' \
--form 'pg_lifetime=""' \
--form 'pg_language=""' \
--form 'pg_user_id=""' \
--form 'pg_user_ip=""' \
--form 'pg_user_phone=""' \
--form 'pg_user_contact_email=""' \
--form 'pg_payment_method=""' \
--form 'pg_request_method=""' \
--form 'pg_check_url=""' \
--form 'pg_result_url=""' \
--form 'pg_success_url=""' \
--form 'pg_failure_url=""' \
--form 'pg_site_url=""' \
--form 'pg_success_url_method=""' \
--form 'pg_failure_url_method=""' \
--form 'pg_param1=""' \
--form 'pg_param2=""' \
--form 'pg_param3=""' \
--form 'pg_generate_qr=""' \
--form 'pg_idempotency_key=""' \
--form 'pg_loyalty_id=""' \
--form 'pg_loyalty_amount=""' \
--form 'pg_freedom_id=""' \
--form 'pg_salt=""' \
--form 'pg_sig=""'

Responses

🟢200Success

application/xml

Body

pg_payment_id

integer

required

Payment ID

pg_status

string

required

pg_redirect_url

string

required

pg_redirect_url_type

string

required

pg_redirect_qr

string

optional

pg_salt

string

required

pg_sig

string

required

Example

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_payment_id>123456</pg_payment_id>
    <pg_redirect_url>https://customer.freedompay.kz/</pg_redirect_url>
    <pg_redirect_url_type>need data</pg_redirect_url_type>
    <pg_redirect_qr>data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAUA...</pg_redirect_qr>
    <pg_salt>some random string</pg_salt>
    <pg_sig>signature-abc123</pg_sig>
</response>

🟢200Invalid Signature

Modified at 2025-03-03 07:41:50

Overview

Any amount

Create payment

Interaction diagram#

Request

Request samples

Responses

Interaction diagram