Overview

Introduction

Gateway Sync API (API v3) processes a request and returns the result in the same response.

URL: {domain}/g2g/<method>, for example {domain}/g2g/payment.

HTTP method: POST only. GET requests are rejected with 405.

Every request and every response is signed: pg_salt + pg_sig (see below).

Request format

The request body can be sent in any of these formats:

Content-Type	Nested parameters (for example `pg_receipt_positions`)
`application/json`	JSON array `[{…}, {…}]` or JSON object with keys `"0"`, `"1"`, …
`application/x-www-form-urlencoded`	`pg_receipt_positions[0][name]=value`
`multipart/form-data`	`pg_receipt_positions[0][name]=value`
XML in the `pg_xml` parameter (`application/x-www-form-urlencoded`)	not supported: send only flat parameters

In JSON, pass all values as strings, for example "pg_amount": "100.50".
A JSON number is converted before the signature check (100.50 becomes 100.5), so a signature calculated from the original value does not match and the API returns 1100.
Exception: in status_v2, pass pg_payment_id as a number.

XML example (the pg_xml value):

<?xml version="1.0" encoding="utf-8"?>
<request>
  <pg_merchant_id>12345</pg_merchant_id>
  <pg_order_id>order_1001</pg_order_id>
  <pg_amount>100</pg_amount>
  <pg_salt>a1b2c3d4</pg_salt>
  <pg_sig>…</pg_sig>
</request>

Response format

The response body is XML (Content-Type: text/xml) with the root element <response>.

pg_status — result of the request: ok or error. Some methods also return intermediate statuses; see the method description.

On error: pg_error_code (numeric code) and pg_error_description (text).

The response is signed with pg_salt and pg_sig by the same rules as the request. Check the signature before using the response.

Validation errors.
If a parameter is missing or has an invalid value, the API returns pg_status error with code 94031 (code 11005 for pg_amount).
The HTTP status is 200; the response is signed.
pg_error_description names the parameter.

Signature errors.
If pg_sig is missing or invalid, the API returns code 1100.
If pg_merchant_id is not found, the API returns code 1101.
These responses may come without pg_salt and pg_sig.

Signature formation

To build pg_sig, concatenate with the separator ;:

The method name — the last segment of the URL path: payment, clearing, status_v2, p2p2nonreg and so on.

The values of all request parameters except pg_sig, sorted by parameter name in alphabetical order. pg_salt (a random string of Latin letters and digits) takes part like any other parameter.

The secret key of the merchant.

Calculate MD5 of the resulting string and pass it in pg_sig as 32 lowercase hexadecimal characters.
Any additional parameters sent in the request also take part in the signature.

Secret key. The merchant has two keys:

Key	Methods
Payment key	all methods except the ones below
Payout key	`p2p2nonreg`, `to_iban`, `reg2reg`, `payout_status2`, `balance_status`

Nested parameters (JSON and form formats) are expanded: each nested value takes part in the signature in the position of its parent parameter, nested values are ordered the same way. Use the code below — it handles nesting.

Response signature is calculated by the same rules with the same method name and key: take all fields of <response> except pg_sig.

Example

Request to {domain}/g2g/payment, secret key test_secret_key:

{
  "pg_merchant_id": "12345",
  "pg_order_id": "order_1001",
  "pg_amount": "100",
  "pg_currency": "KZT",
  "pg_description": "Order #1001",
  "pg_card_name": "IVAN IVANOV",
  "pg_card_pan": "4716047261941981",
  "pg_card_cvc": "123",
  "pg_card_month": "12",
  "pg_card_year": "30",
  "pg_user_phone": "77777777777",
  "pg_user_email": "user@example.com",
  "pg_salt": "a1b2c3d4",
  "pg_sig": "b7ccbf6b20dc8125c70aa4e21617a2c0"
}

String to sign (parameters sorted by name: pg_amount, pg_card_cvc, pg_card_month, pg_card_name, pg_card_pan, pg_card_year, pg_currency, pg_description, pg_merchant_id, pg_order_id, pg_salt, pg_user_email, pg_user_phone):

payment;100;123;12;IVAN IVANOV;4716047261941981;30;KZT;Order #1001;12345;order_1001;a1b2c3d4;user@example.com;77777777777;test_secret_key

pg_sig = MD5 of this string = b7ccbf6b20dc8125c70aa4e21617a2c0

Python

PHP

For the full list of pg_error_code values, see Error codes.

Introduction#

Request format#

Response format#

Signature formation#

Example#

Python#

PHP#

Introduction

Request format

Response format

Signature formation

Example

Python

PHP