Мы используем cookie-файлы
Хорошо

Pay

Access point
Main server address:
https://api.freedompay.kz

Test server adreess:
https://test-api.freedompay.kz
The data is passed as parameters using the POST method. Responses to requests are presented in XML format

Making a payment

Request URL
POST https://api.freedompay.kz/g2g/payment

Test Request URL
POST https://test-api.freedompay.kz/g2g/payment

Request fields

Parameters for the effective operation of the SecureBox anti-fraud service
(These parameters may include parameters from other sections. For Securebox to work effectively, it is recommended to follow the validation recommendations and field examples from this section)
Optional parameters required when paying through tokenized PS's
Response parameters
Response parameters for a successful request:

In case of errors, there will be additional response parameters:
Note. If 3ds is installed on the card, a request must be made to the ACS server of the card issuer's bank.

On this page the client enters his 3ds password.
The server url can be obtained from the pg_3d_acsurl parameter.
Request parameters to the ACS server of the issuer's bank:

Response if successful:
Request for store result_url. Payment result

Example of a positive store response
Request

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=1' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_reference=111111111111' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'


Response

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>ok</pg_status>
    <pg_description>Заказ оплачен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

Example of a negative store response
Request

curl --location --request POST '{{result_url}}' \
--form 'pg_order_id=123456789' \
--form 'pg_payment_id=12345' \
--form 'pg_amount=500' \
--form 'pg_currency=KZT' \
--form 'pg_net_amount=482.5' \
--form 'pg_ps_amount=500' \
--form 'pg_ps_full_amount=500' \
--form 'pg_ps_currency=KZT' \
--form 'pg_description=Покупка в интернет магазине Site.kz' \
--form 'pg_result=0' \
--form 'pg_payment_date=2019-01-01 12:00:00' \
--form 'pg_can_reject=1' \
--form 'pg_user_phone=7077777777777' \
--form 'pg_user_contact_email=mail@customer.kz' \
--form 'pg_need_email_notification=1' \
--form 'pg_testing_mode=1' \
--form 'pg_captured=0' \
--form 'pg_reference=111111111111' \
--form 'pg_card_pan=5483-18XX-XXXX-0293' \
--form 'Параметры мерчанта=' \
--form 'pg_salt=some random string' \
--form 'pg_sig={{paybox_signature}}' \
--form 'pg_payment_method=bankcard'

Response

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_status>rejected</pg_status>
    <pg_description>Платеж отменен</pg_description>
    <pg_salt>random string</pg_salt>
    <pg_sig>ksdjrimzjedkljsujjemnjsuj</pg_sig>
</response>

After accepting payment from the customer or in case of failure to make the payment, FreedomPay calls the store's Result URL and sends information about the payment result to it using the Request Method.

Upon receiving this request, the merchant must take the necessary actions to transfer the product or service to the customer if the payment was successful. If pg_can_reject is 1 and the merchant cannot accept the payment (e.g. the reservation for tickets has expired), the merchant must respond with a rejected status and FreedomPay will cancel the payment. In this case, the pg_description field from the merchant's response is shown to the user as the reason for the rejection.

The Result URL on the merchant side must be publicly accessible, without authorization.

If the Merchant's server is unavailable at the time the Result URL is invoked, or if the response from the server was not status 200, FreedomPay will retry to invoke it every half hour for 2 hours, even if the pg_lifetime account expires.

If the first attempt to call the Result URL is unsuccessful, the payment is not canceled, and in subsequent calls to the Result URL, it does not allow the store to decline the payment.

The store must be prepared for the Result URL to be called repeatedly for the same payment. Responses to repeated invocations must match the original response, even if the transaction pg_lifetime has expired.

Response to result_url from the merchant
The rejected status can be returned by the merchant only if the pg_can_reject parameter was set to 1 in the incoming request from the gate, otherwise, regardless of the merchant's response, the payment will be considered complete. If the merchant rejected the payment (replied rejected), the buyer is redirected to Failure URL, otherwise - to Success URL.

  • ok - payment accepted
  • rejected - rejected payment if pg_can_reject is equal to 1.
  • error - error in data interpretation

Request URL
POST {{result_url}}
Making a payment with 3DSecure after receiving data from the ACS server

Request URL
POST https://api.freedompay.kz/g2g/paymentAcs

Test Request URL
POST https://test-api.freedompay.kz/g2g/paymentAcs

Request fields

Response parameters
Response parameters for a successful request:

In case of errors, there will be additional response parameters:
Non-acceptance payments
To use this parameter, you should contact your manager.

Method: This scenario is similar to Saved card with cvc input. But in the case when the card on which the payment is made is confirmed, the cvc is not requested from the user.

Approved cards are marked with the approved status in the list of cards.

In this scenario, a payment request can be sent without user interaction

Card payment initialization
Payment with a saved card takes place in two stages:

  • Payment initialization
  • Carrying out payment
Request URL
POST https://api.freedompay.kz/g2g/payment
Test Request URL

POST https://test-api.freedompay.kz/g2g/payment

Request fields

Response parameters
In case of errors, there will be additional response parameters:
Any amount method
If you want the payer to enter the payment amount himself, you must use this method.

When making a payment, the payer first gets to the form where he enters the amount of the payment. Then it is redirected to the payment page where the payment takes place.

Request URL
POST https://api.freedompay.kz/g2g/any_amount

Test Request URL
POST https://test-api.freedompay.kz/g2g/any_amount

Request fields

Response parameters
In case of errors, there will be additional response parameters:
Payment page

Request URL
POST https://api.freedompay.kz/g2g/payment_page

Test Request URL
POST https://test-api.freedompay.kz/g2g/payment_page

Request fields

Response parameters
In case of errors, there will be additional response parameters:
Google Pay

Google Pay™ is a fast and secure way for one-touch online purchases. A customer of the store can pay with any card saved in his Google account. For merchant this payment will be processed like a regular payment by card.

If the purchase is made from a mobile device supporting Google Pay, the customer will be asked to confirm the payment using a password, fingerprint or face recognition.

If the purchase is made from a device without the Google Pay app, the customer can select any saved card in his Google account and confirm payment by passing 3D Secure authentication.

All merchants must adhere to the Google Pay APIs Acceptable Use Policy and accept the terms defined in the Google Pay API Terms of Service
The principle of working with the service

By clicking on the Google Pay button, the user goes to the page where the payment methods saved in his Google account are indicated. This way he will be able to quickly choose the method of payment convenient for him.
Payment process:

  1. By clicking the Google Pay button, the user goes to a page with a list of available payment methods and selects the desired one.
  2. Google Pay securely transfers the token corresponding to the specified payment method to your site.
  3. Your site sends its server a token and other payment details.
  4. The server processes the data and transfers the token to the payment service provider.
Hosted Payments Page Integration
Instructions detailing how to integrate Google Pay™ into your Website using the Paybox Hosted Payments Page

Pre-requisites
Implementation Steps
Follow the instructions of your manager. A Google Pay button will be displayed by default on the Hosted Payments Page once Google Pay has been enabled on your account

Web Integration

Instructions detailing how to integrate Google Pay™ into your Website using Paybox as your gateway

Pre-requisites
  1. Read the Google Pay Web Brand Guidelines
  2. Follow Google Pay's [Deploy production environment guidelines](Follow Google Pay's Deploy production environment guidelines). In this step you will obtain a merchantID. By integrating Google Pay, you agree to Google's terms of service.
  3. Contact your manager to have Google Pay enabled on your account. You will be supplied a gatewayMerchantID.
Implementation Steps
Follow the instructions in the following Google guides to implement a Google Pay button in your app:
When setting up the tokenizationSpecification object, specify the following values for the gateway and gatewayMerchantId values:
gateway - freedompay
gatewayMerchantId - <your Google Merchant ID>

The Google Pay button will generate an encrypted token that you must then include in a request to the Paybox API to:
  • Create a purchase using the card in the Google Pay payload
  • Or tokenize the card details in the Google Pay payload
The following documentation outlines the format of the two API calls:
Supported authentication methods: PAN_ONLY and CRYPTOGRAM_3DS. Supported card networks are Visa and MasterCard.
There is no need to transfer the billing address.The payment token received from Google must be passed in the token parameter in string format. It must be transferred in the same form in which you received it from Google. The rest of the options are described below.

Payment via API

To work through the API, the company needs PCI DSS certification. During registration, you will be given the data that you will need to use when making a payment:
  • MerchantID – store ID
  • ClientID – client ID
  • ClientSecret – secret key
Request URL
POST https://api.freedompay.kz/g2g/payment
Test Request URL
POST https://test-api.freedompay.kz/g2g/payment

Request fields


{
    "pg_amount": "500",
    "pg_auto_clearing": "0",
    "pg_currency": "KZT",
    "pg_description": "Payment #1",
    "pg_merchant_id": "9970",
    "pg_order_id": "302911642",
    "pg_payment_method": "google_pay",
    "pg_tokenized_payment_data": "{"signature":"MEQCIG4rKsp0ldpV20ujIxji9KZRtMvbicCnDzgKCLZxvkmiAiAXuke7uzcdzRKq6sAifb4ST5dZjy/1lzd1Y566xLMIIg\u003d\u003d","intermediateSigningKey":{"signedKey":"{\"keyValue\":\"MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEJ9E0ixlcIPr5Pw0mJQaxmCF0ALdoSdtUp/Vn6ctWuNY0NdN0Tj9pO02NE+m5tdetboUfqP6s4ZwWNjZQXAJDKQ\\u003d\\u003d\",\"keyExpiration\":\"1672120937000\"}","signatures":["MEQCIH+zIK9y8EZpuEQ0Dw9xAEpC20IGmG0A2pZWkKmg1YezAiB02QD0qDIGisw+KjwLlFss0eK1yEXlYkgyOtJWmOweXA\u003d\u003d"]},"protocolVersion":"ECv2","signedMessage":"{\"encryptedMessage\":\"ygBdahs6ZSvmc6ip8OqaNrJOJgr7p+S6xALIMUodL83knnyoztbCm5Ok6ZqmHuzsD0Fs1JgWp5SexQrlHGbigwyNwLn4002/fwWPuFIykYH+aJMG9azcSn8GvRLiU+0AtuHZ9LzQQtsgMlFZTpTCIoBajWl/7xgHI6hy555JmT8Y8TgiY6jsYdjUD28FxOOFPUQEx3M4IsgjTaerXO8o5VYr7ymdoPWeWpPy/ZlT+RL4mwLiVn7bnqfXeUVS0e+Ogzb/lgAdRARPIwIbkcsquVRrKN66t8X15OhqPbxewk/xbD0A3IzKk8pDaLhNIoTwCa+7fuNT0xs13f/oZmzitRapHkBGNbH7/xKkbunianzUDM1blr2oH6JiOFJXPYyKOP+5tLI/Z5PrybK1A0j1TsdhOYiLCgZXKO+HOXmKiUUBtHJAr1mW6v0Y0eyXghhFiEqsH4PvTgHCWkLz1yP22UoH3E0oiOXcN3xwNIzLVX+ck75AknNdtL2CIWcw2Pcz10a5x28r1P3o262PKhEjIstLrPIj/nHhd2jA3cm/gyRNV0uoGZS9pyljzhDGdDpN6NmrczMEdW1HkRclyNaPWGIdw/xKUiVhsmqYmR7rsbIbIh/PaM5fEYANJMZBH8A3Lbe5gUTr1mAR\",\"ephemeralPublicKey\":\"BIiEqj+GZlQREoaVEKLrmN3Lf9S0xgWE+qYNGlkKOib7w6XYl5IbiFMIsGYn+xD8N2p5rE4+SMwpcueS4ZZhX+w\\u003d\",\"tag\":\"qjQlnu+6vq72q4FHlylj+IV9Q4fFpox2m4KqlUixeII\\u003d\"}"}"
    "pg_salt": "7fe2b875f72542e3b3704288e92661cd",
    "pg_user_ip": "95.83.118.177",
    "pg_sig": "bfe9284b46b020c8528e4191c58f2222"
}

Response parameters no 3DS

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_payment_id>685462745</pg_payment_id>
    <pg_status>ok</pg_status>
    <pg_3ds>0</pg_3ds>
    <pg_auth_code>116658</pg_auth_code>
    <pg_reference>482481615785</pg_reference>
    <pg_salt>ntb4oJhg46xnJqlU</pg_salt>
    <pg_sig>7828753fe55bea789974fcd233197669</pg_sig>
</response>

Response parameters 3DS
If you receive this response go to Making a payment with 3DSecure


<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_payment_id>685462745</pg_payment_id>
    <pg_status>ok</pg_status>
    <pg_3ds>1</pg_3ds>
    <pg_3d_md>YTE5OThjNTEtOGNjZi00MDQ1LWE3M2ItZTcxMjI0NjkzMTVl</pg_3d_md>
    <pg_3d_acsurl>https://secure.freedompay.kz/v1/v2_3ds_way4/user/3ds-page/561a9397-81ed-480a-a777-21b38dc02de9</pg_3d_acsurl>
    <pg_3d_pareq>eyJtZXNzYWdlVHlwZSI6IkNSZXEiLCJtZXNzYWdlVmVyc2lvbiI6IjIuMS4wIiwidGhyZWVEU1NlcnZlclRyYW5zSUQiOiJhMTk5OGM1MS04Y2NmLTQwNDUtYTczYi1lNzEyMjQ2OTMxNWUiLCJhY3NUcmFuc0lEIjoiZDk1OTM3NGYtZDE0Yi00MjEzLTkwMmItN2Q1YmYwOWFkYTdlIiwiY2hhbGxlbmdlV2luZG93U2l6ZSI6IjA1In0</pg_3d_pareq>
    <pg_salt>GGADkDBS8eLFtQtL</pg_salt>
    <pg_sig>7b1da0a4639625f2686bd7084d09a641</pg_sig>
</response>

Standard integration (only for web-sites)

Standard integration refers to hosting checkout page with Google Pay on merchant's website. To make a payment, you need to receive a payment token from Google Pay and transfer it to the freedompay payment gateway.

Before you begin the integration, make sure that:

  • You have read with Google Pay API Overview;
  • Your web-page supports HTTPS protocol and has a domain-validated TLS certificate;
  • One of the following web browsers is being used: Google Chrome, Mozilla Firefox, Apple Safari, Microsoft Edge, Opera, or UCWeb UC.
Upon completion of the integration, you must ensure that:

Test cards