Документация

Авторизация

Все запросы авторизуются через заголовок Authorization: Bearer sk_live_…. Тестовые ключи начинаются с sk_test_ и работают только в песочнице.

Ошибки

API возвращает стандартные HTTP-коды. Тело ошибки содержит поля error и message. Для большинства ошибок в ответе есть request_id — приложите его, когда обращаетесь к поддержке.

Код	Значение	Описание
400	invalid_request	Поля заполнены некорректно — смотрите message.
401	unauthorized	Ключ невалиден или устарел.
409	order_id_conflict	order_id уже использовался — идемпотентность.
429	rate_limited	Превышен лимит. Заголовок Retry-After подскажет паузу.
5xx	server_error	Со стороны TraX. Запрос можно безопасно повторить с тем же order_id.

Создать платёж

POST /v2/payments

Создаёт новый QR-СБП платёж. В ответе вы получаете URL для отображения QR — покажите его пользователю любым удобным способом (картинкой, диплинком в банк-приложение или нативным шерингом).

Поле	Тип	Описание
amount REQUIRED	integer	Сумма платежа в копейках. Минимум — 100.
currency REQUIRED	string	Только RUB на текущий момент.
order_id REQUIRED	string	Ваш идентификатор заказа. Идемпотентный ключ — повторный запрос вернёт тот же платёж.
method	string	Метод оплаты. Сейчас доступен только sbp_qr.
webhook_url	string	URL для статусных вебхуков. По умолчанию — указанный в настройках.
expires_in	integer	Срок жизни QR в секундах. Дефолт 900, максимум 3600.
metadata	object	Произвольные ключ/значение, вернутся в вебхуке.

Ответ

Получить платёж

GET /v2/payments/{id}

Возвращает текущее состояние платежа. Используйте для ручных перепроверок — основной канал для статусов это вебхуки.

Статусы

Статус	Описание
pending	QR создан, ждём оплату клиента.
processing	Получили подтверждение от банка, идёт зачисление.
succeeded	Деньги у вас на счету. Финальный статус.
expired	Срок жизни QR истёк, оплата не поступила.
failed	Отказ банка или таймаут СБП. Финальный.

Webhooks

На ваш webhook_url прилетает POST на каждое изменение статуса платежа. Подпись находится в заголовке X-Trax-Signature — HMAC-SHA256 от тела запроса с вашим секретом подписи.

Возвращайте 2xx за 5 секунд. При любом другом ответе мы повторим доставку с экспоненциальной паузой — 8 попыток за 24 часа.

SDK

Готовые библиотеки для основных языков. Все SDK типизированы, поддерживают idle-retry и проверку подписи вебхуков из коробки.

Язык	Пакет	Версия
Node.js	@trax/sdk	2.4.1
Python	trax-sdk	2.4.0
PHP	trax/sdk	2.3.2
Go	github.com/trax-pay/sdk-go	v2.4.0