VangardPay — Merchant Portal

Единый портал для мерчантов VangardPay — руководство по работе с платформой, управлению балансом, разрешению апелляций и интеграции по API.

menu_book

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

work Личный кабинет

Вывод средств История операций Отчётность Транзакции

gavel Апелляции

Категории A / B / C Доказательства Процедура Сроки SLA

currency_exchange Расчёты и конвертация

Курсообразование Формула начислений

shield Правила и ответственность

Параметры трафика Комплаенс Защита от атак

integration_instructions API Reference

H2H интеграция Платёжная страница Апелляции API Вебхуки

work Merchant Dashboard

Вывод средств

Доступный баланс отображается на главном экране Dashboard. Для вывода нажмите «Вывести».

Параметр	Значение
Комиссия за вывод	5 USDT за операцию
Время обработки	до 60 минут в рабочие часы (10:00–00:00 МСК)
Допустимые адреса	Только верифицированные кошельки. При использовании нескольких адресов — предварительно согласуйте с финансовым отделом

block

Вывод на площадки, находящиеся под санкциями, запрещён. Такие транзакции будут отклонены.

История операций

Раздел отображает полную историю движения средств по вашему балансу.

Доступные фильтры:

Тип операции: все / входящие (CREDIT, DEPOSIT) / исходящие (DEBIT, WITHDRAW)
Сортировка: по дате, сумме, типу

Данные в таблице:

Столбец	Описание
ID	Уникальный идентификатор операции (UUID)
Дата	Дата и время создания операции
Тип	Тип операции: CREDIT, DEBIT, DEPOSIT, WITHDRAW, FREEZE, UNFREEZE, DEDUCT
Сумма	Сумма операции в USDT
Баланс до	Состояние баланса до операции
Баланс после	Состояние баланса после операции
Тип баланса	Категория баланса: WORKING (рабочий) или FROZEN (замороженный)
Описание	Описание операции и номер связанного ордера

Финансовая отчётность (экспорт)

Выгрузка статистики в формате Excel за произвольный период.

Как выгрузить:

Откройте Настройки → Отчётность
Укажите период (начальная и конечная дата)
Нажмите «Экспорт»

Состав отчёта:

Сводка по аккаунту за выбранный период
Входящие платежи (Pay-In) — все успешные операции приёма
Исходящие платежи (Pay-Out) — все успешные операции отправки
Депозиты — успешные пополнения баланса
Выводы — успешные операции вывода средств

История транзакций

Раздел содержит все транзакции в финальном статусе: Успешно или Отклонено.

Типичные причины отклонения:

Сумма платежа не совпала с суммой в ордере — это может привести к потере средств
Плательщик использовал неверные реквизиты (при оплате через СБП возврат практически невозможен)
Истекло время ожидания оплаты — транзакция закрыта автоматически

Доступные фильтры: дата, статус, способ оплаты, внешний ID (ExtID), внутренний ID.

Данные в таблице:

Столбец	Описание
Статус	Успешно / Отклонено
Баланс (USDT)	Баланс после операции
Сумма (USDT)	Эквивалент в USDT
Курс	Курс конвертации
Сумма (фиат)	Сумма в локальной валюте
Реквизиты	Маскированные данные получателя
Дата	Дата и время создания
Метод	Способ оплаты (CARD_NUMBER / SBP / MOBCOM / CROSSBORDER_PHONE / CROSSBORDER_CARD)
#ID	Уникальный идентификатор транзакции

balance Апелляции

Если плательщик выполнил перевод корректно (верная сумма, верные реквизиты, в установленный срок), транзакция закрывается автоматически. В остальных случаях требуется ручное разбирательство — апелляция.

Классификация апелляций

Категория A. Ошибка плательщика

Качество информирования плательщика на платёжной форме напрямую влияет на количество апелляций. Рекомендуем максимально проработать UX вашей платёжной страницы.

Код	Тип	Описание
A-1	Неполная оплата	Плательщик перевёл сумму меньше указанной в ордере. Распространённые причины: удержание комиссии банком, невнимательность, ошибка ввода
A-2	Избыточная оплата	Перечислена сумма больше указанной. При значительном превышении (например, реквизиты на 5 000, оплата 500 000) существует высокий риск, что средства не будут зачислены
A-3	Просроченная оплата	Перевод выполнен после истечения срока действия ордера. Платформа не несёт ответственности за такие переводы
A-4	Устаревшие реквизиты	Плательщик использовал реквизиты из предыдущего ордера для оплаты нового
A-5	Неверный банк-получатель	При оплате через СБП указан конкретный банк, но перевод направлен в другой. Средства могут поступить на заблокированный счёт
A-6	Дробление платежа	Оплата одного ордера несколькими переводами. Автоматическое сопоставление невозможно — требуется ручная обработка

Категория B. Фрод

Код	Тип	Описание
B-1	Поддельное подтверждение	Предоставлен сфальсифицированный чек или скриншот
B-2	Повторное использование чека	Один чек используется для подтверждения нескольких разных ордеров
B-3	Прочее	Иные случаи мошенничества. Детали предоставляются в рамках индивидуального разбора

Категория C. Техническая ошибка

В редких случаях автоматика платформы может не обработать корректный платёж. Причины: сбой на стороне банка, задержка SMS-подтверждения, проблемы со связью. VangardPay постоянно совершенствует систему для минимизации таких случаев.

Требования к доказательствам

Для успешного рассмотрения апелляции необходимо предоставить подтверждающие документы в одном из следующих форматов:

Банковский чек (PDF)

Финальный статус перевода — «Успешно» или «Исполнено»
Данные получателя — видно, на чей счёт поступил перевод
Точная сумма перевода
Дата и время операции
Без посторонних персональных данных

Видеозапись экрана

Начало записи — с момента входа в интернет-банк (после ввода пароля)
Видна операция с подтверждённым статусом
Чётко отображены: сумма, дата, реквизиты получателя
Отсутствует информация, не относящаяся к платежу

Банковская выписка

Чётко разделены приходные и расходные операции
Видны суммы, даты и время каждой транзакции
Указан номер карты, счёта или привязанного телефона

Аудиозапись звонка в банк

Запись ведётся с отдельного устройства — в кадре виден номер телефона горячей линии
Оператор банка озвучивает название кредитной организации
В ходе разговора уточняются: реквизиты, дата, время и сумма перевода
Запрашивается информация о статусе перевода и возможных задержках

Процедура рассмотрения апелляций

analytics Диаграмма процесса (см. описание ниже)

warning

Апелляция считается активной только после того, как связанная транзакция перейдёт в финальный статус «Отклонено». До этого момента заявка не рассматривается.

Подача апелляции

Мерчант создаёт апелляцию через API (рекомендуется) или через Портал апелляций. Апелляция поступает трейдеру на рассмотрение.

lightbulb

Рекомендация: прикладывайте видеозапись экрана сразу при создании апелляции. Это ускоряет рассмотрение и позволяет закрыть спор на первом этапе — без промежуточных запросов.

Рассмотрение трейдером

Платёж найден и не привязан к другому ордеру → трейдер подтверждает → апелляция одобрена
Платёж не найден → трейдер отклоняет с банковской выпиской → апелляция передаётся на проверку саппорту → возможна вторичная апелляция (см. ниже)
Платёж зачтён по другому ордеру → окончательное отклонение, вторичная апелляция невозможна

Вторичная апелляция (2 этапа)

Вторичная апелляция возможна только при отклонении по причине «Платёж не обнаружен». Следующие причины отклонения являются окончательными и не подлежат вторичной апелляции:

Зачтён по другому ордеру — платёж уже привязан к другой операции
Фрод (категория B) — повторные попытки могут привести к блокировке

warning

Максимальное количество раундов по одной транзакции — 2 (первичная апелляция → вторичная апелляция). После этого вопрос закрыт.

Иерархия веса доказательств (от слабого к сильному):

Приоритет	Тип доказательства
1 (низший)	Чек плательщика (PDF)
2	Банковская выписка (трейдера или плательщика)
3	Видеозапись плательщика
4 (высший)	Видеозапись трейдера

Этап 1. Первичная апелляция

Мерчант создаёт апелляцию и прикладывает чек плательщика. Апелляция поступает трейдеру.

Действия трейдера:

Платёж найден, не зачислен по другому ордеру → трейдер подтверждает → апелляция одобрена
Платёж не найден → трейдер отклоняет с приложением банковской выписки → апелляция передаётся на проверку саппорту

warning

Важно: при отклонении трейдер обязан приложить банковскую выписку, подтверждающую отсутствие поступления. Отклонение без выписки не принимается системой.

После отклонения апелляция передаётся саппорту — саппорт проверяет документы трейдера и пересылает их мерчанту с запросом дополнительных доказательств (видео).

Действия мерчанта (ожидание ответа):

Мерчант не отправляет документы в течение 24 часов → апелляция отклонена
Мерчант не согласен и плательщик прикладывает видео списания → апелляция переходит на вторичное рассмотрение

lightbulb

Шорткат: если мерчант приложил видеозапись (а не чек) сразу при создании первичной апелляции, трейдер может отклонить её только приложив встречное видео. Вторичная апелляция в этом случае исключается — вопрос решается сразу.

Этап 2. Вторичная апелляция

Трейдер получает вторичную апелляцию с видео плательщика.

Действия трейдера:

Трейдер предоставляет встречное видео → решение в пользу трейдера → апелляция отклонена (видео трейдера имеет наибольший вес)
Трейдер не предоставляет видео в течение 3 банковских дней или вручную подтверждает апелляцию → апелляция закрывается в пользу мерчанта

info

Почему 3 банковских дня?

Платёж может находиться на проверке службой безопасности банка
Банку требуется до 3 рабочих дней на рассмотрение
За это время платёж либо зачислится, либо вернётся отправителю

lightbulb

Рекомендация: прикладывайте видеозапись плательщика сразу при создании первичной апелляции. Это позволяет закрыть спорную ситуацию быстрее — без промежуточных этапов и дополнительных запросов.

Сроки рассмотрения (SLA)

Служба апелляций работает круглосуточно, 7 дней в неделю.

Возраст транзакции	Время суток (МСК)	Максимальный срок ответа
0–48 часов	10:00–23:59	45 минут
0–48 часов	00:00-10:00	До 10:00 утра
2–14 дней	любое	5 банковских дней
Вторичная апелляция (срок ответа трейдера)	любое	3 банковских дня
Ответ мерчанта на доказательства трейдера	любое	24 часа (минимум один документ: чек PDF / видео; текст без документа — не ответ)
Старше 14 дней	—	Не принимается

currency_exchange Расчёты и конвертация

Курсообразование

Все расчёты на платформе выполняются по рыночному курсу, сформированному на основе агрегированных данных P2P-площадок (ByBit, Rapira и др.). Курс обновляется в реальном времени.

Детальная методика курсообразования для каждой поддерживаемой валютной пары предоставляется по запросу через вашего менеджера.

Формула начислений

При зачислении средств на баланс мерчанта из суммы платежа удерживается комиссия. Расчёт производится в три этапа.

Исходные данные:

fee — ваша комиссия (%)
rate — текущий курс фиатной валюты к USDT
amount — сумма платежа в фиатной валюте

Все промежуточные значения округляются до 2 знаков после запятой по стандартным математическим правилам (≥ 0.005 → вверх).

Этап	Формула	Пример (amount=10 000₽, rate=95.53, fee=12%)
1. Конвертация в USDT	`usdt = round(amount / rate, 2)`	round(10000 / 95.53, 2) = 104.68
2. Расчёт комиссии	`commission = round(usdt × fee / 100, 2)`	round(104.68 × 12 / 100, 2) = 12.56
3. Зачисление на баланс	`credit = usdt − commission`	104.68 − 12.56 = 92.12 USDT

gavel Правила и ответственность

Настоящий раздел определяет обязательства мерчанта при работе с платформой VangardPay. Нарушение условий может повлечь финансовую ответственность в соответствии с заключённым договором.

1. Соответствие согласованным параметрам трафика

Изменение типа или географии трафика без предварительного согласования с VangardPay не допускается. При выявлении несоответствия между фактическими параметрами трафика и условиями договора платформа вправе применить штрафные санкции.

2. Раскрытие информации об источниках трафика

Мерчант обязан предоставлять полные и достоверные сведения обо всех источниках трафика. Сокрытие информации или предоставление ложных данных влечёт ответственность согласно условиям договора.

3. Добросовестность транзакций

Мерчант несёт ответственность за качество предоставляемых заявок. Намеренная подача недобросовестных или фиктивных ордеров является грубым нарушением условий сотрудничества.

4. Комплаенс при обменных операциях

Использование платформы для приобретения плательщиком товаров, предметов или услуг, запрещённых законодательством соответствующей юрисдикции, строго запрещено.

5. Компенсация убытков

Если действия мерчанта или плательщиков, действующих от имени мерчанта, привели к материальному ущербу для трейдеров платформы, мерчант обязан возместить убытки в полном объёме. Возмещение производится путём списания средств с баланса после предоставления платформой обоснованных доказательств.

Ежемесячно (30-го числа) VangardPay направляет мерчанту акт сверки с детализацией всех случаев.

6. Информирование плательщиков

Мерчант обязан доводить до плательщиков правила совершения платежей и последствия их нарушения. Рекомендуется размещать краткую инструкцию непосредственно на платёжной форме.

7. Защита от автоматизированных атак

Мерчант обязан реализовать на своей стороне защиту от парсинга и перебора платёжных реквизитов (rate limiting, CAPTCHA, мониторинг аномалий).

API Reference

Полная техническая документация для интеграции с платёжной платформой VangardPay. Все запросы выполняются через HTTPS.

vpn_key

Аутентификация

API-ключ выдаётся администратором. Передавайте его в заголовке X-API-Key

webhook

Вебхуки

POST на ваш callbackUrl при изменении статуса ордера. HMAC-SHA256 подпись.

dns

Базовый URL

https://api.vangardpay.com

rocket_launch Быстрый старт

Четыре шага, чтобы начать принимать платежи:

Шаг	Действие	Подробнее
1	Получите доступ к Merchant Dashboard от вашего менеджера	—
2	Получите `X-API-Key` у администратора VangardPay	Ключ выдаётся вручную
3	Выполните тестовый платёж в Sandbox-среде	H2H API или Payment Page
4	Переключитесь на Production и начните приём платежей	Dashboard → Настройки

Способы интеграции

code

Ордера Pay-in

Создание ордеров на пополнение через API. Вы сами строите платёжную форму. Полный контроль над UX.

→ Перейти к Pay-in API

web

Платёжная страница

Создание сессии → редирект на страницу VangardPay. Клиент выбирает сумму и метод сам.

→ Перейти к Payment Page API

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

Все ответы в формате JSON. Успешные запросы возвращают данные напрямую. При ошибке — стандартный объект ошибки.

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

Все ошибки возвращаются в унифицированном формате с типизированным errorCode. Полный список кодов — в разделе Коды ошибок внизу страницы.

{
  "statusCode": 404,
  "errorCode": "ORDER_NOT_FOUND",
  "message": "Ордер не найден",
  "details": null,
  "timestamp": "2026-03-18T12:00:00.000Z",
  "path": "/api/v1/orders/by-id/..."
}

code Ордера Pay-in

Создание ордеров на пополнение через API с заголовком X-API-Key.

Методы оплаты

Поле method определяет, какие реквизиты будут подобраны для ордера. Каждый метод имеет свои обязательные и необязательные поля.

Метод	Описание	Доп. поля в запросе	Реквизиты в ответе
`CARD_NUMBER`	Перевод на банковскую карту. По умолчанию, если `method` не указан.	`bank` (необязательно)	`requisite.cardNumber`, `requisite.holder.bank`
`SBP`	Перевод через Систему быстрых платежей по номеру телефона.	`bank` (необязательно — банк-получатель в СБП)	`requisite.sbpPhoneNumber`, `requisite.holder.bank`
`MOBCOM`	Мобильная коммерция — перевод на номер телефона у мобильного оператора (Билайн, МТС, МегаФон, Tele2). Поле `bank` не используется.	—	`requisite.mobcomPhoneNumber`, `requisite.mobileOperator` (`code`, `name`)
`CROSSBORDER_PHONE`	Трансграничный перевод по локальному номеру телефона. Поддерживаемые страны: AM (Армения), TJ (Таджикистан), UZ (Узбекистан), AB (Абхазия). Список стран, в которых нить обслуживает заявки, закрепляется при подключении (одна или несколько). Конкретная страна для выдачи реквизита определяется каскадом из настроек нити, либо может быть переопределена мерчантом через опциональное поле `requisiteCountry`.	`bank` (необязательно — банк страны), `requisiteCountry` (необязательно — override страны)	`requisite.crossborderPhoneNumber`, `requisite.countryCode`, `requisite.holder.bank`
`CROSSBORDER_CARD`	Трансграничный перевод на локальную банковскую карту. Поддерживаемые страны: AM, TJ, UZ, AB. Список стран, в которых нить обслуживает заявки, закрепляется при подключении (одна или несколько). Конкретная страна для выдачи реквизита определяется каскадом из настроек нити, либо может быть переопределена мерчантом через опциональное поле `requisiteCountry`.	`bank` (необязательно — банк страны), `requisiteCountry` (необязательно — override страны)	`requisite.crossborderCardNumber`, `requisite.countryCode`, `requisite.holder.bank`

info

Список стран (CROSSBORDER_PHONE / CROSSBORDER_CARD) и оператор (MOBCOM) закрепляются за мерчантом при подключении нити. Нить может обслуживать одну или несколько стран. По умолчанию страна выбирается каскадом в рамках настроек нити; мерчант может явно указать страну через опциональное поле requisiteCountry (см. CreateOrderDto). Если поле не передано — каскад работает как раньше. Если передана страна, не подключённая в настройках нити, — запрос отклоняется с ошибкой 400 Bad Request: requisiteCountry is not enabled for this thread. Оператор (MOBCOM) по-прежнему закрепляется за нитью, выбор «налету» не предусмотрен. Фактически выбранная страна возвращается в ответе в requisite.countryCode, оператор — в requisite.mobileOperator.

credit_card

CROSSBORDER_CARD: полный номер карты получателя возвращается в paymentDetails.cardNumber и в order.requisite.crossborderCardNumber. Используйте любое из этих полей для отображения плательщику.

public

Форматы номеров для каждого метода (нормализованные — без пробелов, дефисов и скобок):
CARD_NUMBER (C2C): 13–19 цифр, проверка по алгоритму Luhn. Полный PAN возвращается в ответе мерчанту в полях paymentDetails.cardNumber и order.requisite.cardNumber.
SBP: номер телефона в формате +7XXXXXXXXXX (E.164, 11 цифр после +). Номер должен быть привязан к банку получателя в СБП.
MOBCOM: номер телефона в формате +7XXXXXXXXXX, оператор — один из справочника (BEELINE, MTS, MEGAFON, TELE2 и т.п.).
CROSSBORDER_PHONE — локальный номер страны:
  • AM (Армения): +374 + 8 цифр (пример: +37491234567)
  • TJ (Таджикистан): +992 + 9 цифр (пример: +992901234567)
  • UZ (Узбекистан): +998 + 9 цифр (пример: +998901234567)
  • AB (Абхазия): +7940 + 7 цифр (пример: +79401234567)
CROSSBORDER_CARD: 13–19 цифр локального PAN, проверка по алгоритму Luhn.

Создание нового ордера

POST /api/v1/orders

Тело запроса CreateOrderDto

Поле	Тип	Обяз.	Описание
`type`	enum (DEPOSIT \| WITHDRAWAL)	да	Тип операцииПример: `"DEPOSIT"`
`amount`	number	да	Сумма (0.01–300 000)Пример: `5000`
`currency`	string	нет	Валюта (по умолчанию RUB)Пример: `"RUB"`
`method`	enum (SBP \| CARD_NUMBER \| MOBCOM \| CROSSBORDER_PHONE \| CROSSBORDER_CARD)	да	Метод оплаты (по умолчанию CARD_NUMBER). См. Методы оплатыПример: `"MOBCOM"`
`requisiteCountry`	string	нет	ISO 3166-1 alpha-2 код страны для гео-маршрутизации реквизита. Применяется только к трансгран-методам (`CROSSBORDER_PHONE`, `CROSSBORDER_CARD`). Если задан — каскад ищет реквизит в указанной стране (страна должна быть подключена в настройках нити, иначе `400 Bad Request: requisiteCountry is not enabled for this thread`). Если не передан — страна определяется настройками нити. Поддерживаемые значения: `AM`, `TJ`, `UZ`, `AB`. Игнорируется для не-трансгран-методов.Пример: `"TJ"`
`bank`	string	нет	Код банка получателя (см. список банков через GET /api/v1/banks)Пример: `"SBERBANK"`
`invId`	string	нет	Ваш внутренний ID заказа (генерируется автоматически если не указан)Пример: `"ORDER_123"`
`callbackUrl`	string	нет	URL для вебхук-уведомлений (см. Вебхуки)Пример: `"https://your-site.com/webhook"`
`ttl`	number	нет	Время жизни ордера в секундах (300–86400, по умолчанию 3600)Пример: `3600`

Пример запроса

curl -X POST https://api.vangardpay.com/api/v1/orders \\
  -H "X-API-Key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "type": "DEPOSIT",
    "amount": 5000,
    "method": "SBP",
    "bank": "SBERBANK",
    "callbackUrl": "https://your-site.com/webhook"
  }'

Пример ответа 201 Created

{
  "order": {
    "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "invId": "ORDER_1710528000_abc123",
    "status": "PENDING",
    "amount": 5000,
    "currency": "RUB",
    "requisite": {
      "id": "req-uuid",
      "method": "SBP",
      "sbpPhoneNumber": "+79991234567",
      "holder": {
        "firstName": "Иван",
        "lastName": "Иванов",
        "middleName": "Иванович",
        "bank": { "name": "Сбербанк", "code": "SBERBANK" }
      }
    },
    "createdAt": "2026-03-16T18:00:00.000Z"
  },
  "paymentDetails": {
    "paymentMethod": "SBP",
    "instructions": "Переведите 5000 RUB на указанные реквизиты",
    "recipientFio": "Иван Иванов",
    "bankName": "Сбербанк",
    "bankCode": "SBERBANK",
    "phoneNumber": "+79991234567"
  }
}

Параметры ответа — order

Поле	Тип	Обяз.	Описание
`order.id`	string (UUID)	да	Уникальный идентификатор ордера в системе VangardPay
`order.invId`	string	да	Публичный ID заказа (ваш или сгенерированный автоматически)
`order.status`	string	да	Начальный статус: PENDING (ожидает назначения трейдера)
`order.amount`	number	да	Сумма ордера в фиатной валюте.
`order.currency`	string	да	Код валюты (RUB, KZT и т.д.)
`order.requisite.method`	string	да	Метод оплаты: SBP, CARD_NUMBER, MOBCOM, CROSSBORDER_PHONE, CROSSBORDER_CARD
`order.requisite.countryCode`	string	нет	ISO-код страны реквизита: `AM` \| `TJ` \| `UZ` \| `AB`. Возвращается только для `CROSSBORDER_PHONE` / `CROSSBORDER_CARD`; в других методах поля нет в ответе.
`order.requisite.cardNumber`	string	нет	Полный номер карты получателя. Возвращается только для `method = CARD_NUMBER`.
`order.requisite.sbpPhoneNumber`	string	нет	Телефон СБП-получателя. Возвращается только для `method = SBP`.
`order.requisite.mobcomPhoneNumber`	string	нет	Номер телефона для мобильной коммерции. Возвращается только для `method = MOBCOM`.
`order.requisite.crossborderPhoneNumber`	string	нет	Локальный номер телефона страны получателя. Возвращается только для `method = CROSSBORDER_PHONE`.
`order.requisite.crossborderCardNumber`	string	нет	Полный номер карты получателя страны. Возвращается только для `method = CROSSBORDER_CARD`. Используйте это значение для отображения плательщику.
`order.requisite.mobileOperator.code`	string	нет	Технический код мобильного оператора (`BEELINE`, `MTS`, `MEGAFON`, `TELE2`). Возвращается только для `method = MOBCOM`.
`order.requisite.mobileOperator.name`	string	нет	Отображаемое имя оператора. Возвращается только для `method = MOBCOM`.
`order.requisite.holder.firstName`	string	да	Имя держателя реквизита
`order.requisite.holder.lastName`	string	да	Фамилия держателя
`order.requisite.holder.middleName`	string \| null	нет	Отчество держателя (если задано в реквизите). Может быть `null`.
`order.requisite.holder.bank.name`	string	нет	Название банка. Не возвращается для `MOBCOM` (у мобильной коммерции банка нет).
`order.requisite.holder.bank.code`	string	нет	Код банка (`SBERBANK`, `TINKOFF` и т.д.). Не возвращается для `MOBCOM`.
`order.createdAt`	string (ISO 8601)	да	Дата создания

Параметры ответа — paymentDetails

Поле	Тип	Обяз.	Описание
`paymentDetails.paymentMethod`	string	да	Метод оплаты: `SBP`, `CARD_NUMBER`, `MOBCOM`, `CROSSBORDER_PHONE`, `CROSSBORDER_CARD`.
`paymentDetails.instructions`	string	да	Текстовая инструкция для плательщика.
`paymentDetails.recipientFio`	string	нет	ФИО получателя платежа (для отображения плательщику).
`paymentDetails.bankName`	string	нет	Название банка получателя. Возвращается для всех методов кроме `MOBCOM`.
`paymentDetails.bankCode`	string	нет	Код банка получателя. Возвращается для всех методов кроме `MOBCOM`.
`paymentDetails.cardNumber`	string	нет	Полный номер карты получателя для отображения плательщику. Возвращается только для `CARD_NUMBER` и `CROSSBORDER_CARD` (после дешифровки на стороне платформы).
`paymentDetails.phoneNumber`	string	нет	Телефон получателя. Возвращается только для `SBP`, `MOBCOM`, `CROSSBORDER_PHONE`.

Пример запроса — `MOBCOM`

Запрос

curl -X POST https://api.vangardpay.com/api/v1/orders \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DEPOSIT",
    "amount": 1500,
    "method": "MOBCOM",
    "callbackUrl": "https://your-site.com/webhook"
  }'

Пример ответа 201 Created

{
  "order": {
    "id": "f0e1d2c3-1111-2222-3333-444455556666",
    "invId": "ORDER_1710528100_mob123",
    "status": "PENDING",
    "amount": 1500,
    "currency": "RUB",
    "requisite": {
      "id": "req-mobcom-uuid",
      "method": "MOBCOM",
      "mobcomPhoneNumber": "+79001234567",
      "mobileOperator": { "code": "BEELINE", "name": "Билайн" },
      "holder": {
        "firstName": "Иван",
        "lastName": "Иванов",
        "middleName": "Иванович"
      }
    },
    "createdAt": "2026-04-28T18:00:00.000Z"
  },
  "paymentDetails": {
    "paymentMethod": "MOBCOM",
    "instructions": "Переведите 1500 RUB на указанные реквизиты",
    "recipientFio": "Иван Иванов",
    "phoneNumber": "+79001234567"
  }
}

Пример запроса — `CROSSBORDER_PHONE`

Запрос

curl -X POST https://api.vangardpay.com/api/v1/orders \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DEPOSIT",
    "amount": 8000,
    "method": "CROSSBORDER_PHONE",
    "requisiteCountry": "AM",
    "callbackUrl": "https://your-site.com/webhook"
  }'

Поле requisiteCountry — опциональный override страны. Без него каскад выберет страну из настроек нити (см. описание метода). Указанная страна должна быть подключена в настройках нити, иначе ответ 400 Bad Request.

Пример ответа 201 Created

{
  "order": {
    "id": "a9b8c7d6-aaaa-bbbb-cccc-ddddeeeeffff",
    "invId": "ORDER_1710528200_cbp456",
    "status": "PENDING",
    "amount": 8000,
    "currency": "RUB",
    "requisite": {
      "id": "req-cbp-uuid",
      "method": "CROSSBORDER_PHONE",
      "crossborderPhoneNumber": "+37491234567",
      "countryCode": "AM",
      "holder": {
        "firstName": "Aram",
        "lastName": "Sargsyan",
        "bank": { "name": "Ameriabank", "code": "AMERIA" }
      }
    },
    "createdAt": "2026-04-28T18:00:00.000Z"
  },
  "paymentDetails": {
    "paymentMethod": "CROSSBORDER_PHONE",
    "instructions": "Переведите 8000 RUB на указанные реквизиты",
    "recipientFio": "Aram Sargsyan",
    "bankName": "Ameriabank",
    "bankCode": "AMERIA",
    "phoneNumber": "+37491234567"
  }
}

Пример запроса — `CROSSBORDER_CARD`

Запрос

curl -X POST https://api.vangardpay.com/api/v1/orders \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "DEPOSIT",
    "amount": 12500,
    "method": "CROSSBORDER_CARD",
    "callbackUrl": "https://your-site.com/webhook"
  }'

Пример ответа 201 Created

{
  "order": {
    "id": "11112222-3333-4444-5555-666677778888",
    "invId": "ORDER_1710528300_cbc789",
    "status": "PENDING",
    "amount": 12500,
    "currency": "RUB",
    "requisite": {
      "id": "req-cbc-uuid",
      "method": "CROSSBORDER_CARD",
      "crossborderCardNumber": "4111111111111234",
      "countryCode": "TJ",
      "holder": {
        "firstName": "Rustam",
        "lastName": "Karimov",
        "bank": { "name": "Alif Bank", "code": "ALIF" }
      }
    },
    "createdAt": "2026-04-28T18:00:00.000Z"
  },
  "paymentDetails": {
    "paymentMethod": "CROSSBORDER_CARD",
    "instructions": "Переведите 12500 RUB на указанные реквизиты",
    "recipientFio": "Rustam Karimov",
    "bankName": "Alif Bank",
    "bankCode": "ALIF",
    "cardNumber": "4111111111111234"
  }
}

Получение статуса ордера по invId

GET /api/v1/orders/:invId/status

Параметр :invId — ваш внутренний ID заказа, указанный при создании.

Пример запроса

curl -X GET https://api.vangardpay.com/api/v1/orders/ORDER_123/status \\
  -H "X-API-Key: YOUR_API_KEY"

Пример ответа 200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invId": "ORDER_123",
  "status": "COMPLETED",
  "amount": 5000,
  "factAmount": 4997.50,
  "createdAt": "2026-03-16T18:00:00.000Z",
  "completedAt": "2026-03-16T18:15:00.000Z",
  "appeals": []
}

Параметры ответа

Поле	Тип	Обяз.	Описание
`id`	string (UUID)	да	Уникальный ID ордера в VangardPay
`invId`	string	да	Ваш внутренний ID заказа
`status`	string	да	Текущий статус: PENDING, AWAITING_PAYMENT, COMPLETED, CANCELLED, EXPIRED, FAILED
`amount`	number	да	Запрошенная сумма в фиатной валюте
`factAmount`	number \| null	нет	Фактическая полученная сумма (отличается при недоплате/переплате)
`createdAt`	string (ISO 8601)	да	Дата создания
`completedAt`	string \| null	нет	Дата завершения (null пока не завершён)
`appeals`	array	да	Привязанные апелляции [{id, status, reason, createdAt, updatedAt}]

Список ордеров мерчанта

GET /api/v1/orders

Возвращает список ордеров с пагинацией и фильтрами.

Query-параметры

Поле	Тип	Обяз.	Описание
`page`	number	нет	Номер страницы (по умолчанию 1)Пример: `1`
`limit`	number	нет	Количество на страницу (по умолчанию 20, макс. 100)Пример: `20`
`status`	string	нет	Фильтр по статусу: PENDING, AWAITING_PAYMENT, COMPLETED, CANCELLED, FAILED, EXPIREDПример: `"COMPLETED"`
`type`	string	нет	Тип ордера: DEPOSIT или WITHDRAWALПример: `"DEPOSIT"`
`dateFrom`	string (ISO 8601)	нет	Начало периода (включительно)Пример: `"2026-03-01T00:00:00Z"`
`dateTo`	string (ISO 8601)	нет	Конец периода (включительно)Пример: `"2026-03-31T23:59:59Z"`

Пример запроса

curl -X GET "https://api.vangardpay.com/api/v1/orders?status=COMPLETED&page=1&limit=10" \\
  -H "X-API-Key: YOUR_API_KEY"

Пример ответа 200 OK

{
  "data": [{
    "id": "a1b2c3d4-...", "invId": "ORDER_123", "type": "DEPOSIT",
    "status": "COMPLETED", "currency": "RUB", "amount": 5000,
    "factAmount": 4997.50, "bank": "SBERBANK", "method": "SBP",
    "createdAt": "2026-03-16T18:00:00.000Z",
    "completedAt": "2026-03-16T18:15:00.000Z",
    "expiresAt": "2026-03-16T18:30:00.000Z", "appeals": []
  }],
  "meta": { "total": 42, "page": 1, "limit": 10, "totalPages": 5 }
}

Параметры ответа — data[] (ордер)

Поле	Тип	Обяз.	Описание
`id`	string (UUID)	да	ID ордера
`invId`	string	да	Публичный ID заказа
`type`	string	да	DEPOSIT или WITHDRAWAL
`status`	string	да	Текущий статус ордера
`currency`	string	да	Код валюты
`amount`	number	да	Запрошенная сумма
`factAmount`	number \| null	нет	Фактическая полученная сумма
`bank`	string \| null	нет	Код банка
`method`	string \| null	нет	Метод оплаты
`createdAt`	string (ISO 8601)	да	Дата создания
`completedAt`	string \| null	нет	Дата завершения
`expiresAt`	string \| null	нет	Дата истечения ордера
`appeals`	array	да	Привязанные апелляции [{id, status}]

Параметры ответа — meta

Поле	Тип	Обяз.	Описание
`meta.total`	number	да	Общее количество ордеров по фильтрам
`meta.page`	number	да	Текущая страница
`meta.limit`	number	да	Записей на страницу
`meta.totalPages`	number	да	Всего страниц

Получение ордера по UUID

GET /api/v1/orders/by-id/:id

Возвращает детальную информацию: курс, комиссию, время оплаты и привязанные апелляции.

Пример запроса

curl -X GET https://api.vangardpay.com/api/v1/orders/by-id/a1b2c3d4-e5f6-7890-abcd-ef1234567890 \\
  -H "X-API-Key: YOUR_API_KEY"

Пример ответа 200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invId": "ORDER_123", "type": "DEPOSIT", "status": "COMPLETED",
  "currency": "RUB", "amount": 5000, "factAmount": 4997.50,
  "exchangeRate": 92.5, "usdtAmount": 54.05, "merchantFee": 2.50,
  "bank": "SBERBANK", "method": "SBP",
  "callbackUrl": "https://your-site.com/webhook", "callbackSent": true,
  "expiresAt": "2026-03-16T18:30:00.000Z",
  "createdAt": "2026-03-16T18:00:00.000Z",
  "completedAt": "2026-03-16T18:15:00.000Z",
  "paidAt": "2026-03-16T18:14:50.000Z", "appeals": []
}

Параметры ответа

Поле	Тип	Обяз.	Описание
`id`	string (UUID)	да	ID ордера
`invId`	string	да	Публичный ID заказа
`type`	string	да	DEPOSIT или WITHDRAWAL
`status`	string	да	Текущий статус
`currency`	string	да	Валюта ордера
`amount`	number	да	Запрошенная сумма в фиатной валюте
`factAmount`	number \| null	нет	Фактическая полученная сумма (отличается при недоплате)
`exchangeRate`	number \| null	нет	Курс фиат → USDT на момент создания
`usdtAmount`	number \| null	нет	Эквивалент суммы в USDT
`merchantFee`	number \| null	нет	Комиссия мерчанта в USDT
`bank`	string \| null	нет	Код банка
`method`	string \| null	нет	Метод оплаты
`callbackUrl`	string \| null	нет	URL вебхука, указанный при создании
`callbackSent`	boolean	да	Был ли отправлен вебхук (true/false)
`expiresAt`	string \| null	нет	Время истечения ордера
`createdAt`	string (ISO 8601)	да	Дата создания
`completedAt`	string \| null	нет	Дата завершения
`paidAt`	string \| null	нет	Дата фиксации оплаты клиентом
`appeals`	array	да	Привязанные апелляции [{id, status, reason, createdAt, updatedAt}]

Отмена ордера

POST /api/v1/orders/:id/cancel

Отменяет ордер. Допустимо только для PENDING и AWAITING_PAYMENT. Замороженные средства трейдера разблокируются автоматически.

warning

Отмена ордера в другом статусе вернёт ошибку ORDER_CANCEL_INVALID_STATUS (400).

Пример запроса

curl -X POST https://api.vangardpay.com/api/v1/orders/a1b2c3d4-.../cancel \\
  -H "X-API-Key: YOUR_API_KEY"

Пример ответа 200 OK

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "invId": "ORDER_123", "status": "CANCELLED",
  "amount": 5000, "currency": "RUB",
  "createdAt": "2026-03-16T18:00:00.000Z",
  "completedAt": "2026-03-16T18:20:00.000Z"
}

Параметры ответа

Поле	Тип	Обяз.	Описание
`id`	string (UUID)	да	ID отменённого ордера
`invId`	string	да	Публичный ID заказа
`status`	string	да	Всегда CANCELLED
`amount`	number	да	Запрошенная сумма
`currency`	string	да	Валюта
`createdAt`	string (ISO 8601)	да	Дата создания
`completedAt`	string (ISO 8601)	да	Дата отмены

Баланс мерчанта

GET /api/v1/balance

Пример запроса

curl -X GET https://api.vangardpay.com/api/v1/balance \\
  -H "X-API-Key: YOUR_API_KEY"

Пример ответа 200 OK

{
  "merchant": {
    "id": "m-abc123", "displayName": "My Store",
    "balance": 15250.75, "isVerified": true
  }
}

Параметры ответа — merchant

Поле	Тип	Обяз.	Описание
`merchant.id`	string (UUID)	да	ID мерчанта
`merchant.displayName`	string	да	Отображаемое имя
`merchant.balance`	number	да	Текущий баланс в USDT
`merchant.isVerified`	boolean	да	Верификация пройдена

Список поддерживаемых банков

GET /api/v1/banks

Возвращает банки, доступные для создания ордеров. Поле code используется в параметре bank при создании ордера.

Пример запроса

curl -X GET https://api.vangardpay.com/api/v1/banks \\
  -H "X-API-Key: YOUR_API_KEY"

Пример ответа 200 OK

[
  { "id": "bank-uuid-1", "name": "Сбербанк", "code": "SBERBANK", "logoUrl": "/uploads/banks/sber.png", "countryCode": "RU" },
  { "id": "bank-uuid-2", "name": "Тинькофф", "code": "TINKOFF", "logoUrl": "/uploads/banks/tinkoff.png", "countryCode": "RU" }
]

Параметры ответа — массив объектов

Поле	Тип	Обяз.	Описание
`id`	string (UUID)	да	ID банка
`name`	string	да	Название банка
`code`	string	да	Код для параметра `bank`
`logoUrl`	string \| null	нет	URL логотипа
`countryCode`	string	да	Код страны ISO 3166-1 alpha-2

output Вывод Pay-out

Создание заявок на вывод средств с баланса мерчанта в USDT на TRC-20 кошелёк. Маршрут: /api/withdrawals. Авторизация: Bearer JWT.

info

Поток вывода: Мерчант создаёт заявку → средства замораживаются → администратор одобряет → средства списываются и отправляется транзакция → заявка завершается с txHash.

Создание заявки на вывод

POST /api/withdrawals

Тело запроса

Поле	Тип	Обяз.	Описание
`merchantId`	string (UUID)	да	ID мерчанта (должен совпадать с авторизованным)Пример: `"m-abc123"`
`amount`	number	да	Сумма вывода в USDTПример: `500`
`walletAddress`	string	да	TRC-20 адрес кошелька (формат: T + 33 символа)Пример: `"TJYs..."`
`currency`	string	нет	Валюта (поддерживается только USDT)Пример: `"USDT"`
`comment`	string	нет	Комментарий к заявкеПример: `"Вывод за март"`

warning

Валидация: адрес должен быть TRC-20 (/^T[A-Za-z1-9]{33}$/). Доступный баланс = balance - frozenBalance. При создании заявки средства замораживаются.

Пример запроса

curl -X POST https://api.vangardpay.com/api/withdrawals \\
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \\
  -H "Content-Type: application/json" \\
  -d '{
    "merchantId": "m-abc123",
    "amount": 500,
    "walletAddress": "TJYs7pEqSKVaKnbeed1HpKr1MBGGGEaK1Y",
    "comment": "Вывод за март"
  }'

Пример ответа 201 Created

{
  "id": "wd-uuid-123",
  "merchantId": "m-abc123",
  "amount": 500,
  "currency": "USDT",
  "walletAddress": "TJYs7pEqSKVaKnbeed1HpKr1MBGGGEaK1Y",
  "bankDetails": null,
  "comment": "Вывод за март",
  "status": "PENDING",
  "adminComment": null,
  "processedBy": null,
  "processedAt": null,
  "txHash": null,
  "completedAt": null,
  "createdAt": "2026-03-18T12:00:00.000Z",
  "updatedAt": "2026-03-18T12:00:00.000Z",
  "merchant": {
    "id": "m-abc123",
    "displayName": "My Store",
    "user": { "id": "user-uuid", "login": "merchant@example.com" }
  }
}

Параметры ответа

Поле	Тип	Обяз.	Описание
`id`	string (UUID)	да	ID заявки на вывод
`merchantId`	string (UUID)	да	ID мерчанта
`amount`	number	да	Сумма вывода в USDT
`currency`	string	да	Валюта (USDT)
`walletAddress`	string	да	TRC-20 адрес кошелька
`bankDetails`	object \| null	нет	Банковские реквизиты (не используется для USDT)
`comment`	string \| null	нет	Комментарий мерчанта
`status`	string	да	Статус: PENDING, APPROVED, COMPLETED, REJECTED, CANCELLED
`adminComment`	string \| null	нет	Комментарий администратора (при одобрении/отклонении)
`processedBy`	string \| null	нет	ID администратора, обработавшего заявку
`processedAt`	string \| null	нет	Дата обработки
`txHash`	string \| null	нет	Хеш транзакции (заполняется при завершении)
`completedAt`	string \| null	нет	Дата завершения вывода
`createdAt`	string (ISO 8601)	да	Дата создания
`updatedAt`	string (ISO 8601)	да	Дата обновления
`merchant`	object	да	Данные мерчанта (id, displayName, user)

Список заявок на вывод

GET /api/withdrawals

Возвращает заявки текущего мерчанта с пагинацией и фильтрами.

Query-параметры

Поле	Тип	Обяз.	Описание
`page`	number	нет	Номер страницы (по умолчанию 1)Пример: `1`
`limit`	number	нет	Количество на страницу (по умолчанию 10)Пример: `10`
`status`	string	нет	Фильтр по статусу: PENDING, APPROVED, COMPLETED, REJECTED, CANCELLEDПример: `"PENDING"`

Пример запроса

curl -X GET "https://api.vangardpay.com/api/withdrawals?page=1&limit=10&status=PENDING" \\
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Пример ответа 200 OK

{
  "data": [{
    "id": "wd-uuid-123",
    "merchantId": "m-abc123",
    "amount": 500,
    "currency": "USDT",
    "walletAddress": "TJYs...",
    "status": "PENDING",
    "comment": "Вывод за март",
    "adminComment": null,
    "txHash": null,
    "createdAt": "2026-03-18T12:00:00.000Z",
    "merchant": {
      "id": "m-abc123",
      "user": { "id": "user-uuid", "login": "merchant@example.com" }
    }
  }],
  "meta": { "page": 1, "limit": 10, "total": 5, "totalPages": 1 }
}

Параметры ответа — data[]

Поле	Тип	Обяз.	Описание
`id`	string (UUID)	да	ID заявки
`merchantId`	string	да	ID мерчанта
`amount`	number	да	Сумма вывода
`currency`	string	да	Валюта (USDT)
`walletAddress`	string	да	TRC-20 адрес
`status`	string	да	Текущий статус заявки
`comment`	string \| null	нет	Комментарий мерчанта
`adminComment`	string \| null	нет	Комментарий администратора
`txHash`	string \| null	нет	Хеш транзакции
`createdAt`	string (ISO 8601)	да	Дата создания
`merchant`	object	да	Данные мерчанта

Параметры ответа — meta

Поле	Тип	Обяз.	Описание
`meta.page`	number	да	Текущая страница
`meta.limit`	number	да	Записей на страницу
`meta.total`	number	да	Общее кол-во заявок
`meta.totalPages`	number	да	Всего страниц

Детали заявки на вывод

GET /api/withdrawals/:id

Пример запроса

curl -X GET https://api.vangardpay.com/api/withdrawals/wd-uuid-123 \\
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Пример ответа 200 OK

{
  "id": "wd-uuid-123",
  "merchantId": "m-abc123",
  "amount": 500,
  "currency": "USDT",
  "walletAddress": "TJYs7pEqSKVaKnbeed1HpKr1MBGGGEaK1Y",
  "bankDetails": null,
  "comment": "Вывод за март",
  "status": "COMPLETED",
  "adminComment": "Одобрено",
  "processedBy": "admin-uuid",
  "processedAt": "2026-03-18T14:00:00.000Z",
  "txHash": "abc123def456...",
  "completedAt": "2026-03-18T15:00:00.000Z",
  "createdAt": "2026-03-18T12:00:00.000Z",
  "updatedAt": "2026-03-18T15:00:00.000Z",
  "merchant": {
    "id": "m-abc123",
    "user": { "id": "user-uuid", "login": "merchant@example.com" }
  }
}

Параметры ответа

Поле	Тип	Обяз.	Описание
`id`	string (UUID)	да	ID заявки
`merchantId`	string	да	ID мерчанта
`amount`	number	да	Сумма вывода
`currency`	string	да	Валюта
`walletAddress`	string	да	TRC-20 адрес
`bankDetails`	object \| null	нет	Банковские реквизиты
`comment`	string \| null	нет	Комментарий мерчанта
`status`	string	да	Текущий статус
`adminComment`	string \| null	нет	Комментарий администратора
`processedBy`	string \| null	нет	ID администратора
`processedAt`	string \| null	нет	Дата обработки
`txHash`	string \| null	нет	Хеш транзакции (после завершения)
`completedAt`	string \| null	нет	Дата завершения
`createdAt`	string (ISO 8601)	да	Дата создания
`updatedAt`	string (ISO 8601)	да	Дата обновления
`merchant`	object	да	Данные мерчанта

Отмена заявки на вывод

PATCH /api/withdrawals/:id/cancel

Отменяет заявку. Допустимо только для статуса PENDING. Замороженные средства автоматически разблокируются.

Пример запроса

curl -X PATCH https://api.vangardpay.com/api/withdrawals/wd-uuid-123/cancel \\
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Пример ответа 200 OK

{
  "id": "wd-uuid-123",
  "status": "CANCELLED",
  "amount": 500,
  "processedAt": "2026-03-18T13:00:00.000Z"
}

Параметры ответа

Поле	Тип	Обяз.	Описание
`id`	string (UUID)	да	ID заявки
`status`	string	да	Всегда CANCELLED
`amount`	number	да	Сумма (средства размораживаются)
`processedAt`	string (ISO 8601)	да	Дата отмены

Статусы заявок

Жизненный цикл заявки на вывод

Поле	Тип	Обяз.	Описание
`PENDING`	—	нет	Создана, ожидает одобрения администратором. Средства заморожены
`APPROVED`	—	нет	Одобрена администратором, ожидает отправки транзакции
`COMPLETED`	—	нет	Транзакция отправлена, средства списаны. Содержит txHash
`REJECTED`	—	нет	Отклонена администратором. Средства размораживаются. Причина в adminComment
`CANCELLED`	—	нет	Отменена мерчантом (только из PENDING). Средства размораживаются

Платёжная страница

Создайте платёжную сессию и перенаправьте клиента на страницу VangardPay. Клиент сам выберет сумму и метод.

info

Поток: Создать сессию → получить paymentUrl → редирект клиента → клиент платит → вебхук на ваш сервер

Создание платёжной сессии

POST /api/v1/payment-sessions

Тело запроса CreatePaymentSessionDto

Поле	Тип	Обяз.	Описание
`minAmount`	number	нет	Минимальная сумма платежаПример: `100`
`maxAmount`	number	нет	Максимальная сумма платежаПример: `100000`
`currency`	string	нет	Валюта (по умолчанию RUB)Пример: `"RUB"`
`allowedMethods`	string	нет	JSON-массив разрешённых методов. Допустимые значения: `SBP`, `CARD_NUMBER`, `MOBCOM`, `CROSSBORDER_PHONE`, `CROSSBORDER_CARD`Пример: `["CARD_NUMBER", "SBP", "MOBCOM"]`
`callbackUrl`	string	нет	URL для вебхук-уведомленийПример: `"https://merchant.com/webhook"`
`successUrl`	string	нет	URL редиректа после успехаПример: `"https://merchant.com/success"`
`failUrl`	string	нет	URL редиректа при ошибкеПример: `"https://merchant.com/fail"`
`externalId`	string	нет	Ваш внешний ID заказаПример: `"ORDER_123"`
`metadata`	string	нет	JSON с произвольными даннымиПример: `{"userId": "123"}`
`ttl`	number	нет	Время жизни сессии в секундах (300–86400)Пример: `3600`

Пример запроса

curl -X POST https://api.vangardpay.com/api/v1/payment-sessions \\
  -H "X-API-Key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "minAmount": 500, "maxAmount": 50000,
    "allowedMethods": "["SBP", "CARD_NUMBER"]",
    "callbackUrl": "https://your-site.com/webhook",
    "successUrl": "https://your-site.com/success",
    "failUrl": "https://your-site.com/fail",
    "externalId": "ORDER_456"
  }'

Пример ответа 201 Created

{
  "sessionId": "session-uuid-123",
  "token": "ps_a1b2c3d4e5f6",
  "paymentUrl": "https://pay.vangardpay.com/pay/ps_a1b2c3d4e5f6",
  "expiresAt": "2026-03-16T19:00:00.000Z"
}

Параметры ответа

Поле	Тип	Обяз.	Описание
`sessionId`	string (UUID)	да	ID сессии в системе
`token`	string	да	Публичный токен сессии
`paymentUrl`	string	да	URL платёжной страницы — перенаправьте клиента сюда
`expiresAt`	string (ISO 8601)	да	Время истечения сессии

gavel Апелляции

Если ордер завершился некорректно (клиент оплатил, но статус не подтвердился), создайте апелляцию.

Создание апелляции

POST /api/appeals

Тело запроса CreateAppealDto

Поле	Тип	Обяз.	Описание
`orderId`	string (UUID)	нет	UUID ордера в системе (один из orderId / invId обязателен)Пример: `"550e8400-..."`
`invId`	string	нет	Ваш публичный ID заказа (альтернатива orderId)Пример: `"INV-12345"`
`reason`	string	да	Причина апелляцииПример: `"Платёж не зачислен"`
`comment`	string	нет	Подробный комментарийПример: `"Клиент отправил 5000 руб"`
`images`	string[]	нет	URL изображений (предварительно загрузите через /upload)
`videos`	string[]	нет	URL видеозаписей
`documents`	string[]	нет	URL документов (PDF, DOC)

lightbulb

Сначала загрузите файлы через POST /api/appeals/upload, затем передайте URL в массивы images, videos, documents.

Пример запроса

curl -X POST https://api.vangardpay.com/api/appeals \\
  -H "X-API-Key: YOUR_API_KEY" \\
  -H "Content-Type: application/json" \\
  -d '{
    "invId": "ORDER_123",
    "reason": "Платёж не зачислен",
    "comment": "Клиент отправил 5000 руб, приложен чек",
    "images": ["https://api.vangardpay.com/uploads/appeals/appeal-123.jpg"]
  }'

Пример ответа 201 Created

{
  "id": "appeal-uuid-123",
  "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reason": "Платёж не зачислен",
  "comment": "Клиент отправил 5000 руб, приложен чек",
  "status": "PENDING",
  "images": "["https://api.vangardpay.com/uploads/appeals/appeal-123.jpg"]",
  "videos": null, "documents": null,
  "deadline": "2026-03-19T18:00:00.000Z",
  "createdAt": "2026-03-16T18:00:00.000Z",
  "order": {
    "id": "a1b2c3d4",
    "merchant": { "id": "m-abc", "displayName": "My Store" },
    "provider": null
  }
}

Параметры ответа

Поле	Тип	Обяз.	Описание
`id`	string (UUID)	да	ID апелляции
`orderId`	string (UUID)	да	ID связанного ордера
`reason`	string	да	Причина
`comment`	string \| null	нет	Комментарий
`status`	string	да	Статус: PENDING, UNDER_REVIEW, APPROVED, REJECTED, SUPPORT_REVIEW, TRADER_REVIEW
`images`	string \| null	нет	JSON-массив URL изображений
`videos`	string \| null	нет	JSON-массив URL видео
`documents`	string \| null	нет	JSON-массив URL документов
`deadline`	string (ISO 8601)	да	Крайний срок рассмотрения
`createdAt`	string (ISO 8601)	да	Дата создания
`order`	object	да	Краткие данные связанного ордера

Загрузка файлов для апелляции

POST /api/appeals/upload

Загрузка до 10 файлов (макс. 50 МБ каждый). Форматы: JPEG, PNG, GIF, WebP, MP4, AVI, PDF, DOC, DOCX, TXT, ZIP, XLS, XLSX.

Пример запроса

curl -X POST https://api.vangardpay.com/api/appeals/upload \\
  -H "X-API-Key: YOUR_API_KEY" \\
  -F "files=@screenshot.png" \\
  -F "files=@receipt.pdf"

Пример ответа 200 OK

{
  "files": [
    { "type": "image", "path": "https://api.vangardpay.com/uploads/appeals/appeal-123.png",
      "mime_type": "image/png", "originalName": "screenshot.png", "size": 245760 },
    { "type": "document", "path": "https://api.vangardpay.com/uploads/appeals/appeal-456.pdf",
      "mime_type": "application/pdf", "originalName": "receipt.pdf", "size": 102400 }
  ],
  "message": "Загружено 2 файл(ов)"
}

Параметры ответа — files[]

Поле	Тип	Обяз.	Описание
`type`	string	да	Тип файла: image, video, document
`path`	string	да	Полный URL загруженного файла (передавайте в images/videos/documents при создании апелляции)
`mime_type`	string	да	MIME-тип файла
`originalName`	string	да	Оригинальное имя файла
`size`	number	да	Размер файла в байтах

Параметры ответа — корневые

Поле	Тип	Обяз.	Описание
`message`	string	да	Информационное сообщение

Список апелляций мерчанта

GET /api/appeals

Возвращает список апелляций с пагинацией и фильтрами.

Query-параметры

Поле	Тип	Обяз.	Описание
`page`	number	нет	Номер страницы (по умолчанию 1)Пример: `1`
`limit`	number	нет	Количество на странице (по умолчанию 20)Пример: `20`
`status`	string	нет	Фильтр по статусу апелляцииПример: `"PENDING"`
`orderId`	string	нет	Фильтр по UUID ордера
`dateFrom`	string (ISO 8601)	нет	Начало периода
`dateTo`	string (ISO 8601)	нет	Конец периода

Пример запроса

curl -X GET "https://api.vangardpay.com/api/appeals?page=1&limit=10" \\
  -H "X-API-Key: YOUR_API_KEY"

Пример ответа 200 OK

{
  "data": [{
    "id": "appeal-uuid-123", "orderId": "a1b2c3d4",
    "reason": "Платёж не зачислен", "status": "PENDING",
    "deadline": "2026-03-19T18:00:00.000Z",
    "createdAt": "2026-03-16T18:00:00.000Z",
    "order": {
      "id": "a1b2c3d4", "invId": "ORDER_123", "amount": 5000,
      "status": "CANCELLED",
      "requisite": { "id": "req-uuid", "method": "SBP",
        "sbpPhoneNumber": "+79991234567",
        "holder": { "firstName": "Иван", "lastName": "Иванов",
          "bank": { "name": "Сбербанк", "code": "SBERBANK" } }
      }
    }
  }],
  "meta": { "total": 3, "page": 1, "limit": 10, "totalPages": 1 }
}

Параметры ответа — data[]

Поле	Тип	Обяз.	Описание
`id`	string (UUID)	да	ID апелляции
`orderId`	string	да	ID связанного ордера
`reason`	string	да	Причина апелляции
`status`	string	да	Статус апелляции
`deadline`	string (ISO 8601)	да	Крайний срок
`createdAt`	string (ISO 8601)	да	Дата создания
`order`	object	да	Данные ордера (id, invId, amount, status, merchant, trader, requisite)

Параметры ответа — meta

Поле	Тип	Обяз.	Описание
`meta.total`	number	да	Общее кол-во апелляций
`meta.page`	number	да	Текущая страница
`meta.limit`	number	да	Записей на страницу
`meta.totalPages`	number	да	Всего страниц

Детали апелляции

GET /api/appeals/:id

Полная информация: прикреплённые файлы, история изменений статуса.

Пример запроса

curl -X GET https://api.vangardpay.com/api/appeals/APPEAL_UUID \\
  -H "X-API-Key: YOUR_API_KEY"

Пример ответа 200 OK

{
  "id": "appeal-uuid-123",
  "orderId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "reason": "Платёж не зачислен", "comment": "Клиент отправил 5000 руб",
  "status": "PENDING",
  "images": "["https://api.vangardpay.com/uploads/appeals/appeal-123.jpg"]",
  "videos": null, "documents": null,
  "deadline": "2026-03-19T18:00:00.000Z",
  "createdAt": "2026-03-16T18:00:00.000Z",
  "order": {
    "id": "a1b2c3d4", "invId": "ORDER_123", "amount": 5000,
    "currency": "RUB", "status": "CANCELLED", "type": "DEPOSIT",
    "bank": "SBERBANK", "createdAt": "2026-03-16T17:00:00.000Z",
    "requisite": { "id": "req-uuid", "method": "SBP",
      "sbpPhoneNumber": "+79991234567",
      "holder": { "firstName": "Иван", "lastName": "Иванов",
        "bank": { "name": "Сбербанк", "code": "SBERBANK" } } }
  },
  "changeLogs": [
    { "id": "log-1", "status": "PENDING", "comment": null, "createdAt": "2026-03-16T18:00:00.000Z" }
  ]
}

Параметры ответа

Поле	Тип	Обяз.	Описание
`id`	string (UUID)	да	ID апелляции
`orderId`	string (UUID)	да	ID связанного ордера
`reason`	string	да	Причина
`comment`	string \| null	нет	Комментарий мерчанта
`status`	string	да	Текущий статус
`images`	string \| null	нет	JSON-массив URL изображений
`videos`	string \| null	нет	JSON-массив URL видео
`documents`	string \| null	нет	JSON-массив URL документов
`deadline`	string (ISO 8601)	да	Крайний срок рассмотрения
`createdAt`	string (ISO 8601)	да	Дата создания
`order`	object	да	Полные данные ордера (id, invId, amount, currency, status, type, bank, merchant, trader, requisite)
`changeLogs`	array	да	История смен статуса [{id, status, comment, createdAt}]

webhook Вебхуки

При каждом изменении статуса ордера VangardPay отправляет POST-запрос на ваш callbackUrl. Формат: application/json. Заголовок: User-Agent: PaymentAggregator/1.0.

info

Когда отправляется вебхук? При любом изменении статуса ордера: PENDING → AWAITING_PAYMENT, AWAITING_PAYMENT → COMPLETED, → CANCELLED, → EXPIRED, → FAILED.

Формат вебхука

{
  "invId": "ORDER_123",
  "status": "COMPLETED",
  "amount": 5000,
  "factAmount": 4997.50,
  "currency": "RUB",
  "timestamp": "2026-03-16T18:15:00.000Z",
  "signature": "a1b2c3d4e5f6..."
}

Параметры вебхука (JSON body)

Поле	Тип	Обяз.	Описание
`invId`	string	да	Ваш внутренний ID заказа (invId при создании ордера)Пример: `"ORDER_123"`
`status`	string	да	Новый статус ордера: PENDING, AWAITING_PAYMENT, COMPLETED, CANCELLED, EXPIRED, FAILEDПример: `"COMPLETED"`
`amount`	number	да	Запрошенная сумма ордера в фиатной валютеПример: `5000`
`factAmount`	number \| null	нет	Фактическая полученная сумма (только для COMPLETED, может отличаться от amount)Пример: `4997.5`
`currency`	string	да	Код валюты ордераПример: `"RUB"`
`timestamp`	string (ISO 8601)	да	Время события на стороне сервераПример: `"2026-03-16T18:15:00.000Z"`
`signature`	string	да	HMAC-SHA256 подпись для верификации (см. ниже)

Проверка подписи (HMAC-SHA256)

Подпись вычисляется из конкатенации 4 полей + ваш callbackSecret:

dataString = invId + status + amount + timestamp
signature  = HMAC-SHA256(dataString, callbackSecret)

warning

Всегда проверяйте подпись! Без проверки подписи злоумышленник может подделать вебхук и зачислить средства без реальной оплаты.

Пример на Node.js:

const crypto = require('crypto');

app.post('/webhook', (req, res) => {
  const { invId, status, amount, timestamp, signature } = req.body;

  const dataString = invId + status + amount + timestamp;
  const expected = crypto
    .createHmac('sha256', CALLBACK_SECRET)
    .update(dataString)
    .digest('hex');

  if (expected !== signature) {
    return res.status(403).json({ error: 'Invalid signature' });
  }

  // Обработка события
  switch (status) {
    case 'COMPLETED':
      // Зачислить средства пользователю
      break;
    case 'CANCELLED':
    case 'EXPIRED':
    case 'FAILED':
      // Уведомить пользователя об ошибке
      break;
  }

  res.json({ ok: true });  // Обязательно ответить 200!
});

Пример на PHP:

$data = json_decode(file_get_contents('php://input'), true);

$dataString = $data['invId'] . $data['status'] . $data['amount'] . $data['timestamp'];
$expected = hash_hmac('sha256', $dataString, $callbackSecret);

if (!hash_equals($expected, $data['signature'])) {
    http_response_code(403);
    exit('Invalid signature');
}

// Обработка событие
if ($data['status'] === 'COMPLETED') {
    // Зачислить средства
}
http_response_code(200);
echo json_encode(['ok' => true]);

Пример на Python:

import hmac, hashlib, json
from flask import Flask, request, jsonify

app = Flask(__name__)

@app.route('/webhook', methods=['POST'])
def webhook():
    data = request.json
    data_string = f"{data['invId']}{data['status']}{data['amount']}{data['timestamp']}"
    expected = hmac.new(
        CALLBACK_SECRET.encode(),
        data_string.encode(),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(expected, data['signature']):
        return jsonify(error='Invalid signature'), 403

    if data['status'] == 'COMPLETED':
        # Зачислить средства
        pass

    return jsonify(ok=True), 200

Ожидаемый ответ

Ваш сервер обязан ответить HTTP 200 OK с любым телом. Все остальные коды считаются ошибкой.

Политика повторов

Политика повторной отправки

Поле	Тип	Обяз.	Описание
`Таймаут`	—	да	10 секунд на ответ сервера
`Количество попыток`	—	да	Максимум 3 попытки
`Интервал`	—	да	60 секунд между попытками
`После 3 неудач`	—	да	Вебхук прекращается, callbackSent остаётся false

warning

Если ваш сервер не ответил 200 OK за 10 секунд, вебхук будет отправлен повторно до 3 раз с интервалом 60 секунд. После 3 неудачных попыток уведомление прекращается — используйте GET /orders/:invId/status для актуализации.

Идемпотентность

lightbulb

Рекомендация: обрабатывайте вебхуки идемпотентно. Один и тот же вебхук может быть доставлен повторно (при retry). Сохраняйте invId + status и проверяйте дубли перед зачислением средств.

Статусы ордеров

Возможные статусы

Поле	Тип	Обяз.	Описание
`PENDING`	—	нет	Ордер создан, ожидает назначения трейдера
`AWAITING_PAYMENT`	—	нет	Трейдер назначен, клиент должен оплатить
`COMPLETED`	—	нет	Платёж подтверждён, средства зачислены
`CANCELLED`	—	нет	Ордер отменён мерчантом или системой
`EXPIRED`	—	нет	Истёк таймаут ордера (ttl)
`FAILED`	—	нет	Ошибка обработки ордера

error Коды ошибок

Все ошибки API возвращаются в унифицированном формате с типизированным errorCode:

{
  "statusCode": 400,
  "errorCode": "ORDER_CANCEL_INVALID_STATUS",
  "message": "Невозможно отменить ордер в статусе COMPLETED",
  "details": null,
  "timestamp": "2026-03-18T12:00:00.000Z",
  "path": "/api/v1/orders/uuid/cancel"
}

Параметры ошибки

Поле	Тип	Обяз.	Описание
`statusCode`	number	да	HTTP-статус код (400, 401, 403, 404, 429, 500)
`errorCode`	string	да	Типизированный код ошибки (см. таблицы ниже)
`message`	string	да	Человекочитаемое описание ошибки
`details`	any \| null	нет	Дополнительные данные (массив ошибок валидации и т.д.)
`timestamp`	string (ISO 8601)	да	Время ошибки
`path`	string	да	Путь запроса, вызвавшего ошибку

Ордера

Коды ошибок ордеров

Поле	Тип	Обяз.	Описание
`ORDER_NOT_FOUND`	404	нет	Ордер с указанным ID не найден
`ORDER_ACCESS_DENIED`	403	нет	Нет доступа к чужому ордеру
`ORDER_CANCEL_INVALID_STATUS`	400	нет	Отмена допустима только для PENDING / AWAITING_PAYMENT
`ORDER_EXPIRED`	400	нет	Ордер истёк
`ORDER_CREATION_DISABLED`	400	нет	Торговая активность мерчанта отключена
`NO_AVAILABLE_TRADERS`	400	нет	Нет трейдеров с подходящими реквизитами и балансом

Апелляции

Коды ошибок апелляций

Поле	Тип	Обяз.	Описание
`APPEAL_NOT_FOUND`	404	нет	Апелляция не найдена
`APPEAL_ACCESS_DENIED`	403	нет	Нет доступа к чужой апелляции
`APPEAL_STATUS_INVALID`	400	нет	Невалидная смена статуса

Общие

Общие коды ошибок

Поле	Тип	Обяз.	Описание
`UNAUTHORIZED`	401	нет	Невалидный API-ключ или JWT-токен
`FORBIDDEN`	403	нет	Недостаточно прав для действия
`VALIDATION_ERROR`	400	нет	Ошибка валидации полей запроса
`RATE_LIMIT_EXCEEDED`	429	нет	Превышен лимит запросов
`MERCHANT_NOT_FOUND`	404	нет	Merchant профиль не найден
`INSUFFICIENT_BALANCE`	400	нет	Недостаточно средств для операции
`FILE_NOT_FOUND`	404	нет	Файл не найден на сервере
`RECEIPT_NOT_FOUND`	404	нет	Чек не найден
`INTERNAL_ERROR`	500	нет	Внутренняя ошибка сервера

VangardPay — Merchant Portal

work Merchant Dashboard

Вывод средств

История операций

Финансовая отчётность (экспорт)

История транзакций

balance Апелляции

Классификация апелляций

Категория A. Ошибка плательщика

Категория B. Фрод

Категория C. Техническая ошибка

Требования к доказательствам

Банковский чек (PDF)

Видеозапись экрана

Банковская выписка

Аудиозапись звонка в банк

Процедура рассмотрения апелляций

Подача апелляции

Рассмотрение трейдером

Вторичная апелляция (2 этапа)

Сроки рассмотрения (SLA)

currency_exchange Расчёты и конвертация

Курсообразование

Формула начислений

gavel Правила и ответственность

1. Соответствие согласованным параметрам трафика

2. Раскрытие информации об источниках трафика

3. Добросовестность транзакций

4. Комплаенс при обменных операциях

5. Компенсация убытков

6. Информирование плательщиков

7. Защита от автоматизированных атак

API Reference

Аутентификация

Вебхуки

Базовый URL

rocket_launch Быстрый старт

Способы интеграции

Ордера Pay-in

Платёжная страница

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

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

code Ордера Pay-in

Методы оплаты

Создание нового ордера

Пример запроса — MOBCOM

Пример запроса — CROSSBORDER_PHONE

Пример запроса — CROSSBORDER_CARD

Получение статуса ордера по invId

Список ордеров мерчанта

Получение ордера по UUID

Отмена ордера

Баланс мерчанта

Список поддерживаемых банков

output Вывод Pay-out

Создание заявки на вывод

Список заявок на вывод

Детали заявки на вывод

Отмена заявки на вывод

Статусы заявок

Платёжная страница

Создание платёжной сессии

gavel Апелляции

Создание апелляции

Загрузка файлов для апелляции

Список апелляций мерчанта

Детали апелляции

webhook Вебхуки

Формат вебхука

Проверка подписи (HMAC-SHA256)

Ожидаемый ответ

Политика повторов

Идемпотентность

Статусы ордеров

error Коды ошибок

Ордера

Апелляции

Общие

Пример запроса — `MOBCOM`

Пример запроса — `CROSSBORDER_PHONE`

Пример запроса — `CROSSBORDER_CARD`