Create payment

POST

https://api.freedompay.kz/init_payment.php

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

When redirecting to failure_url or success_url, the following parameters will be passed:

property	type	description
`pg_order_id`	string	Payment ID in the merchant system
`pg_payment_id`	int	Transaction ID
`pg_salt`	string	Random string
`pg_sig`	string	Request signature

When redirecting to success_url, the following parameters will be passed (frame only: if pg_payment_route equals frame):

property	type	description
`pg_order_id`	string	Payment ID in the merchant system
`pg_payment_id`	int	Transaction ID
`pg_salt`	string	Random string
`pg_sig`	string	Request signature

When redirecting to failure_url, the following parameters will be passed (frame only: if pg_payment_route equals frame):

property	type	description
`pg_order_id`	string	Payment ID in the merchant system
`pg_status`	string	Transaction ID
`pg_error_code`	string	Error code ID
`pg_error_description`	string	Text description of the error

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

optional

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

<= 50 characters

Example:

550e8400-e29b-41d4-a716-446655440000

pg_amount

number <float>

required

Payment amount in pg_currency

>= 0.01<= 99999999

pg_currency

string

optional

Currency in which the amount is specified. Default value is based on settings

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)

<= 1024 characters

pg_testing_mode

enum<integer>

optional

Creating a payment in test mode

Allowed values:

pg_lifetime

integer

optional

Time (in seconds) during which the payment must be completed. Default value is based on settings

>= 60<= 604800

pg_language

enum<string> <ISO 639-1:2002>

optional

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

Allowed values:

ruenkkkguz

Default:

pg_auto_clearing

enum<integer>

optional

If 1 clearing will occur immediately

Allowed values:

pg_recurring_start

enum<integer>

optional

Recurring start option

>= 0

Allowed values:

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

>= 1<= 156

pg_timeout_after_payment

integer

optional

Specifies the payment page closing time in seconds

>= 1

Default:

pg_3ds_challenge

enum<integer>

optional

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

Allowed values:

Default:

pg_user_id

string

optional

User ID in the merchant system

>= 1 characters<= 50 characters

Example:

No65GFR755789T

Match pattern:

^[a-zA-Z0-9_-]+$

pg_user_ip

string <ipv4>

optional

Client's IP address

Example:

127.0.0.1

pg_user_phone

number

optional

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

Example:

77777777777

pg_user_contact_email

string <email>

optional

User's contact email address

Example:

mail@customer.kz

pg_payment_method

enum<string>

optional

Displays payment methods on the payment page

Allowed values:

bankcardmobile_commerce

pg_request_method

enum<string>

optional

Method for calling store scripts (Check URL)

Allowed values:

GETPOSTXML

pg_check_url

string

optional

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

<= 255 characters

Example:

https://site.com/check

pg_result_url

string

optional

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

<= 255 characters

Example:

https://site.com/result

pg_success_url

string

optional

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

<= 255 characters

Example:

https://site.com/success

pg_failure_url

string

optional

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

<= 255 characters

Example:

https://site.com/failure

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)

<= 255 characters

Example:

http://site.kz/return

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

<= 255 characters

Example:

http://site.kz/state

pg_success_url_method

enum<string>

optional

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

Allowed values:

GETPOST

pg_failure_url_method

enum<string>

optional

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

Allowed values:

GETPOST

pg_state_url_method

enum<string>

optional

Method for state URL submission. Options: GET

Allowed values:

GETPOST

pg_receipt_positions[0][count]

integer

optional

Product quantity

>= 1

Example:

pg_receipt_positions[0][name]

string

optional

Product name

>= 1 characters

Example:

Mouse pad

pg_receipt_positions[0][tax_type]

enum<integer>

optional

Tax type. Possible values:
0 - Without tax,
1 - VAT 0%,
2 - VAT 12%,
3 - VAT 12/112,
4 - VAT 18%,
5 - VAT 18/118
6 - VAT 10%,
7 - VAT 10/110,
8 - VAT 20%,
9 - VAT 20/120.

Allowed values:

0123456789

pg_receipt_positions[0][price]

number

optional

Price per unit product

>= 0.01<= 99999999

pg_param1

string

optional

Additional parameter 1

<= 255 characters

Example:

Additional information

pg_param2

string

optional

Additional parameter 2

<= 255 characters

Example:

Additional information

pg_param3

string

optional

Additional parameter 3

<= 255 characters

Example:

Additional information

pg_extra_params

object

optional

payer_identificator

string

optional

Payer's IIN/BIN. Required field for processing government fee payments

payer_name

string

optional

Payer's Name. Depends on the payer's registration.Required field for processing government fee payments

beneficiar_name

string

optional

Benificiar's Full Name. Required field for processing government fee payments

pg_commission_discount

enum<integer>

optional

If you want to use a discount on the commission

Allowed values:

pg_commission_discount_fix

number

optional

To use a fixed discount amount

>= 1<= 99999999

pg_commission_discount_percentage

number

optional

To use a percentage discount

>= 1<= 100

pg_generate_qr

enum<integer>

optional

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

Allowed values:

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

<= 255 characters

Example:

550e8400-e29b-41d4-a716-446655440000

pg_loyalty_id

number

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

pg_payment_route

enum<string>

optional

Static value. To open a bank card only frame, if the frame is set

Allowed value:

frame

Example:

frame

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/init_payment.php' \
--form 'pg_merchant_id=""' \
--form 'pg_order_id="550e8400-e29b-41d4-a716-446655440000"' \
--form 'pg_amount=""' \
--form 'pg_currency=""' \
--form 'pg_description=""' \
--form 'pg_testing_mode=""' \
--form 'pg_lifetime=""' \
--form 'pg_language=""' \
--form 'pg_auto_clearing=""' \
--form 'pg_recurring_start=""' \
--form 'pg_recurring_lifetime=""' \
--form 'pg_timeout_after_payment=""' \
--form 'pg_3ds_challenge=""' \
--form 'pg_user_id="No65GFR755789T"' \
--form 'pg_user_ip="127.0.0.1"' \
--form 'pg_user_phone="77777777777"' \
--form 'pg_user_contact_email="mail@customer.kz"' \
--form 'pg_payment_method=""' \
--form 'pg_request_method=""' \
--form 'pg_check_url="https://site.com/check"' \
--form 'pg_result_url="https://site.com/result"' \
--form 'pg_success_url="https://site.com/success"' \
--form 'pg_failure_url="https://site.com/failure"' \
--form 'pg_site_url="http://site.kz/return"' \
--form 'pg_state_url="http://site.kz/state"' \
--form 'pg_success_url_method=""' \
--form 'pg_failure_url_method=""' \
--form 'pg_state_url_method=""' \
--form 'pg_receipt_positions[0][count]="2"' \
--form 'pg_receipt_positions[0][name]="Mouse pad"' \
--form 'pg_receipt_positions[0][tax_type]=""' \
--form 'pg_receipt_positions[0][price]=""' \
--form 'pg_param1="Additional information"' \
--form 'pg_param2="Additional information"' \
--form 'pg_param3="Additional information"' \
--form 'pg_extra_params=""' \
--form 'pg_commission_discount=""' \
--form 'pg_commission_discount_fix=""' \
--form 'pg_commission_discount_percentage=""' \
--form 'pg_generate_qr=""' \
--form 'pg_idempotency_key="550e8400-e29b-41d4-a716-446655440000"' \
--form 'pg_loyalty_id=""' \
--form 'pg_loyalty_amount=""' \
--form 'pg_freedom_id=""' \
--form 'pg_template=""' \
--form 'pg_payment_route="frame"' \
--form 'pg_salt=""' \
--form 'pg_sig=""'

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

Modified at 2025-05-02 11:41:11

Confirm payment

Any amount