API для приёма оплат на своём сайте

Схема простая: вы создаёте платёж запросом к API, отправляете покупателя на полученный checkoutUrl, а после оплаты получаете вебхук. Всё остальное остаётся на нашей стороне — приём денег по СБП и картам, чек по агентской схеме, расчёт комиссии, автовыдача товара на игровой сервер по RCON или через плагин, выплаты на ваши реквизиты. Свою платёжную страницу писать не нужно, PCI DSS и реквизиты карт вас не касаются.

Что вы получаете

• Оплата стартует прямо из вашего интерфейса: корзина, кнопка, редирект на оплату, возврат на вашу страницу.
• Заказы связаны с вашей базой через externalOrderId и metadata — их видно и в статусе платежа, и в вебхуке.
• Каталог товаров и выдача остаются нашими: после оплаты воркер сам выполняет команды товара на игровом сервере и присылает события delivery.*.
• Песочница на тестовом ключе: полный цикл интеграции без реальных списаний.

Базовый адрес и формат

Все ручки живут под одним префиксом. Только HTTPS, тело и ответы — JSON в UTF-8. Суммы во всём API целые, в копейках (amountCents: 49900 = 499,00 ₽) — дробных рублей нет нигде, чтобы не терять копейки на округлении.

https://godonate.ru/v1/public

// Успех — всегда объект с полем data
{ "data": { "id": "…", "status": "PENDING" } }

// Ошибка — объект с полем error и машинным кодом
{ "error": { "code": "ITEMS_REQUIRED", "message": "Для этого магазина оплата возможна только по товарам (укажите items)." } }

Ориентируйтесь на error.code, а не на текст message: коды стабильны, а формулировки мы можем уточнять. Полный список — в разделе «Коды ошибок».

Кому API доступен

Доступ зависит от категории аккаунта, выбранной при регистрации. Ограничения не косметические: они следуют из того, как оформляется чек (54-ФЗ) и как мы отвечаем за приём платежей.

1. 01
   Выпустите API-ключ

   Кабинет → API-ключи → создать. Отметьте только нужные скоупы: для магазина на своём сайте обычно хватает payments:write, payments:read и products:read. Полный ключ показывается один раз — мы храним только его хеш. Для разработки создайте отдельный тестовый ключ (gd_test_…).
2. 02
   Добавьте домен возврата

   Адреса, на которые мы вернём покупателя после оплаты, работают только с домена из белого списка в кабинете. Пока домен не добавлен, запрос с returnUrl отвечает RETURN_URL_NOT_ALLOWED. Почему нельзя передавать любой адрес — в разделе «Возврат на сайт».
3. 03
   Создайте платёж

   Один POST-запрос с идентификатором магазина, суммой в копейках и позициями заказа. Свой номер заказа передавайте в externalOrderId — он же защищает от двойного списания при повторе запроса.
4. 04
   Отправьте покупателя на checkoutUrl

   В ответе приходит checkoutUrl — страница оплаты провайдера. Сделайте на неё редирект (или откройте в новом окне). Ссылка живёт 15 минут: по истечении срока платёж перестаёт быть оплачиваемым, для новой попытки создайте новый платёж — с новым externalOrderId.
5. 05
   Примите вебхук и выдайте заказ

   Заказ считается оплаченным по событию payment.captured, а не по возврату покупателя на сайт: браузер он может закрыть в любой момент. Проверьте подпись, ответьте 2xx, отметьте заказ у себя. В payload уже есть externalOrderId, items и metadata — второй запрос к API за деталями не нужен.

curl -X POST https://godonate.ru/v1/public/payments \
  -H "X-API-Key: gd_live_ваш_ключ" \
  -H "Content-Type: application/json" \
  -d '{
    "storeId": "8f14e45f-ceea-4e7a-9d40-1c9ec3b6a1de",
    "amountCents": 49900,
    "items": [
      { "productId": "b3c1f0a2-5d7e-4a91-8c22-7f0e5a1d9b64",
        "name": "VIP на 30 дней", "priceCents": 49900, "quantity": 1 }
    ],
    "customer": { "nickname": "Steve" },
    "externalOrderId": "shop-2026-000417",
    "returnUrl": "https://myserver.ru/order/417/done",
    "failureUrl": "https://myserver.ru/order/417/fail"
  }'

{
  "data": {
    "id": "9c8d7e6f-4b21-4c8a-93d5-2a7e11f0c3b8",
    "status": "PENDING",
    "amountCents": 49900,
    "feeCents": 1996,
    "netCents": 47904,
    "checkoutUrl": "https://securepay.example.ru/new/aBcD1234",
    "returnUrl": "https://myserver.ru/order/417/done?payment_id=9c8d7e6f-…&order_id=shop-2026-000417",
    "failureUrl": "https://myserver.ru/order/417/fail?payment_id=9c8d7e6f-…&order_id=shop-2026-000417"
  }
}

feeCents — наша комиссия приёма по вашей ставке, netCents — что попадёт на баланс (amountCents − feeCents). Ставка индивидуальна и доступна в GET /v1/public/merchant.

Заголовки

Ключ передаётся в X-API-Key. Поддерживается и Authorization: Bearer — но только для значений, начинающихся с gd_; любой другой Bearer-токен просто игнорируется. Если заданы оба заголовка, приоритет у X-API-Key.

# Основной вариант
curl https://godonate.ru/v1/public/merchant \
  -H "X-API-Key: gd_live_ваш_ключ"

# Bearer — для клиентов, которым удобнее стандартный заголовок
curl https://godonate.ru/v1/public/merchant \
  -H "Authorization: Bearer gd_live_ваш_ключ"

Боевой и тестовый ключ

Среда зашита в сам ключ, отдельного «переключателя песочницы» нет — по префиксу видно, куда уйдут деньги:

• gd_live_… — боевой ключ: платежи идут через реального провайдера, деньги списываются.
• gd_test_… — ключ песочницы: платёж создаётся через mock-провайдера, оплата подтверждается на тестовой странице, реального списания нет. Такой платёж помечен isTest: true — и в вебхуке это поле тоже приходит, чтобы тестовые заказы не смешались с боевыми.

Остальное в песочнице настоящее: те же адреса ручек, та же валидация, те же коды ошибок, те же вебхуки. Магазины и товары у тестового и боевого ключа общие — это один и тот же аккаунт.

Скоупы

Скоупы выбираются при выпуске ключа и не меняются потом — чтобы расширить права, выпустите новый ключ. Если у ключа нет нужного скоупа, ручка отвечает 403 API_KEY_FORBIDDEN и сообщает, какого именно скоупа не хватает.

Практика: для магазина на своём сайте достаточно ключа на запись платежей и чтение товаров. Ключ для аналитики или бухгалтерии делайте отдельным — только на чтение.

Отказы аутентификации

Лимиты частоты

• Общий лимит — 300 запросов в минуту с одного IP.
• Создание платежа (POST /v1/public/payments) — 30 запросов в минуту с одного IP, отдельным счётчиком.
• При атаке на платформу мы можем временно понизить потолки (до 60 и 10 запросов в минуту соответственно). Штатную интеграцию это не задевает, но обработчик 429 должен быть.

При превышении приходит 429 с кодом RATE_LIMIT_EXCEEDED, заголовком retry-after и счётчиками x-ratelimit-limit, x-ratelimit-remaining, x-ratelimit-reset. Повторяйте запрос не раньше, чем через указанное в retry-after время, и обязательно с тем же externalOrderId — тогда повтор не создаст второй платёж (см. «Идемпотентность»).

Платежи

POST https://godonate.ru/v1/public/payments

{
  "storeId": "8f14e45f-ceea-4e7a-9d40-1c9ec3b6a1de",
  "amountCents": 74800,
  "currency": "RUB",
  "items": [
    { "productId": "b3c1f0a2-5d7e-4a91-8c22-7f0e5a1d9b64",
      "name": "VIP на 30 дней", "priceCents": 49900, "quantity": 1 },
    { "productId": "1d2e3f4a-6b7c-48d9-90ea-5f6a7b8c9d01",
      "name": "Набор ресурсов", "priceCents": 12450, "quantity": 2 }
  ],
  "customer": { "nickname": "Steve", "email": "steve@example.com" },
  "externalOrderId": "shop-2026-000417",
  "returnUrl": "https://myserver.ru/order/417/done",
  "failureUrl": "https://myserver.ru/order/417/fail",
  "metadata": { "playerId": "1042", "source": "site" }
}

{
  "data": {
    "id": "9c8d7e6f-4b21-4c8a-93d5-2a7e11f0c3b8",
    "status": "PENDING",
    "amountCents": 74800,
    "feeCents": 2992,
    "netCents": 71808,
    "checkoutUrl": "https://securepay.example.ru/new/aBcD1234",
    "returnUrl": "https://myserver.ru/order/417/done?payment_id=9c8d7e6f-…&order_id=shop-2026-000417",
    "failureUrl": "https://myserver.ru/order/417/fail?payment_id=9c8d7e6f-…&order_id=shop-2026-000417"
  }
}

{
  "data": {
    "id": "9c8d7e6f-4b21-4c8a-93d5-2a7e11f0c3b8",
    "status": "SUCCEEDED",
    "amountCents": 74800,
    "currency": "RUB",
    "storeId": "8f14e45f-ceea-4e7a-9d40-1c9ec3b6a1de",
    "customerEmail": "steve@example.com",
    "customerNickname": "Steve",
    "comment": null,
    "externalOrderId": "shop-2026-000417",
    "createdAt": "2026-07-30T11:02:41.118Z",
    "capturedAt": "2026-07-30T11:03:27.544Z",
    "expiresAt": "2026-07-30T11:17:41.118Z"
  }
}

Аккаунт

{
  "data": {
    "id": "2b9c4d5e-7f80-4a1b-9c2d-3e4f5a6b7c8d",
    "slug": "myserver",
    "type": "IP",
    "status": "APPROVED",
    "legalName": "ИП Иванов Иван Иванович",
    "payinFeePercent": 4,
    "payoutFeePercent": 4,
    "balanceCents": 1842300
  }
}

Магазины

{
  "data": [
    {
      "id": "8f14e45f-ceea-4e7a-9d40-1c9ec3b6a1de",
      "slug": "myserver",
      "name": "MyServer — магазин",
      "description": "Привилегии и наборы",
      "status": "ACTIVE",
      "category": "MINECRAFT",
      "createdAt": "2026-05-14T08:21:03.402Z"
    }
  ]
}

POST https://godonate.ru/v1/public/stores

{
  "name": "MyServer — магазин",
  "description": "Привилегии и наборы",
  "category": "MINECRAFT",
  "brandColor": "#F5D800",
  "shopEnabled": true
}

PATCH https://godonate.ru/v1/public/stores/8f14e45f-ceea-4e7a-9d40-1c9ec3b6a1de

{
  "description": "Привилегии и наборы",
  "status": "PAUSED"
}

Товары

curl "https://godonate.ru/v1/public/products?storeId=8f14e45f-ceea-4e7a-9d40-1c9ec3b6a1de" \
  -H "X-API-Key: gd_live_ваш_ключ"

{
  "data": [
    {
      "id": "b3c1f0a2-5d7e-4a91-8c22-7f0e5a1d9b64",
      "storeId": "8f14e45f-ceea-4e7a-9d40-1c9ec3b6a1de",
      "name": "VIP на 30 дней",
      "slug": "vip-30",
      "description": "Доступ к /fly и цветной ник",
      "priceCents": 49900,
      "status": "ACTIVE",
      "externalId": "shop-item-8842",
      "createdAt": "2026-05-14T08:44:12.006Z"
    }
  ],
  "nextCursor": null
}

POST https://godonate.ru/v1/public/products

{
  "storeId": "8f14e45f-ceea-4e7a-9d40-1c9ec3b6a1de",
  "slug": "vip-30",
  "name": "VIP на 30 дней",
  "description": "Доступ к /fly и цветной ник",
  "priceCents": 49900,
  "deliveryType": "RCON_COMMAND",
  "deliveryCommands": ["lp user {nickname} parent addtemp vip 30d"],
  "requirePlayerOnline": false,
  "externalId": "shop-item-8842"
}

{
  "error": {
    "code": "UNSAFE_COMMAND",
    "message": "Команды выдачи отклонены по соображениям безопасности: «lp user {nickname} parent add admin» — выдача администраторских прав: привилегированная группа или право со звёздочкой",
    "commands": [
      {
        "command": "lp user {nickname} parent add admin",
        "reason": "privilege_escalation",
        "message": "выдача администраторских прав: привилегированная группа или право со звёздочкой"
      }
    ]
  }
}

PUT https://godonate.ru/v1/public/products/by-external/shop-item-8842

{
  "storeId": "8f14e45f-ceea-4e7a-9d40-1c9ec3b6a1de",
  "slug": "vip-30",
  "name": "VIP на 30 дней",
  "priceCents": 45900,
  "deliveryType": "RCON_COMMAND",
  "deliveryCommands": ["lp user {nickname} parent addtemp vip 30d"],
  "requirePlayerOnline": false
}

PATCH https://godonate.ru/v1/public/products/b3c1f0a2-5d7e-4a91-8c22-7f0e5a1d9b64

{
  "priceCents": 39900,
  "status": "ACTIVE"
}

Выплаты

{
  "data": [
    {
      "id": "5e6f7a8b-9c0d-41e2-83f4-5a6b7c8d9e0f",
      "status": "SUCCEEDED",
      "amountCents": 500000,
      "feeCents": 20000,
      "netCents": 480000,
      "method": "SBP_ACCOUNT",
      "createdAt": "2026-07-28T06:10:44.771Z",
      "succeededAt": "2026-07-28T09:32:08.219Z",
      "failedAt": null,
      "failureReason": null,
      "providerPayoutId": "e2c-88213004"
    }
  ]
}

Как это работает

• Оба поля необязательные. Не передали — покупатель после оплаты остаётся на наших страницах результата.
• Принимается только https. Домен должен быть в белом списке возвратных адресов в кабинете; его поддомены разрешаются автоматически (добавили myserver.ru — работает и shop.myserver.ru). Пока список пуст, любой адрес отклоняется.
• Проверка идёт до создания платежа: при неподходящем адресе приходит 400 RETURN_URL_NOT_ALLOWED с полем error.field (returnUrl или failureUrl), и платёж не создаётся вовсе — висящего PENDING не остаётся.
• При возврате мы дописываем в адрес два параметра: payment_id — наш идентификатор платежа, order_id — ваш externalOrderId, если он передавался. Свои query-параметры в адресе сохраняются, порт и фрагмент тоже.
• Итоговые адреса возврата приходят в ответе на создание платежа — в полях returnUrl и failureUrl.

// вы передали при создании платежа
"returnUrl": "https://myserver.ru/order/417/done"

// покупатель вернётся по адресу
https://myserver.ru/order/417/done?payment_id=9c8d7e6f-4b21-4c8a-93d5-2a7e11f0c3b8&order_id=shop-2026-000417

// если в адресе уже были параметры, наши просто добавятся
"returnUrl": "https://myserver.ru/pay?from=cart"
https://myserver.ru/pay?from=cart&payment_id=…&order_id=…

// свой payment_id в адресе мы перезапишем своим значением
"returnUrl": "https://myserver.ru/pay?payment_id=whatever"
https://myserver.ru/pay?payment_id=9c8d7e6f-…&order_id=…

Почему нельзя передать любой адрес

Это самый частый вопрос интеграторов, поэтому отвечаем подробно. Если бы мы редиректили на любой адрес из запроса, ручка создания платежа стала бы открытым редиректом на домене godonate.ru — а у платёжного сервиса это прямой инструмент фишинга.

Сценарий атаки простой. Мошенник берёт свой ключ, создаёт платёж с returnUrl на подставной сайт, копирующий наш вход в кабинет, и рассылает ссылку, которая начинается с настоящего домена платёжного сервиса. Жертва видит знакомый домен, проходит по цепочке и оказывается на клоне, где вводит пароль или платёжные данные. Формально скомпрометирован не наш сервер, но для пострадавшего это выглядит как «меня обманули через GoDonate», и разбираться будем мы.

Есть и вторая причина, менее очевидная. Возвратный адрес получает в параметрах payment_id и order_id, а браузер добавляет заголовок Referer с нашей страницы. Открытый редирект утекал бы этими данными на любой сторонний сайт, включая аналитику и рекламные сети чужих страниц.

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

Есть и третья, чисто практическая деталь: параметр payment_id в вашем адресе мы всегда перезаписываем своим значением. Иначе чужой человек мог бы подсунуть в ссылку идентификатор другого, уже оплаченного платежа, и ваш сайт сверил бы не тот заказ.

Практическое следствие: добавьте домен до первого боевого запроса. Обычно достаточно одной записи для сайта и одной для тестового стенда, а конкретные пути (/order/417/done) внутри домена можно менять свободно — проверяется только домен и схема. Ошибку RETURN_URL_NOT_ALLOWED в интеграции стоит логировать явно, иначе она выглядит как загадочный отказ платежа — см. «Коды ошибок».

Как это устроено

Из externalOrderId и идентификатора вашего API-ключа мы строим внутренний ключ идемпотентности вида api:<id ключа>:<externalOrderId> и держим на нём ограничение уникальности. Перед созданием платежа проверяем, нет ли уже записи с таким ключом. Если есть — новый платёж не создаётся, а в ответ уходит уже существующий.

• Первый запрос: 201 и полный объект платежа.
• Повтор с тем же externalOrderId и тем же заказом: 200, тот же id и тот же checkoutUrl, плюс флаг idempotent: true.
• Повтор с тем же externalOrderId, но другой суммой или другим составом позиций: 409 и код IDEMPOTENCY_KEY_REUSED. Мы не подменяем заказ молча — иначе покупатель оплатил бы старую сумму, а вы считали бы закрытым новый заказ. Изменился состав — нужен новый номер.
• Без externalOrderId защиты нет вообще: два запроса — два платежа и два списания.

{
  "data": {
    "id": "9c8d7e6f-4b21-4c8a-93d5-2a7e11f0c3b8",
    "status": "PENDING",
    "amountCents": 74800,
    "checkoutUrl": "https://securepay.example.ru/new/aBcD1234",
    "idempotent": true
  }
}

Обратите внимание: в идемпотентном ответе нет feeCents и netCents. Если они вам нужны, возьмите их из ответа на первый запрос или запросите GET /v1/public/payments/:id.

Как пользоваться

• Создайте заказ в своей базе и получите его номер до вызова API. Номер заказа и есть externalOrderId — не генерируйте его случайно на каждую попытку.
• При таймауте, сетевой ошибке или 429 повторяйте запрос с тем же значением и тем же телом. Это безопасно: второго списания не будет.
• Новую попытку оплаты того же заказа (истёк 15-минутный срок ссылки, покупатель ушёл) оформляйте как новый платёж с новым значением — например shop-2026-000417-2. Иначе вы получите старый, уже неоплачиваемый checkoutUrl.

Настройка

• Кабинет → Вебхуки → добавить адрес и выбрать события. Можно подписаться на * — тогда придут все.
• Секрет показывается один раз при создании эндпоинта. Он нужен только вашему серверу; храните его как пароль.
• Адрес должен быть публично доступен. Внутренние и служебные адреса (localhost, приватные сети) мы не вызываем — такая доставка блокируется и не повторяется.
• Есть кнопка тестового события и журнал доставок с кодами ответа — отлаживайте по ним, не дожидаясь реальных платежей.

Несколько проектов на одном аккаунте

У адреса есть проект (магазин). Выберите его при создании эндпоинта — и на этот адрес пойдут события только этого проекта; для второго проекта заведите второй адрес со своим секретом. Проект можно сменить в любой момент в карточке эндпоинта.

• Адрес без проекта (по умолчанию) получает события всех проектов сразу — как и раньше. Различать их можно по data.storeId, он есть во всех платёжных событиях, событиях выдачи и споров.
• События выплат (payout.*) относятся ко всему аккаунту, а не к проекту, поэтому приходят только на адреса без проекта.

Несколько сборов на одной странице

Когда проект один, а активностей несколько (сбор на технику, розыгрыш, отдельная рубрика), заводить второй проект незачем — хватит метки в ссылке. Добавьте к ссылке параметр ?p=метка (латиница, цифры, дефис, до 32 символов) и раздайте её зрителям под нужную активность:

https://godonate.ru/@nickname?p=beer     # сбор на пиво
https://godonate.ru/@nickname?p=pixel    # пиксельная стена
https://godonate.ru/@nickname            # обычная ссылка, метки нет

• Метка приезжает в каждом платёжном событии полем data.projectTag (null, если донат пришёл по обычной ссылке) и хранится у платежа — по ней же видно метку в карточке доната в кабинете.
• В карточке эндпоинта можно указать метку — тогда на этот адрес пойдут только донаты с ней. Донаты без метки на такой адрес не приходят, поэтому держите один адрес без метки как общий.
• Платежам, созданным через POST /v1/payments с API-ключом, метку можно передать полем projectTag в теле запроса.

Запрос от нас

Всегда POST с JSON-телом. Таймаут — 10 секунд, редиректы не выполняются: адрес должен отвечать сам, 301/302 считается неудачей.

POST /godonate/webhook HTTP/1.1
Content-Type: application/json
X-GoDonate-Event: payment.captured
X-GoDonate-Delivery-Id: 41f0a7c3-5b28-4d9e-8a10-6c7d8e9f0a1b
X-GoDonate-Signature: t=1785312208,v1=6f1c3a9d…
User-Agent: GoDonate-Webhooks/1.0

Тело

Оболочка одинаковая у всех событий: имя события, время формирования и полезная нагрузка в data. Для платежей в data уже есть всё, чтобы закрыть заказ без второго запроса к API.

{
  "event": "payment.captured",
  "createdAt": "2026-07-30T11:03:28.061Z",
  "data": {
    "id": "9c8d7e6f-4b21-4c8a-93d5-2a7e11f0c3b8",
    "storeId": "8f14e45f-ceea-4e7a-9d40-1c9ec3b6a1de",
    "projectTag": "beer",
    "amountCents": 74800,
    "currency": "RUB",
    "feeCents": 2992,
    "netCents": 71808,
    "status": "CAPTURED",
    "customerNickname": "Steve",
    "customerEmail": "steve@example.com",
    "comment": null,
    "capturedAt": "2026-07-30T11:03:27.544Z",
    "externalOrderId": "shop-2026-000417",
    "metadata": { "playerId": "1042", "source": "site" },
    "items": [
      { "productId": "b3c1f0a2-5d7e-4a91-8c22-7f0e5a1d9b64",
        "name": "VIP на 30 дней", "priceCents": 49900, "quantity": 1 }
    ],
    "isTest": false
  }
}

• externalOrderId — ваш номер заказа (null, если не передавали) и metadata — данные, которые вы приложили при создании платежа.
• items — оплаченные позиции с серверными названиями и ценами.
• isTest — платёж создан тестовым ключом. В боевом обработчике на таких заказах ничего выдавать не нужно.
• comment — сообщение плательщика, если оно было (для оплаты по товарам обычно null).

Проверка подписи

Считайте HMAC-SHA256 от сырого тела запроса с секретом эндпоинта в качестве ключа и сравните hex-результат со значением v1.

# Подписывается ТОЛЬКО тело запроса, как оно пришло, байт в байт.
# Ни timestamp, ни разделители, ни заголовки в подпись не входят.

v1 = HEX( HMAC_SHA256( key = webhook_secret, message = raw_body ) )

• Берите тело до разбора JSON. Если фреймворк уже распарсил его и вы соберёте строку обратно через сериализацию, порядок ключей и пробелы поменяются — подпись не сойдётся.
• Сравнивайте подписи функцией с постоянным временем работы: hash_equals в PHP, crypto.timingSafeEqual в Node.
• Подпись не сошлась — отвечайте 401 и ничего не делайте с заказом.

Ответ и повторы

• Успех — любой код 2xx. Всё остальное, включая таймаут и обрыв соединения, считается неудачей.
• Повторы: до 8 попыток, пауза удваивается начиная с 2 секунд, вся серия укладывается примерно в 4 минуты. Тело вашего ответа мы читаем и первые несколько тысяч символов сохраняем в журнал доставок — туда удобно писать причину отказа.
• Отвечайте 2xx сразу, как только записали событие себе, а долгую работу выносите в фон. Обработчик, который выдаёт товар синхронно и не успевает за 10 секунд, получит повтор и, если у вас нет дедупликации, выдаст товар дважды.
• Обработчик должен быть идемпотентным: ключ дедупликации — X-GoDonate-Delivery-Id либо пара «событие + data.id».

События

Новые события и новые поля в существующих мы добавляем без предупреждения — это совместимое изменение. Игнорируйте незнакомые event и лишние поля вместо строгой валидации схемы, и обновления вас не затронут.

{
  "error": {
    "code": "AMOUNT_MISMATCH",
    "message": "amountCents не совпадает с суммой позиций",
    "expectedCents": 74800
  }
}

У части ошибок есть дополнительные поля: expectedCents — ожидаемая сумма позиций, limitCents и usedCents — лимит приёма и сколько из него уже израсходовано.

Аутентификация и доступ

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

Остальное

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

<?php
// Создание платежа. Ключ — только на сервере, в код и в git не попадает.
$apiKey = getenv('GODONATE_API_KEY');

$order = [
    'storeId' => '8f14e45f-ceea-4e7a-9d40-1c9ec3b6a1de',
    'amountCents' => 49900,              // 499,00 ₽ — всегда копейки, целым числом
    'items' => [[
        'productId' => 'b3c1f0a2-5d7e-4a91-8c22-7f0e5a1d9b64',
        'name' => 'VIP на 30 дней',
        'priceCents' => 49900,
        'quantity' => 1,
    ]],
    'customer' => ['nickname' => $playerNick],
    // Номер заказа из своей БД: он же ключ идемпотентности при повторе запроса.
    'externalOrderId' => 'shop-' . $orderId,
    'returnUrl' => 'https://myserver.ru/order/' . $orderId . '/done',
    'failureUrl' => 'https://myserver.ru/order/' . $orderId . '/fail',
];

$ch = curl_init('https://godonate.ru/v1/public/payments');
curl_setopt_array($ch, [
    CURLOPT_POST => true,
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_TIMEOUT => 20,
    CURLOPT_HTTPHEADER => [
        'X-API-Key: ' . $apiKey,
        'Content-Type: application/json',
    ],
    CURLOPT_POSTFIELDS => json_encode($order, JSON_UNESCAPED_UNICODE),
]);

$raw = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$res = json_decode($raw, true);

if ($status !== 201 && $status !== 200) {
    // Ориентируемся на code, а не на текст сообщения.
    $code = $res['error']['code'] ?? 'UNKNOWN';
    error_log('godonate: order ' . $orderId . ' failed with ' . $code);
    exit('Не удалось создать платёж');
}

// 200 с флагом idempotent означает, что этот заказ уже оплачивался ранее —
// ссылка та же самая, второго списания не будет.
header('Location: ' . $res['data']['checkoutUrl']);

Приём вебхука и проверка подписи

Ключевая часть — сравнение подписей. Ниже в обоих примерах используется сравнение с постоянным временем работы, и это не перестраховка.

<?php
// Обработчик вебхука: /godonate/webhook
$secret = getenv('GODONATE_WEBHOOK_SECRET');

// ВАЖНО: берём тело как есть. Если распарсить JSON и собрать строку обратно,
// изменятся пробелы и порядок ключей — подпись не сойдётся никогда.
$body = file_get_contents('php://input');
$header = $_SERVER['HTTP_X_GODONATE_SIGNATURE'] ?? '';

// Заголовок: t=<unix>,v1=<hex>
$parts = [];
foreach (explode(',', $header) as $chunk) {
    $kv = explode('=', trim($chunk), 2);
    if (count($kv) === 2) {
        $parts[$kv[0]] = $kv[1];
    }
}

$timestamp = (int) ($parts['t'] ?? 0);
$received = $parts['v1'] ?? '';

// Подписывается ТОЛЬКО тело запроса: ни t, ни разделителей в HMAC нет.
$expected = hash_hmac('sha256', $body, $secret);

// hash_equals, а не ===: сравнение с постоянным временем работы.
// Обычное сравнение строк выходит на первом различающемся байте, поэтому по
// времени ответа можно побайтово угадывать правильную подпись (timing attack).
// hash_equals всегда проходит всю строку и такой утечки не даёт.
if (!hash_equals($expected, $received)) {
    http_response_code(401);
    exit;
}

// Защита от повторного проигрывания старого запроса.
if (abs(time() - $timestamp) > 300) {
    http_response_code(401);
    exit;
}

$event = json_decode($body, true);

if ($event['event'] === 'payment.captured') {
    $data = $event['data'];

    // Тестовые платежи в боевом обработчике игнорируем.
    if (!empty($data['isTest'])) {
        http_response_code(200);
        exit;
    }

    // Дедупликация: один и тот же вебхук может прийти повторно.
    // Ключ — id доставки или пара «событие + id платежа».
    $deliveryId = $_SERVER['HTTP_X_GODONATE_DELIVERY_ID'] ?? $data['id'];
    if (already_processed($deliveryId)) {
        http_response_code(200);
        exit;
    }

    // externalOrderId уже в payload — второй запрос к API не нужен.
    mark_order_paid($data['externalOrderId'], $data['amountCents']);
    remember_delivery($deliveryId);
}

// Отвечаем 2xx сразу; тяжёлую работу — в фон, иначе поймаем повтор по таймауту.
http_response_code(200);

Что проверить перед запуском

• Ключ читается из переменных окружения, а не лежит в репозитории и не отдаётся в браузер.
• Тело вебхука берётся сырым (php://input, express.raw) — до разбора JSON.
• Обработчик отвечает 2xx быстро, а выдачу и письма делает в фоне.
• Повторный вебхук с тем же X-GoDonate-Delivery-Id не выдаёт товар второй раз.
• Заказы с isTest: true в боевом контуре игнорируются.
• Домены returnUrl и failureUrl добавлены в белый список в кабинете.

Полезные запросы для отладки

Если интеграция «не работает», начните с этого запроса: он показывает, что ключ жив, скоуп на месте и аккаунт в рабочем статусе.

curl -i https://godonate.ru/v1/public/merchant -H "X-API-Key: $GODONATE_API_KEY"