Card

POST

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

This method is used for processing payments using a card

At this stage, the payer provides card details to execute the transaction

The payment can follow two scenarios: with 3D Secure (3DS) or without it

Interaction diagram for non3ds payment

Status: success/error/pending

Interaction diagram for 3ds payment

Status: success/error

Status: pending

G2G_API_V3-pending Payment 3DS. case 2.drawio.png

Request

Body Params multipart/form-data

pg_merchant_id

number

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

Payment mode
0 - production, 1 - test. If the mode is not specified, then the mode set in the shop settings is taken

>= 0<= 1

pg_user_id

string

optional

User ID in the merchant's system
(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)

Example:

No65GFR755789T

pg_user_email

string <email>

optional

Payer's email or email linked (specified during registration) to the personal account ID or wallet number of the payer.
(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)

Example:

example@site.com.

pg_user_phone

string

optional

Payer's phone number or phone number linked (specified during registration) to the personal account ID or wallet number of the payer.
Digits without spaces, plus signs, or parentheses
(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_card_pan

string

required

Card number

>= 13 characters<= 20 characters

pg_card_cvc

integer

required

CVC/CVC2/CVV card password

pg_card_year

integer

required

Card expiration year

pg_card_month

integer

required

Card expiration month

pg_card_name

string

required

Name and surname of card holders

Example:

John Doe

pg_auto_clearing

boolean

optional

Clearing type (0 or 1)
1 - automatic write-off after successful authorization, 0 - write-off by launching the clearing method

pg_3ds_challenge

boolean

optional

Determines the need to complete the Challenge Flow
(1 - it is mandatory to conduct the Challenge Requested, 0 or empty - the method is determined by the issuer) the issuing bank can ignore this parameter and make a payment according to its own Challenge Flow

pg_exchange_params

object

optional

Exchange rate parameters passed when a fixed rate needs to be used

rate

string

optional

The exchange rate provided by the merchant. Payments will be converted using this exact rate.

rates_code

string

optional

Unique currency rate source identifier. Contact your account manager to obtain this code.

ex_date

string

optional

Historical date for applying the exchange rate. If empty, current date applies.

pg_param1

string

optional

Additional parameter 1

pg_param2

string

optional

Additional parameter 2

pg_param3

string

optional

Additional parameter 3

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' \
--form 'pg_merchant_id=""' \
--form 'pg_order_id=""' \
--form 'pg_amount=""' \
--form 'pg_currency=""' \
--form 'pg_description=""' \
--form 'pg_testing_mode=""' \
--form 'pg_user_id=""' \
--form 'pg_user_email=""' \
--form 'pg_user_phone=""' \
--form 'pg_card_pan=""' \
--form 'pg_card_cvc=""' \
--form 'pg_card_year=""' \
--form 'pg_card_month=""' \
--form 'pg_card_name="John Doe"' \
--form 'pg_auto_clearing=""' \
--form 'pg_3ds_challenge=""' \
--form 'pg_exchange_params=""' \
--form 'pg_param1=""' \
--form 'pg_param2=""' \
--form 'pg_param3=""' \
--form 'pg_salt=""' \
--form 'pg_sig=""'

Responses

🟢200Success

application/xml

Body

pg_payment_id

string

required

Transaction ID

pg_status

string

required

Request status

pg_3ds

boolean

required

Flag indicating the need for a 3DS request.
1 – 3DS is required, 0 - not required

pg_3d_md

string

optional

Card Issuer Bank Url for 3ds Validation

pg_3d_acsurl

string

optional

Parameter for request 3ds

pg_3d_pareq

string

optional

Parameter for request 3ds

pg_auth_code

string

required

Payment authorization code from the bank

pg_reference

string

required

Transaction reference

pg_datetime

string

required

Date and time of the request

pg_salt

string

required

Random string

pg_sig

string

required

Request digital signature

pg_card_id

integer

optional

Saved card ID for next payments (Deprecated)

pg_card_token_to

string

optional

Saved card token for next payments

pg_recurring_profile

integer

optional

Recurring profile ID (if the payment request parameter pg_recurring_start = 1 was specified)

Example

<?xml version="1.0" encoding="utf-8"?>
<response>
    <pg_payment_id>7777777777</pg_payment_id>
    <pg_status>ok</pg_status>
    <pg_3ds>0</pg_3ds>
    <pg_auth_code/>
    <pg_reference/>
    <pg_datetime>2024-09-02T12:19:01+00:00</pg_datetime>
    <pg_salt>YtfwCGiBHsFLpYGk</pg_salt>
    <pg_sig>ccee466c01c2332d8a065d6108fd686b</pg_sig>
</response>

🟢200Process

🟢200Error

🟢200Invalid Signature

Any amount

3DSecure

Card

Interaction diagram for non3ds payment#

Interaction diagram for 3ds payment#

Request

Request samples

Responses

Interaction diagram for non3ds payment

Interaction diagram for 3ds payment