Create payment - Freedom Pay

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

pg_template_params is used to control the appearance and behavior of the payment page. Parameters are passed as part of the init_payment request and affect frontend rendering. Required if customization is used

Recurring payments are repeat payments where a recurring profile is created during the first payment. Subsequent payments are made according to this profile.

To create a profile, the following parameters are passed in init_payment:
pg_recurring_start — profile creation
pg_recurring_lifetime — validity period

If pg_recurring_lifetime exceeds the card's expiration date, the profile remains active until the card expires.

The profile number (pg_recurring_profile_id) is passed in the Result URL.

It is also supported for Apple Pay and Google Pay.

For connection, please contact the manager.

Status: success/error/pending

Request Code Samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.freedompay.kz/init_payment' \
--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_payment_route="frame"' \
--form 'pg_salt=""' \
--form 'pg_sig=""' \
--form 'pg_template=""' \
--form 'pg_template_params[applepay]=""' \
--form 'pg_template_params[googlepay]=""' \
--form 'pg_template_params[can_save_card]=""' \
--form 'pg_template_params[css_override]=""' \
--form 'pg_template_params[show_details]=""' \
--form 'pg_template_params[freedom_loyalty]=""' \
--form 'pg_template_params [show_email]=""' \
--form 'pg_template_params [show_phone]=""' \
--form 'pg_template_params [show_freedom_logo]=""' \
--form 'pg_template_params [theme]=""'

Responses

🟢200Success

application/xml

Body

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