GGWPAY docs

Приём средств #

Заголовки — в «Авторизации». Статусы — в «Статусах».

POST /gw/v1/collect #

Создать заявку на приём.

ПолеТипОбяз.Описание
merchant_referencestringдаВаш номер заказа. Он же ключ идемпотентности
amountint64да*Сумма целыми рублями, > 0: 7000 = 7 000 ₽
amount_minorint64да*Та же сумма в копейках: 700000 = 7 000 ₽
currencystringдаВалюта заявки, например RUB
methodstringдаC2C (карта) или SBP, регистр не важен. Другое значение — 400 с текстом method must be SBP or C2C
metadataobjectнетПроизвольный JSON. Хранится, в ответах не возвращается

\* Сумма присылается ОДНИМ из двух полей. Оба разом — 400: разойдись они, любой наш выбор был бы неверным для половины случаев. amount — целое число, дробных сумм в контракте нет.

Поля direction нет: путь задаёт направление. Неизвестные поля в теле — 400, а не молчаливое игнорирование.

Запрос

json
{
  "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, отдельно запрашивать курс по сделке не нужно.

json
{
  "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

json
{
  "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" — свободных реквизитов под неё не было. Ждать дольше незачем, создавайте новую.

Формат заявки #

ПолеТипКогда естьОписание
referencestringвсегдаНаш номер заявки (ord_...)
merchant_referencestringесли передавалиВаш номер заказа
statusstringвсегдаПубличный статус
amountint64всегдаСумма целыми рублями
amount_minorint64всегдаСумма в минимальных единицах. После закрытия спора на фактическую сумму — фактическая
original_amount, original_amount_minorint64только если сумма меняласьИсходная сумма заявки — та, с которой вы её создали. Есть, только когда по спору заявка закрыта на другую сумму
currencystringвсегдаВалюта заявки
methodstringвсегдаСпособ оплаты
ratestringесли курс зафиксированКурс этой заявки: сколько единиц currency за 1 USDT. Фиксируется при создании и дальше не меняется; по нему заявка зачислится на баланс. Строкой — разбирайте десятичным типом, не float
rate_e8int64вместе с rateТот же курс целым числом: rate × 10^8
decline_reasonstringу части declinedСвободный текст причины, не код. Может быть пустым
requisiteobjectтолько awaiting_paymentКуда платить, см. ниже
created_atdatetimeвсегдаСоздание заявки
updated_atdatetimeвсегдаПоследнее изменение
settled_atdatetimeтолько fulfilledМомент подтверждения оплаты. У declined / lapsed / reversed поля нет
disputeobjectтолько если вы открывали спор по заявкеВаш последний спор по заявке и переписка с поддержкой, см. Переписка по спору

metadata в ответе не возвращается.

requisite #

ПолеТипКогда естьОписание
numberstringвсегдаКуда платить. Номер телефона при method = SBP, номер карты при C2C
holder_namestringвсегдаИмя получателя. При SBP плательщик увидит его в своём банке и сверит
bank_codestringвсегдаКод банка получателя. Название и логотип по коду — справочник банков
expires_atdatetimeесли известенДо какого момента реквизит точно действителен

Одно поле 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).

ПолеТипОбяз.Описание
reasonstringдаПричина, 10–2000 символов после схлопывания пробелов

Запрос

json
{ "reason": "деньги списаны, но заявка отмечена как неоплаченная" }

201

json
{
  "reference": "ord_01J8Z9QF3K4M5N6P7Q8R9S0T1U",
  "status": "disputed",
  "reason": "деньги списаны, но заявка отмечена как неоплаченная"
}

С этого момента GET по заявке возвращает disputed — отдельного ресурса спора нет.

Переписка по спору #

Поддержка отвечает на спор письменно. Ответ приходит в поле dispute ответа GET /gw/v1/collect/{reference} и виден в кабинете мерчанта (раздел «Споры»). Там же можно ответить поддержке. Поле есть, только если по заявке открывали спор вы; споры исполнителя сюда не попадают.

ПолеТипОписание
dispute.idstringНомер спора (dsp_...)
dispute.statusstringopen — разбираем, resolved — решён, withdrawn — закрыт без решения. В чью пользу решили, видно по status самой заявки
dispute.opened_atdatetimeКогда открыт спор
dispute.reasonstringВаша причина спора
dispute.messages[]arrayПереписка по порядку. Пустой массив — ответов ещё не было
dispute.messages[].fromstringplatform — ответ поддержки, merchant — ваше сообщение из кабинета
dispute.messages[].textstringТекст сообщения
dispute.messages[].atdatetimeКогда отправлено
json
{
  "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 и поменялась только сумма.
json
{
  "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

json
{
  "reference": "ord_01J8Z9QF3K4M5N6P7Q8R9S0T1U",
  "status": "fulfilled"
}

Ошибки: 401 UNAUTHORIZED, 404 NOT_FOUND (нет открытого спора по этой заявке).

GET /gw/v1/catalog/banks #

Справочник банков: расшифровка кода bank_code из реквизита. Read-only, без побочных эффектов. Параметров нет.

Список меняется редко — забирайте его раз в сутки, а не на каждую заявку. Новые банки площадка добавляет без выкатки; если в реквизите пришёл незнакомый bank_code, перечитайте справочник.

200

json
{
  "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"
    }
  ]
}
ПолеТипОписание
codestringРовно то, что приходит в bank_code реквизита
namestringНазвание банка для плательщика
logo_urlstringАбсолютный адрес логотипа. Чаще всего SVG; у новых банков бывает PNG, JPEG или WebP — тип смотрите в Content-Type ответа

Порядок банков осмысленный: сначала те, на которые приём идёт чаще всего, дальше по алфавиту, в конце — недавно добавленные. Показывайте список как пришёл — сортировать заново не нужно.

Логотипы рисуются не все сразу: logo_url есть у каждого банка, но картинки по адресу может ещё не быть — держите свою заглушку на 404.

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

Ошибки: 401 UNAUTHORIZED, 429 RATE_LIMITED.