Обзор

Данная документация описывает методы Gateway API. Сервис позволяет осуществить бесшовное подключение для большинства методов и параметров.

Структура документации:

API: методы api/* для регистрации заказов, проведения платежей, работы с токенами, регулярными платежами и балансами.
Wallet: методы api/wallet/* для работы с Кошельками: пополнение, выплаты, переводы между Кошельками и выписки.
GateWeb: методы gateweb/* для P2P‑операций и ряда административных операций.
OFD: методы ofd/* для получения фискальных чеков.

Каждый раздел содержит:

краткое назначение метода;
HTTP‑метод и полный URL;
тип запроса (формат данных запроса);
параметры запроса
параметры ответа
возможные примечания.

Формирование подписи

Все входящие запросы (кроме тех, где явно указано иное) и все ответы ПЦ содержат поле signature — цифровую подпись, рассчитываемую по единому алгоритму:

Из тела запроса (или тела ответа) убирается само поле signature.
Оставшиеся данные сериализуются в компактный канонический JSON: ключи сортируются лексикографически, без пробелов между элементами (json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False)).
К полученной строке слева приписывается секретный ключ (password) терминала: secret_key + json_string.
От полученной строки берётся SHA‑256, результат приводится к нижнему регистру в виде hex‑строки (64 символа).

import hashlib
import json


def signature(secret_key: str, data: dict) -> str:
    data_str = json.dumps(data, sort_keys=True, separators=(",", ":"), ensure_ascii=False)
    pre_sign_str = "".join([secret_key, data_str])

    sign = hashlib.sha256(pre_sign_str.encode()).hexdigest()

    return str(sign).lower()

Важно:

В подписи участвуют все поля запроса/ответа (включая необязательные, если они переданы), кроме самого поля signature.
Для входящих запросов data — это JSON‑тело запроса, дополненное query‑параметрами (для GET‑эндпоинтов, где тело отсутствует).
Сравнение подписи регистронезависимо (сервер приводит присланное значение к нижнему регистру перед сравнением).

Структура `payer` / `receiver`

Во многих методах данные Плательщика и/или Получателя передаются вложенным объектом payer и/или receiver. Оба объекта используют одну и ту же структуру полей — какие именно поля значимы для конкретного метода, указано в разделе «Структура запроса» этого метода.

Поле	Тип	Описание
`email`	`str`	Адрес электронной почты.
`phone`	`str`	Телефон в формате `7XXXXXXXXXX`.
`wallet_public_id`	`str`	Уникальный идентификатор Кошелька.
`public_id`	`str`	Идентификатор клиента на стороне ТСП.
`payment_mean_token`	`str`	Токен платёжного средства (карты или СБП).
`bank_name`	`str`	Наименование банка.
`bank_id`	`str`	Идентификатор банка из справочника участников СБП.
`first_name`	`str`	Имя.
`last_name`	`str`	Фамилия.
`middle_name`	`str`	Отчество.
`acc_number`	`str`	Номер счета.
`contract`	`str`	Номер договора.
`receipt_type`	`int`	Номер шаблона уведомления, отправляемого на email. По умолчанию используется первый (стандартный) шаблон.
`pan`	`str`	Номер карты.
`country`	`str`	Код страны.
`region`	`str`	Название региона (области, края).
`address`	`str`	Адрес. Общий формат: название улицы, номер дома, номер квартиры/офиса.
`is_notify`	`bool`	Признак необходимости отправки email-уведомления. Принимает `0`/`1` или `false`/`true`. (по умолчанию `false`)
`city`	`str`	Название населённого пункта (города, посёлка и т.д.).
`post_code`	`str`	Почтовый индекс (ZIP code).

Все поля необязательны на уровне структуры payer/receiver как таковой. Однако в ряде методов (api/wallet/*) wallet_public_id внутри payer и/или receiver обязателен для заполнения — это указано отдельно в разделе «Структура запроса» соответствующего метода.

Формат ошибок

Любая ошибка возвращается в едином формате:

{
    "error_code": "TERMINAL_NOT_FOUND",
    "technical_message": "Terminal not found",
    "timestamp": 1751976000,
    "details": null,
    "request_id": "b3b3c1f0-4b3a-4f3a-9b1a-1234567890ab"
}

Поле	Тип	Описание
`error_code`	`str`	Машиночитаемый код ошибки — см. таблицу ниже.
`technical_message`	`str \\| null`	Человекочитаемое описание ошибки.
`timestamp`	`int`	Unix-время формирования ответа (секунды).
`details`	`object \\| null`	Дополнительные данные об ошибке. Для ошибок валидации содержит `validation_errors` (см. ниже); в остальных случаях обычно `null`.
`request_id`	`str \\| null`	Идентификатор запроса для трассировки (значение заголовка `X-Request-ID`).

Для ошибок валидации (error_code = "VALIDATION_ERROR", HTTP 422) details.validation_errors содержит список всех невалидных полей запроса целиком, а не только первое найденное:

{
    "error_code": "VALIDATION_ERROR",
    "technical_message": "Validation error",
    "timestamp": 1751976000,
    "details": {
        "validation_errors": [
            {
                "field": "body.amount",
                "message": "Input should be a valid integer, unable to parse string as an integer",
                "type": "int_parsing"
            }
        ]
    },
    "request_id": "b3b3c1f0-4b3a-4f3a-9b1a-1234567890ab"
}

field — полный путь до поля через точку (например, body.customers_stock.shares.0.amount для ошибки во вложенном списке).

Коды ошибок

`error_code`	HTTP‑статус	Описание
`TERMINAL_INVALID`	400	Incorrect Terminal ID
`CURRENCY_INVALID`	400	Invalid currency
`AMOUNT_INVALID`	400	Invalid amount
`INVALID_PAYMENT_MEAN_TOKEN`	400	Invalid token
`WALLET_ID_NOT_FOUND`	400	ref not found
`NOT_ENOUGH_BALANCE`	400	Not enough money on ref balance
`OPERATION_INVALID`	400	Incorrect Operation ID
`PRECHECK_TX_INVALID`	400	Precheck is not OK
`EXTERNAL_SERVICE_ERROR`	400	Error communicating with external system
`BALANCE_LIMIT_REACHED`	400	Balance limit reached
`ONLY_WALLET_METHOD`	400	Only wallet method
`NO_REVERSIBLE_TX`	400	No reversible tx
`WALLET_INACTIVE`	400	Wallet inactive
`RECURRENT_INVALID`	400	Recurrent invalid
`PAYMENT_MEAN_NOT_SET`	400	Payment mean not set
`INVALID_TX_ACTION`	400	Invalid tx action
`INVALID_TOKEN_ACTION`	400	Invalid token action
`CRYPTOGRAM_INVALID`	400	Cryptogram decryption failed
`INVALID_TX_STATUS`	400	Invalid tx status
`SIGN_INVALID`	401	Invalid signature
`TERMINAL_NOT_FOUND`	404	Terminal not found
`ORDER_NOT_FOUND`	404	Incorrect Order ID
`TX_NOT_FOUND`	404	Operation not found
`PRECHECK_NOT_FOUND`	404	Precheck_id not found
`CUSTOMER_NOT_FOUND`	404	Customer not found
`RSA_KEY_NOT_FOUND`	404	RSA key not found or revoked
`DUPLICATE_UNIQUE_KEY`	409	Another request with unique key is in progress
`TX_CANCEL_NOT_ALLOWED`	409	Transaction cancel not allowed
`VALIDATION_ERROR`	422	Validation error (см. `details.validation_errors`)
`REQUIRED_FIELD_MISSING`	422	Missing required parameter
`REFERENCE_MISSING`	422	Missing reference
`REFERENCE_TOO_LONG`	422	Reference is too long
`ORDER_CLIENT_ID_DUPLICATE`	422	Order with client ID duplicate for terminal
`CURRENCY_MISSING`	422	Missing currency
`AMOUNT_MISSING`	422	Missing amount
`INTERNAL_ERROR`	500	Internal error

Дубликат `unique_key`

Отдельный случай — повторный запрос с уже использованным unique_key, пока исходная операция ещё обрабатывается. Он не следует общему формату ошибок выше: сервер возвращает HTTP 409 с данными исходной (дублируемой) операции:

{
    "duplicated_operation": {
        "unique_key": "test2",
        "tx_id": 449800,
        "tx_type": "PURCHASE_BY_QR",
        "tx_status": "COMPLETE",
        "order_id": 480413,
        "client_id": "721716fc-6837-4dbc-8308-37de445c30f0"
    },
    "code": "DUPLICATE_UNIQUE_KEY",
    "description": "Another request with unique key is in progress",
    "signature": "1a4f9c02e7b3d685f0a219c4e7b03d58f61ca2e9b7d0143f5a8c62e9d0b7415"
}