Приём средств #
Заголовки — в «Авторизации». Статусы — в «Статусах».
POST /gw/v1/collect #
Создать заявку на приём.
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
merchant_reference | string | да | Ваш номер заказа. Он же ключ идемпотентности |
amount | int64 | да* | Сумма целыми рублями, > 0: 7000 = 7 000 ₽ |
amount_minor | int64 | да* | Та же сумма в копейках: 700000 = 7 000 ₽ |
currency | string | да | Валюта заявки, например RUB |
method | string | да | C2C (карта) или SBP, регистр не важен. Другое значение — 400 с текстом method must be SBP or C2C |
metadata | object | нет | Произвольный JSON. Хранится, в ответах не возвращается |
\* Сумма присылается ОДНИМ из двух полей. Оба разом — 400: разойдись они, любой наш выбор был бы неверным для половины случаев. amount — целое число, дробных сумм в контракте нет.
Поля direction нет: путь задаёт направление. Неизвестные поля в теле — 400, а не молчаливое игнорирование.
Запрос
{
"merchant_reference": "order-42",
"amount": 7000,
"currency": "RUB",
"method": "SBP"
}201 — заявка создана. 200 — повтор: заявка с этим merchant_reference уже была, вернули её как есть, в текущем состоянии. Тело в обоих случаях — формат заявки.
Ответ синхронный. Исполнитель подбирается внутри этого же запроса, и ответ несёт окончательный результат — экран оплаты рисуйте прямо по нему:
| Что в ответе | Что делать |
|---|---|
status: awaiting_payment, есть requisite | Обычный случай. Показать плательщику requisite |
status: lapsed, decline_reason: "no_executor" | Исполнителя сейчас нет. Заявка закрыта, создавайте новую |
status: accepted, requisite нет | Редко: подбор не успел завершиться. Реквизит придёт уведомлением или опросом, см. «Сколько ждать реквизит» |
В ответе же — rate: курс, зафиксированный на этой заявке. По нему исполненная заявка зачислится на баланс в USDT, отдельно запрашивать курс по сделке не нужно.
{
"reference": "ord_01J8Z9QF3K4M5N6P7Q8R9S0T1U",
"merchant_reference": "order-42",
"status": "awaiting_payment",
"amount": 7000,
"amount_minor": 700000,
"currency": "RUB",
"method": "SBP",
"rate": "87.22360796",
"rate_e8": 8722360796,
"requisite": {
"number": "+79001234567",
"holder_name": "IVAN IVANOV",
"bank_code": "sberbank",
"expires_at": "2026-09-22T12:15:00Z"
},
"created_at": "2026-09-22T12:00:00Z",
"updated_at": "2026-09-22T12:00:01Z"
}Ошибки: 400 INVALID_ARGUMENT (пустое тело, нет обязательного поля, сумма <= 0, неизвестное поле, method не SBP/C2C), 401 UNAUTHORIZED, 403 FORBIDDEN (ключ без p2p:payin), 409 IDEMPOTENCY_CONFLICT (тот же merchant_reference с другой суммой, валютой или способом), 429 RATE_LIMITED.
POST /gw/v1/collect/{reference}/cancel #
Отменить неоплаченную заявку. Тела нет.
Заявка не удаляется — она остаётся в истории и в сверке с исходом «не исполнена».
200 — формат заявки, status: "declined", decline_reason: "merchant_cancelled". Реквизита в ответе нет.
Коллбек на отмену не отправляется: вы её инициировали, и итог — в этом ответе. Если ответ потерялся (таймаут, обрыв), узнайте статус через GET /gw/v1/collect/{reference}.
Ошибки: 401 UNAUTHORIZED, 404 NOT_FOUND (нет такой заявки или она чужая), 409 CONFLICT (заявка уже оплачена, отменена или истекла), 429 RATE_LIMITED.
| Статус заявки | Отмена |
|---|---|
accepted | Да |
awaiting_payment | Да — реквизит освобождается сразу |
fulfilled | Нет, 409 |
declined / lapsed | Нет, 409 — уже терминальная |
Отменять после выдачи реквизита можно намеренно: это самый частый повод (плательщик увидел реквизит и закрыл вкладку). Если деньги всё-таки придут после отмены, автоматически они не зачислятся — это разбирается спором.
Отмена и подтверждение оплаты могут прийти в одну секунду. Выигрывает то, что пришло первым: по уже оплаченной заявке отмена вернёт 409, и деньги не потеряются.
GET /gw/v1/collect/{reference} #
Состояние заявки. {reference} — поле reference из ответа на создание.
200
{
"reference": "ord_01J8Z9QF3K4M5N6P7Q8R9S0T1U",
"merchant_reference": "order-42",
"status": "awaiting_payment",
"amount_minor": 1000000,
"currency": "RUB",
"method": "C2C",
"requisite": {
"number": "4111111111111111",
"holder_name": "IVAN IVANOV",
"bank_code": "sberbank",
"expires_at": "2026-09-23T10:45:00Z"
},
"created_at": "2026-09-22T12:00:00Z",
"updated_at": "2026-09-22T12:03:00Z"
}Ошибки: 401 UNAUTHORIZED, 404 NOT_FOUND (нет такой заявки или она чужая — эти случаи намеренно неразличимы), 429 RATE_LIMITED.
Сколько ждать реквизит #
Обычно нисколько: реквизит приходит в ответе на создание. Ниже — только для редкого случая, когда создание ответило accepted без реквизита.
| Что | Сколько |
|---|---|
accepted → awaiting_payment (выдача реквизита) | Обычно 1–2 с |
| Сколько заявка ищет исполнителя, пока не сдастся | 10 мин |
| Сколько действует выданный реквизит | 15 мин |
Опрашивайте раз в секунду первые 10 секунд, дальше раз в 5 секунд. Если исполнителя не нашлось за 10 минут, заявка сама становится lapsed с decline_reason: "no_executor" — свободных реквизитов под неё не было. Ждать дольше незачем, создавайте новую.
Формат заявки #
| Поле | Тип | Когда есть | Описание |
|---|---|---|---|
reference | string | всегда | Наш номер заявки (ord_...) |
merchant_reference | string | если передавали | Ваш номер заказа |
status | string | всегда | Публичный статус |
amount | int64 | всегда | Сумма целыми рублями |
amount_minor | int64 | всегда | Сумма в минимальных единицах. После закрытия спора на фактическую сумму — фактическая |
original_amount, original_amount_minor | int64 | только если сумма менялась | Исходная сумма заявки — та, с которой вы её создали. Есть, только когда по спору заявка закрыта на другую сумму |
currency | string | всегда | Валюта заявки |
method | string | всегда | Способ оплаты |
rate | string | если курс зафиксирован | Курс этой заявки: сколько единиц currency за 1 USDT. Фиксируется при создании и дальше не меняется; по нему заявка зачислится на баланс. Строкой — разбирайте десятичным типом, не float |
rate_e8 | int64 | вместе с rate | Тот же курс целым числом: rate × 10^8 |
decline_reason | string | у части declined | Свободный текст причины, не код. Может быть пустым |
requisite | object | только awaiting_payment | Куда платить, см. ниже |
created_at | datetime | всегда | Создание заявки |
updated_at | datetime | всегда | Последнее изменение |
settled_at | datetime | только fulfilled | Момент подтверждения оплаты. У declined / lapsed / reversed поля нет |
dispute | object | только если вы открывали спор по заявке | Ваш последний спор по заявке и переписка с поддержкой, см. Переписка по спору |
metadata в ответе не возвращается.
requisite #
| Поле | Тип | Когда есть | Описание |
|---|---|---|---|
number | string | всегда | Куда платить. Номер телефона при method = SBP, номер карты при C2C |
holder_name | string | всегда | Имя получателя. При SBP плательщик увидит его в своём банке и сверит |
bank_code | string | всегда | Код банка получателя. Название и логотип по коду — справочник банков |
expires_at | datetime | если известен | До какого момента реквизит точно действителен |
Одно поле number на оба способа: что в нём лежит, задаёт method заявки — тот самый, который вы прислали при создании. Ветвиться на стороне интеграции не нужно, достаточно показать number и holder_name.
Выданный реквизит не меняется #
Как только вы получили
requisite, он закреплён за заявкой до конца. Платформа НЕ передаёт заявку другому исполнителю с другим реквизитом: плательщик уже видит номер и может переводить прямо сейчас.Значит заявка из
awaiting_paymentуходит только вперёд:
- заплатили —
fulfilled;- не заплатили за отведённое время —
lapsed,decline_reason: payment_not_received.Возврата в
acceptedпри приёме не бывает. Реквизит с экрана убирайте по терминальному статусу, а не по таймеру.
POST /gw/v1/collect/{reference}/claim #
Открыть спор по заявке. Окно — семь дней с момента, когда заявка пришла к результату (fulfilled, declined, lapsed).
| Поле | Тип | Обяз. | Описание |
|---|---|---|---|
reason | string | да | Причина, 10–2000 символов после схлопывания пробелов |
Запрос
{ "reason": "деньги списаны, но заявка отмечена как неоплаченная" }201
{
"reference": "ord_01J8Z9QF3K4M5N6P7Q8R9S0T1U",
"status": "disputed",
"reason": "деньги списаны, но заявка отмечена как неоплаченная"
}С этого момента GET по заявке возвращает disputed — отдельного ресурса спора нет.
Переписка по спору #
Поддержка отвечает на спор письменно. Ответ приходит в поле dispute ответа GET /gw/v1/collect/{reference} и виден в кабинете мерчанта (раздел «Споры»). Там же можно ответить поддержке. Поле есть, только если по заявке открывали спор вы; споры исполнителя сюда не попадают.
| Поле | Тип | Описание |
|---|---|---|
dispute.id | string | Номер спора (dsp_...) |
dispute.status | string | open — разбираем, resolved — решён, withdrawn — закрыт без решения. В чью пользу решили, видно по status самой заявки |
dispute.opened_at | datetime | Когда открыт спор |
dispute.reason | string | Ваша причина спора |
dispute.messages[] | array | Переписка по порядку. Пустой массив — ответов ещё не было |
dispute.messages[].from | string | platform — ответ поддержки, merchant — ваше сообщение из кабинета |
dispute.messages[].text | string | Текст сообщения |
dispute.messages[].at | datetime | Когда отправлено |
{
"reference": "ord_01M43KHZQY3TJ4Y0DWRHPAZ1ZK",
"status": "disputed",
"dispute": {
"id": "dsp_01K6ZQ7S6DHR3PM0BB1YZ9D4KQ",
"status": "open",
"opened_at": "2026-10-07T09:00:00Z",
"reason": "Плательщик перевёл 5012.00, оплата не зачтена",
"messages": [
{ "from": "platform", "text": "Оплату нашли, заявку закроем в течение часа", "at": "2026-10-07T10:00:00Z" }
]
}
}Отдельного коллбека о новом ответе нет. Пока спор открыт, проверяйте поле при обычном опросе статуса.
Закрытие на фактическую сумму #
Плательщик мог заплатить не ту сумму, что в заявке (например, 7 000 вместо 7 030), или заплатить по уже закрытой заявке. Приложите чек в причине спора: платформа по нему закрывает заявку как оплаченную на фактическую сумму — меньше или больше исходной.
После этого:
- статус заявки —
fulfilled; amount/amount_minor— фактическая сумма, по ней же пересчитан расчёт и зачисление на баланс;original_amount/original_amount_minor— исходная сумма заявки;- уходит коллбек
collect.status_changedс этими полями — даже если заявка и раньше былаfulfilledи поменялась только сумма.
{
"reference": "ord_01M43KHZQY3TJ4Y0DWRHPAZ1ZK",
"merchant_reference": "order-42",
"status": "fulfilled",
"amount": 7000,
"amount_minor": 700000,
"original_amount": 7030,
"original_amount_minor": 703000,
"currency": "RUB"
}Сверяйте зачисление по amount_minor, а original_amount_minor — с суммой своего заказа.
Ошибки: 400 INVALID_ARGUMENT (пустое тело, причина короче 10 или длиннее 2000 символов, заявка ещё не пришла к результату), 401 UNAUTHORIZED, 404 NOT_FOUND (заявка не ваша или не существует), 409 CONFLICT (окно истекло или спор по заявке уже открыт).
DELETE /gw/v1/collect/{reference}/claim #
Отозвать свой открытый спор. Тела нет. Заявка возвращается к статусу, который был до спора.
200
{
"reference": "ord_01J8Z9QF3K4M5N6P7Q8R9S0T1U",
"status": "fulfilled"
}Ошибки: 401 UNAUTHORIZED, 404 NOT_FOUND (нет открытого спора по этой заявке).
GET /gw/v1/catalog/banks #
Справочник банков: расшифровка кода bank_code из реквизита. Read-only, без побочных эффектов. Параметров нет.
Список меняется редко — забирайте его раз в сутки, а не на каждую заявку. Новые банки площадка добавляет без выкатки; если в реквизите пришёл незнакомый bank_code, перечитайте справочник.
200
{
"banks": [
{
"code": "sberbank",
"name": "Сбер",
"logo_url": "https://api.ggwpayments.com/static/img/bank/sber.svg"
},
{
"code": "tinkoff",
"name": "Т-Банк",
"logo_url": "https://api.ggwpayments.com/static/img/bank/tinkoff.svg"
}
]
}| Поле | Тип | Описание |
|---|---|---|
code | string | Ровно то, что приходит в bank_code реквизита |
name | string | Название банка для плательщика |
logo_url | string | Абсолютный адрес логотипа. Чаще всего SVG; у новых банков бывает PNG, JPEG или WebP — тип смотрите в Content-Type ответа |
Порядок банков осмысленный: сначала те, на которые приём идёт чаще всего, дальше по алфавиту, в конце — недавно добавленные. Показывайте список как пришёл — сортировать заново не нужно.
Логотипы рисуются не все сразу: logo_url есть у каждого банка, но картинки по адресу может ещё не быть — держите свою заглушку на 404.
Один и тот же банк может прийти под двумя кодами (tinkoff и tbank), и в справочнике есть банки, на которые приём уже закрыт: старые реквизиты с такими кодами живы, и расшифровать их вы должны.
Ошибки: 401 UNAUTHORIZED, 429 RATE_LIMITED.