Вебхуки

Вебхуки для уведомлений о событиях.

Настройка:

1. Перейдите в Панель автора → Настройки (меню с тремя точками) → раздел API-ключи

2. Сгенерируйте API-ключ, если ещё не сделали

3. Укажите URL вашего вебхука в настройках

Проверка подписи: Каждый запрос содержит заголовок trbt-signature с HMAC-SHA256 подписью тела запроса, подписанной вашим API-ключом.

Повторные попытки: При ошибке доставки система повторяет отправку с экспоненциальной задержкой в течение ~24 часов: 5мин, 15мин, 30мин, 1ч, 2ч, 4ч, 8ч, 8ч.

Заказ в магазине

Уведомление об оплате заказа в магазине

Payload

application/json

namestring · enumRequiredExample: shop_orderPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

statusstringOptionalExample: ok

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "shop_order",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "fee": 8000,
    "status": "paid",
    "email": "[e-mail]",
    "customerId": "user_12345",
    "isRecurrent": false,
    "period": "monthly",
    "paymentToken": "660e8400-e29b-41d4-a716-446655440001",
    "cardLast4": "4242",
    "cardBrand": "VISA",
    "starsAmount": 0,
    "onlyStars": false,
    "firstPeriodAmount": 50000,
    "memberStatus": "active",
    "memberExpiresAt": "2025-12-13T15:04:05Z"
  }
}

Ошибка списания по заказу магазина

Уведомление об ошибке списания по рекуррентному заказу магазина. Отправляется после каждой неудачной попытки списания. Система делает до 3 попыток (1 исходная + 2 повторных) в течение ~8 часов, после чего рекуррентный заказ отменяется.

Отправляется только для рекуррентных оплат картой. Подписки, оплаченные напрямую Telegram Stars (без привязанной карты), продлеваются самим Telegram — если Telegram не продлевает подписку, она отменяется с cancelReason="stars_subscription_expired" через shop_order_cancelled, без предшествующих событий shop_order_charge_failed. То же касается OnlyStars-подписок «карта → Stars», когда покупатель отменил подписку на стороне Telegram: предварительное списание с карты пропускается, а подписка отменяется с cancelReason="stars_subscription_expired" (без shop_order_charge_failed).

Время списания относительно memberExpiresAt:

• Оплата картой: списание происходит строго после memberExpiresAt, обычно в течение нескольких минут.
• OnlyStars (карта → Stars): списание происходит до 72 часов до memberExpiresAt для предварительной покупки Stars для продления через Telegram.

Payload

application/json

namestring · enumRequiredExample: shop_order_charge_failedPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

statusstringOptionalExample: ok

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "shop_order_charge_failed",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "period": "monthly",
    "chargeRetries": 1,
    "email": "[e-mail]",
    "customerId": "user_12345",
    "isRecurrent": true,
    "starsAmount": 0,
    "onlyStars": false,
    "firstPeriodAmount": 50000,
    "memberStatus": "active",
    "memberExpiresAt": "2025-12-13T15:04:05Z"
  }
}

Успешное списание по заказу магазина

Уведомление об успешном списании по рекуррентному заказу магазина.

Payload

application/json

namestring · enumRequiredExample: shop_order_charge_successPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

statusstringOptionalExample: ok

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "shop_order_charge_success",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "period": "monthly",
    "email": "[e-mail]",
    "customerId": "user_12345",
    "isRecurrent": true,
    "starsAmount": 0,
    "onlyStars": false,
    "firstPeriodAmount": 50000,
    "memberStatus": "active",
    "memberExpiresAt": "2025-12-13T15:04:05Z"
  }
}

Отмена заказа магазина

Уведомление об отмене рекуррентной подписки на заказ магазина. Триггер указан в поле cancelReason payload:

• cancelled_by_seller — явная отмена через Mini App / публичный API (POST /api/v1/shop/orders/{orderUuid}/cancel).
• charge_failed — рекуррентное списание не удалось после всех повторов.
• payment_method_expired — сохранённая карта больше непригодна.
• stars_subscription_expired — подписка Telegram Stars перестала продлеваться на стороне Telegram. Покрывает как подписки чистыми Stars (без привязанной карты; продление — на стороне Telegram), так и OnlyStars-подписки «карта → Stars», у которых покупатель отменил подписку на стороне Telegram (предварительное списание с карты тогда прекращается).
• seller_unavailable — продавец больше не может принимать платежи.
• last_charge_refunded — была возвращена последняя по времени создания транзакция покупателя по заказу магазина (через любой канал: банковский chargeback, возврат Telegram Stars, ручной возврат продавцом). Возврат более старой транзакции при наличии более новой подписку НЕ отменяет. Это событие отправляется в дополнение к shop_order_refunded для той же транзакции.

Payload

application/json

namestring · enumRequiredExample: shop_order_cancelledPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

statusstringOptionalExample: ok

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "shop_order_cancelled",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "period": "monthly",
    "cancelReason": "cancelled_by_seller",
    "email": "[e-mail]",
    "customerId": "user_12345",
    "isRecurrent": true,
    "starsAmount": 0,
    "onlyStars": false,
    "firstPeriodAmount": 50000,
    "memberStatus": "cancelled",
    "memberExpiresAt": "2025-12-13T15:04:05Z"
  }
}

Возврат по заказу магазина

Уведомление о возврате средств по транзакции заказа магазина. Срабатывает для разовых и рекуррентных заказов, независимо от триггера возврата (банковский chargeback, возврат Telegram Stars, ручной возврат продавцом).

Жизненный цикл. Ручной возврат, инициированный продавцом, сначала отправляет событие со status=initiated, затем — второе со status=completed, когда провайдер подтвердит операцию. Банковские chargeback'и и возвраты Telegram Stars пропускают шаг initiated и сразу отправляют status=completed. Получатели должны идемпотентно обрабатывать два события с одинаковым transactionId (по одному на каждый статус).

Рекуррентные заказы — отмена при возврате последней транзакции. Если возвращаемая transactionId — это последняя по времени создания транзакция покупателя по рекуррентной подписке, после этого события отправляется shop_order_cancelled с cancelReason="last_charge_refunded". Возврат более старой транзакции (когда более новое рекуррентное списание ещё существует) НЕ отменяет подписку.

Payload

application/json

namestring · enumRequiredExample: shop_order_refundedPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

statusstringOptionalExample: ok

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "shop_order_refunded",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "transactionId": 12345,
    "amount": 100000,
    "currency": "rub",
    "status": "initiated",
    "refundedAt": "2025-03-20T01:15:58.33246Z",
    "customerId": "user_12345",
    "isRecurrent": false,
    "period": "onetime",
    "starsAmount": 0,
    "onlyStars": false,
    "firstPeriodAmount": 50000,
    "memberStatus": "active",
    "memberExpiresAt": "2025-12-13T15:04:05Z"
  }
}

Ошибка оплаты заказа магазина

Уведомление об ошибке первичной оплаты заказа магазина (CIT) (например, карта отклонена, недостаточно средств). Отправляется для разовых платежей и для первого списания рекуррентного заказа. Сумма, которую попытались списать, указана в минимальных единицах валюты — firstPeriodAmount, если у рекуррентного заказа задано переопределение первого периода, иначе amount.

Payload

application/json

namestring · enumRequiredExample: shop_order_payment_failedPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

statusstringOptionalExample: ok

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "shop_order_payment_failed",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "errorCode": "payment_declined",
    "errorMessage": "Карта отклонена эмитентом",
    "email": "[e-mail]",
    "customerId": "user_12345",
    "starsAmount": 0,
    "onlyStars": false,
    "firstPeriodAmount": 50000
  }
}

Покупатель оплатил инвойс

Покупатель оплатил инвойс. Событие приходит сразу после оплаты, до вебхука shop_order.

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

Payload

application/json

namestring · enumRequiredExample: shop_order_payment_receivedPossible values:

created_atstring · date-timeRequired

Время создания события

Example: 2025-03-20T01:15:58.33246Z

sent_atstring · date-timeRequired

Время отправки события

Example: 2025-03-20T01:15:58.542279448Z

Responses

200

Вебхук успешно обработан

application/json

statusstringOptionalExample: ok

400

Некорректные данные вебхука

401

Неверная подпись вебхука

Payload

{
  "name": "shop_order_payment_received",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "period": "monthly",
    "starsAmount": 150,
    "onlyStars": true,
    "starsPurchaseId": 4711,
    "email": "[e-mail]",
    "customerId": "user_12345"
  }
}