Начало работы

Добро пожаловать в документацию WinWallet Merchant API — REST API платёжного шлюза для приёма онлайн-платежей. API позволяет создавать инвойсы, получать ссылки на оплату, отслеживать статусы платежей и получать уведомления через вебхуки.

Возможности API

Создание инвойса с детализацией по позициям
Редирект покупателя на платёжную страницу
Polling статуса инвойса
Отмена неоплаченных инвойсов
Server-to-server callback при смене статуса

Рекомендуемый порядок изучения: Быстрый старт → Создание заказа и приём оплаты → Вебхуки (Webhooks).

Base URL

Все запросы к Merchant API выполняются относительно базового URL вашего окружения:

https://gate.example.com

Точный хост выдаётся при подключении мерчанта. Для sandbox и production используются разные базовые URL и разные API-токены.

Authentication

Для всех защищённых эндпоинтов (создание, статус, отмена инвойса) требуется Bearer token в заголовке Authorization и идентификатор мерчанта в заголовке X-Merchant.

Заголовок	Обязательность	Описание
`Authorization`	Да	Формат: `Bearer <api_token>`. Пример: `Bearer sk_live_xxxxxxxxx`
`X-Merchant`	Да	Уникальный идентификатор мерчанта для multi-tenant routing и аудита. Пример: `merchant_123`
`Content-Type`	Для POST	`application/json`

Пример HTTP-запроса с авторизацией:

            POST /invoice/create HTTP/1.1
            Host: api.winwallet.io
            Authorization: Bearer sk_live_xxxxxxxxx
            X-Merchant: merchant_123
            Content-Type: application/json

            {"amount": 1500, "currency": "USD", ...}
        

Жизненный цикл платежа

Типовой сценарий интеграции:

Статусы инвойса:

Код	Статус	Описание
1	PENDING	Инвойс создан, ожидается оплата
2	PAID	Успешно оплачен
3	EXPIRED	Истёк срок действия
4	CANCELED	Отменён мерчантом

Формат ответов API

Успешные и ошибочные ответы бизнес-методов оборачиваются в единую структуру APIResponse: поле result (true/false), при успехе — data, при ошибке — error с message и error_code. Подробнее — в Обработка ошибок.

01 июня 2026