Freedom Pay
  1. Purchase
Freedom Pay
  • Overview
  • Gateway API
    • Overview
    • Sync API
      • Overview
      • Purchase
        • Overview
        • Create payment
        • Any amount
        • Card
        • 3DSecure
        • Cancel
        • Clearing
        • Refund
        • Status
      • Payout
        • Overview
        • Card
        • IBAN
        • Balance
        • Status
      • Transfer
        • Overview
        • Card
        • 3DSecure
        • Rates
        • Status
      • Card
        • Overview
        • Add
        • 3DSecure
        • List
        • Remove
        • Status
      • Token
        • Overview
        • Token Pay
        • Apple Pay
        • Google Pay
        • Token Payout
        • Status
    • Async API
      • Overview
      • create
        • create payment
        • create payment recurrent
      • read
        • read payment
        • read request
      • edit
        • edit payment.refund
        • edit payment.reverse
        • edit payment.clearing
      • delete
  • Merchant API
    • Overview
    • Purchase
      • Overview
      • Checkout
      • Card token
        • Overview
        • Tokenize card
        • Delete token
        • Card token list
        • Create payment (with CVC)
        • Confirm payment (with CVC)
        • Create payment
        • Confirm payment
      • Create payment
        POST
      • Any amount
        POST
      • Cancel payment
        POST
      • Clearing
        POST
      • Refund payment
        POST
      • Status
        POST
    • Payout
      • Overview
      • Card token
        • Tokenize card
        • Delete token
        • Card token list
        • Create payment
      • Create payment
      • IBAN
      • Balance status
      • Status by order_id
      • Status by Payment ID
      • Status
    • Mobile balance
      • Overview
      • Init
      • Pay
      • Approve
      • Resend code
      • Status
    • Invoice
      • Overview
      • Init
      • Info
      • Pay
      • Status
    • SDK
      • JS SDK
      • Google Pay
      • Freedom QR
        • Reader SDK (Android)
        • Provider SDK (Android)
      • Payment SDK
        • iOS
        • Android
    • CMS
      • Overview
      • Get Merchant ID and key
      • WordPress
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
        • Update
      • Tilda
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
      • InSales
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
      • Ecwid
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
      • Bitrix
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
      • PrestaShop
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
      • OpenCart
        • Overview
        • Installation
        • Configuration
        • Test
        • Live payments
    • Redirect back
      POST
    • Result notify
      POST
    • Payout notify
      POST
    • Check request
      POST
  • Card API
    • Overview
    • Payment Cards
      • Overview
      • Dictionaries
      • Bulk issue
      • Issue card
      • Issue plastic card
      • Activate card
      • Block card
      • Unblock card
      • Set PIN
      • Reset PIN counter
      • Close card
      • Update client
      • Card info
      • Balance
      • Secret data
      • Secret data (version 2)
      • Statement
      • Statement extended
      • Create client
      • Edit client
      • Сards' list
      • Request' status
      • Create transaction
      • Clearing transaction
      • Refund transaction
      • Transaction request' status
      • Transaction info
    • Gift Cards
      • Overview
      • List
      • Issue
      • Confirm
      • Resend
      • Resend code
      • Status
  • Partner API
    • Rates
      • Overview
      • Rates
    • Products
      • Overview
      • Dictionaries
      • Add client with product
      • Request status
    • E-Money
      • Overview
      • Add
      • Owner identification
      • Info
      • Close
      • Block
      • Balance
      • Statement
      • Request Status
    • Freedom ID
      • Overview
      • Design
      • iOS SDK
      • Android SDK
      • OAuth2
        • Authorization link
        • Token exchange
        • Token refresh
        • User info
        • Request profile
        • Get profile status
        • Create user
        • Update user
      • OIDC
        • Authorization endpoint
        • Token exchange
        • Userinfo
      • Error codes
      • Examples
        • Keycloak
    • Transfer
      • Overview
      • Get token
      • Refresh token
      • Get agents
      • Fees
      • Create person
      • Create business
      • Create transfer
      • Print application
      • Confirm
      • Search
      • Payout
      • Payout confirm
      • Cancel
      • Get person info
      • Get business info
      • Status
      • Info
    • Device ID
      • Android SDK
      • iOS SDK
  1. Purchase

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:
propertytypedescription
pg_order_idstringPayment ID in the merchant system
pg_payment_idintTransaction ID
pg_saltstringRandom string
pg_sigstringRequest signature
When redirecting to success_url, the following parameters will be passed (frame only: if pg_payment_route equals frame):
propertytypedescription
pg_order_idstringPayment ID in the merchant system
pg_payment_idintTransaction ID
pg_saltstringRandom string
pg_sigstringRequest signature
When redirecting to failure_url, the following parameters will be passed (frame only: if pg_payment_route equals frame):
propertytypedescription
pg_order_idstringPayment ID in the merchant system
pg_statusstringTransaction ID
pg_error_codestringError code ID
pg_error_descriptionstringText description of the error
Status: success/error/pending
Merchant_API_V3-Payment page.drawio.png

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:
01
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:
ru
pg_auto_clearing
enum<integer> 
optional
If 1 clearing will occur immediately
Allowed values:
01
pg_recurring_start
enum<integer> 
optional
Recurring start option
>= 0
Allowed values:
01
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:
10
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:
01
Default:
0
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:
2
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:
01
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:
01
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
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
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
Previous
Confirm payment
Next
Any amount