Freedom Pay

read payment

POST

https://api.freedompay.kz/v5/g2g/read

Request

Header Params

string

required

Indicates the media types that the client is able to understand from the server response.

Default:

application/json

Content-Type

string

required

Specifies the media type of the resource being sent to the server.

X-JWS-Signature

string

required

Request signature.

Example:

eyJhbGciOiJSUzI1NiIsImtpZCI6IjEyMzQ1NiJ9.eyJpc3MiOiJleGFtcGxlLmNvbSIsInN1YiI6InVzZXIxMjMiLCJhdWQiOiJhcGkuZXhhbXBsZS5jb20iLCJleHAiOjE2MzAwMDAwMDAsImlhdCI6MTYyOTk5NjQwMH0.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

X-Action

string

required

Invoked method.
If the same request_id is sent more than once, the API guarantees idempotent behavior and returns the original response.

Default:

gateway.payment.status

X-Request-Id

string

required

Unique request ID (UUID).

Example:

01978cb8-60f4-7b04-8b8d-8075a11d56a3

Body Params application/json

string

Required if "order_id" is not provided

required

Payment ID (UUID).

Example:

01978c2f-79bc-72de-85f1-2ca183462dc5

order_id

string

Required if "id" is not provided

optional

Order number in the merchant's system.

Example:

12345

Example

{
    "id": "01907dac-a93d-776e-b475-cba6a54a4888",
    "order_id": "1234"
}

Request samples

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'https://api.freedompay.kz/v5/g2g/read' \
--header 'Accept;' \
--header 'X-JWS-Signature;' \
--header 'X-Action;' \
--header 'X-Request-Id;' \
--header 'Content-Type: application/json' \
--data-raw '{
    "id": "01907dac-a93d-776e-b475-cba6a54a4888",
    "order_id": "1234"
}'

Responses

🟢200OK

application/json

Headers

x-request-id

string

required

Request ID (UUID), equals X-Request-Id from request headers.

Example:

01978c2b-f191-7b56-92f8-20c7c401d1fc

x-request-status

string

required

Request status.

Example:

success

x-datetime

string

required

Request datetime.

Example:

2025-06-20T07:13:31Z

Body

string <uuid>

required

Unique identifier of the payment generated by the gateway.

Example:

01978d0e-b956-7ea2-9a42-32cff1f44ede

order_id

string <char>

required

Merchant’s order reference that links the payment to the merchant system.

Example:

12345

parent_id

string <uuid>

required

UUID of the parent payment

Example:

01978d27-fdb1-7fd1-8812-ce7a83414c72

status

string <char>

required

Current processing state of the payment (approved, success, error, etc.).

Examples:

processsuccessapprovedreversederror

amount

number <float>

required

Transaction amount in the original currency units (e.g., “103” = 103 KZT).

Example:

100

created_at

string <date-time>

required

Timestamp when the payment record was created on the gateway.

Example:

2025-06-20T07:13:31.068188524Z

3ds

object

required

Object containing information for the client’s 3DS authentication.

flow_type

string

required

Details of 3DS flow used (Challenge or Frictionless).

Examples:

acs_url

string

required

URL to which the client should be redirected via POST. The request body must include the parameter TermUrl, which is the URL the client will be returned to after 3DS completion.

Example:

https://acs.com/something

from

object

required

recurrent

object

optional

card

object

optional

Card token

clearing

object

required

cleared

boolean

required

Payment clearing status

amount

number <float>

required

Amount cleared

Example:

100

additional

object

optional

approval_code

string

required

Payment approval code sent by the issuing bank

reference

string

required

Unique bank transaction identifier assigned by the bank (RRN)

intreference

string

required

Unique bank transaction internal identifier assigned by the bank

refund_payments

array [object {3}]

optional

Array containing information about refund payments

string

required

UUID of the refund payment

amount

integer | number

required

Amount of the refund payment

status

string

required

Status of the refund payment

reverse_payments

array [object {3}]

optional

Array containing information about reversed (canceled) payments

string

required

UUID of the reversed payment

amount

integer

required

Amount of the reversed payment

status

string

required

Status of the reversed payment

Since the API operates asynchronously, whenever the payment status is returned as process, you must continuously query the payment status until you receive a final status such as approved or success.

{
    "id": "01978d0e-b956-7ea2-9a42-32cff1f44ede",
    "status": "approved",
    "amount": 100,
    "created_at": "2025-06-20T07:13:31.068188524Z",
    "order_id": "1234",
    "clearing": {
        "cleared": false,
        "amount": 0
    },
    "from": {
        "card": {
            "token": "01978d11-669e-7dd1-bf1b-75a12bf57ca9",
            "brand": "VI"
        }
    },
    "additional": {
        "approval_code": "95F69T",
        "reference": "1234567891234",
        "intreference": "AC1BFED11052BFAC"
    },
    "3ds": {
        "acs_url": "",
        "flow_type": "F"
    }
}

Modified at 2025-06-26 13:34:50

create payment

read request