Create payment (with CVC)

POST

https://api.freedompay.kz/v1/merchant/{{merchant_id}}/card/init

In this method, we initialize payment using a previously saved card

At this stage, the existence of the pg_card_token sent by the merchant is verified. If everything is correct, Freedom Pay Gateway responds with a payment_id

Interaction diagram

Status: success/error/pending

Merchant_API_V3-Saved card with CVC input (Pay).drawio.png

Request

Body Params multipart/form-data

pg_merchant_id

integer

required

Merchant ID in the system {{project}}.

pg_amount

number

required

Payment amount. Minimum 0.01.

>= 0.01<= 99999999

pg_currency

string

optional

Payment currency.

pg_order_id

string

required

Order ID in the merchant system.

Example:

550e8400-e29b-41d4-a716-446655440000

pg_user_id

string

required

User ID in the merchant system.

<= 50 characters

Example:

No65GFR755789T

Match pattern:

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

pg_card_id

number

optional

Card ID. (Deprecated). Required if no pg_card_token.

Example:

pg_card_token

string

required

Card token. Required if no pg_card_id.

<= 255 characters

Example:

ef741cfc-f85e-41a0-84e6-2ba964912182

pg_description

string

required

Order description.

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_user_email

string <email>

optional

Customer's email (specified during payment initialization).

pg_user_phone

number

optional

The user's phone number (starting with the country code). If not specified

Example:

77777777777

pg_user_ip

string

optional

Client's IP address. Necessary for the analysis of disputable situations in case of suspected fraud.

Example:

127.0.0.1

pg_result_url

string

optional

URL for message about payment result. Required if not set in the store settings.

<= 255 characters

Example:

https://site.com/result

pg_success_url

string

optional

URL to which the user is sent in case of successful payment. Required if not set in the store settings.

<= 255 characters

Example:

https://site.com/success

pg_failure_url

string

optional

URL to which the user is sent in case of unsuccessful payment. Required if not set in the store settings.

<= 255 characters

Example:

https://site.com/failure

pg_param1

string

optional

Additional Information.

<= 255 characters

Example:

Additional Information

pg_param2

string

optional

Additional Information.

<= 255 characters

Example:

Additional Information

pg_param3

string

optional

Additional Information.

<= 255 characters

Example:

Additional Information

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_salt

string

required

A 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 -g --request POST 'https://api.freedompay.kz/v1/merchant/{{merchant_id}}/card/init' \
--form 'pg_merchant_id=""' \
--form 'pg_amount=""' \
--form 'pg_currency=""' \
--form 'pg_order_id="550e8400-e29b-41d4-a716-446655440000"' \
--form 'pg_user_id="No65GFR755789T"' \
--form 'pg_card_id="56"' \
--form 'pg_card_token="ef741cfc-f85e-41a0-84e6-2ba964912182"' \
--form 'pg_description=""' \
--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_user_email=""' \
--form 'pg_user_phone="77777777777"' \
--form 'pg_user_ip="127.0.0.1"' \
--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_param1="Additional Information"' \
--form 'pg_param2="Additional Information"' \
--form 'pg_param3="Additional Information"' \
--form 'pg_idempotency_key="550e8400-e29b-41d4-a716-446655440000"' \
--form 'pg_loyalty_id=""' \
--form 'pg_loyalty_amount=""' \
--form 'pg_freedom_id=""' \
--form 'pg_salt=""' \
--form 'pg_sig=""'

Responses

🟢200Success

application/xml

Body

pg_status

string

required

Shows the result of the query
Status Description
ok — Request was successful,
error — Request was successful

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_merchant_id

integer

required

Merchant ID in the system {{project}}

pg_order_id

string

required

Order ID in the merchant system

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_order_id>12345</pg_payment_id>
    <pg_merchant_id>9970</pg_payment_id>
    <pg_salt>LNTZ7ciT1xjwzCFr</pg_salt>
    <pg_sig>760767e58ac9c2089e02471638b01111</pg_sig>
</response>

🟢200Error

🟢200Invalid Signature

Modified at 2025-04-18 10:20:51

Card token list

Confirm payment (with CVC)

Create payment (with CVC)

Interaction diagram#

Request

Request samples

Responses

Interaction diagram