Ctrlk
Главная страница
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Методы

Методы для управления заказами и подписками.

Способы оплаты

Доступные способы оплаты зависят от конфигурации заказа:

Стандартные заказы (onlyStars: false):

Способ
Доступность

Банковские карты

Всегда доступны

СБП

Доступен, когда у продавца включён СБП (можно включить по запросу в поддержке Tribute). Только для разовых заказов (period: "onetime")

Wallet Pay (TON)

Всегда доступен

Telegram Stars

Только при starsAmount > 0, период onetime или monthly, и tokenCharging выключен

Заказы только за Stars (onlyStars: true, tokenCharging выключен, только периоды onetime и monthly):

Способ
Доступность

Telegram Stars

Всегда доступен

Банковские карты

Оплата картой через Stars. Доступна когда starsAmount >= 50

Примечание: Pix и PayPal недоступны для заказов магазина.

Список магазинов

get

Возвращает активные магазины аутентифицированного пользователя, отсортированные по дате создания (от старого к новому). Неактивные магазины в списке не возвращаются. Для пользователя с одним магазином всегда вернётся ровно один элемент; владельцы нескольких магазинов используют этот метод, чтобы получить shopId для остальных эндпоинтов через ?shopId=.

Authorizations
Api-KeystringRequired

API ключ для аутентификации.

Responses
200

Успешный ответ

application/json
idinteger · uint64Required

ID магазина

Example: 1
userIdintegerRequired

ID владельца магазина

Example: 123
namestringRequired

Название магазина

Example: Мой магазин
linkstringRequired

Ссылка/slug магазина

Example: myshop
callbackUrlstring · uriRequired

URL вебхука для уведомлений о заказах

Example: https://example.com/webhook
recurrentbooleanRequired

Доступны ли рекуррентные платежи

Example: true
onlyStarsbooleanRequired

Принимаются ли только платежи через Telegram Stars

Example: false
tokenChargingbooleanRequired

Включены ли списания по токенам (merchant-initiated)

Example: false
statusinteger · enumRequired

Статус магазина (0 = неактивен, 1 = активен)

Example: 1Possible values:
get/shops
GET /api/v1/shops HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

[
  {
    "id": 1,
    "userId": 123,
    "name": "Мой магазин",
    "link": "myshop",
    "callbackUrl": "https://example.com/webhook",
    "recurrent": true,
    "onlyStars": false,
    "tokenCharging": false,
    "status": 1
  }
]

Получить магазин

get

Возвращает информацию о магазине аутентифицированного пользователя. Возвращаются только активные магазины. Передайте ?shopId= для конкретного магазина; без параметра возвращается самый старый активный магазин. Явный shopId неактивного (но принадлежащего пользователю) магазина возвращает error_shop_inactive.

Authorizations
Api-KeystringRequired

API ключ для аутентификации.

Query parameters
shopIdinteger · uint64Optional

ID активного магазина. По умолчанию — самый старый активный магазин пользователя.

Example: 1
Responses
200

Успешный ответ

application/json
idinteger · uint64Required

ID магазина

Example: 1
userIdintegerRequired

ID владельца магазина

Example: 123
namestringRequired

Название магазина

Example: Мой магазин
linkstringRequired

Ссылка/slug магазина

Example: myshop
callbackUrlstring · uriRequired

URL вебхука для уведомлений о заказах

Example: https://example.com/webhook
recurrentbooleanRequired

Доступны ли рекуррентные платежи

Example: true
onlyStarsbooleanRequired

Принимаются ли только платежи через Telegram Stars

Example: false
tokenChargingbooleanOptional

Включены ли списания по токенам (merchant-initiated)

Example: false
statusinteger · enumRequired

Статус магазина (0 = неактивен, 1 = активен)

Example: 1Possible values:
get/shop
GET /api/v1/shop HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "id": 1,
  "userId": 123,
  "name": "Мой магазин",
  "link": "myshop",
  "callbackUrl": "https://example.com/webhook",
  "recurrent": true,
  "onlyStars": false,
  "tokenCharging": false,
  "status": 1
}

Получить заказы магазина

get

Возвращает список заказов магазина, отсортированных по убыванию ID (сначала новые). Опционально можно фильтровать по диапазону дат. Передайте ?shopId= для конкретного магазина; без параметра используется самый старый магазин.

Authorizations
Api-KeystringRequired

API ключ для аутентификации.

Query parameters
shopIdinteger · uint64Optional

ID магазина, из которого читать заказы. По умолчанию — самый старый магазин пользователя.

Example: 1
dateFromstring · dateOptional

Начальная дата (включительно) в UTC, формат yyyy-mm-dd

Example: 2026-01-01
dateTostring · dateOptional

Конечная дата (включительно) в UTC, формат yyyy-mm-dd

Example: 2026-12-31
Responses
200

Успешный ответ

application/json
uuidstring · uuidRequired

UUID заказа

Example: 550e8400-e29b-41d4-a716-446655440000
shopIdinteger · uint64Required

ID магазина, к которому относится заказ

Example: 1
amountinteger · int64Required

Сумма заказа в минимальных единицах валюты (центы/копейки)

Example: 100000
currencystring · enumRequired

Код валюты (в нижнем регистре)

Example: rubPossible values:
titlestringRequired

Название заказа (макс 100 символов UTF-16)

Example: Товар X
descriptionstringRequired

Описание заказа (макс 300 символов UTF-16)

Example: Подробное описание товара
statusstring · enumRequired

Статус заказа. prepaid опциональный (включается по запросу продавца): card-to-Stars заказы, где Stars зачислены покупателю, но он ещё не подтвердил списание. Продавцы без включения видят pending.

Отказ по карте статус не меняет — заказ остаётся в pending и доступен к оплате.

Example: paidPossible values:
emailstring · emailOptional

Email клиента (опционально)

Example: customer@example.com
successUrlstring · uriRequired

URL редиректа при успешной оплате

Example: https://shop.com/success
failUrlstring · uriRequired

URL редиректа при неудачной оплате

Example: https://shop.com/fail
paymentUrlstring · uri · nullableRequired

Веб-URL для завершения оплаты клиентом в браузере. null для заказов OnlyStars — их можно оплатить только внутри Telegram через webappPaymentUrl.

Example: https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000
webappPaymentUrlstring · uriOptional

URL для оплаты через Telegram WebApp

Example: https://t.me/tribute/app?startapp=b2RK4mN
createdAtstring · date-timeRequired

Время создания заказа в формате ISO 8601

Example: 2025-11-13T15:04:05Z
commentstringOptional

Комментарий к заказу (опционально)

Example: Особые пожелания
periodstring · enumRequired

Период оплаты для рекуррентных заказов

Example: onetimePossible values:
memberStatusstring · enumOptional

Статус рекуррентной подписки (только для рекуррентных заказов)

Example: activePossible values:
memberExpiresAtstring · date-timeOptional

Дата окончания рекуррентной подписки в формате ISO 8601 (только для рекуррентных заказов)

Example: 2025-12-13T15:04:05Z
memberInTrialbooleanOptional

True, пока активный участник ещё находится в бесплатном пробном периоде (подписан, но списание не произошло). Присутствует всегда, когда есть участник — false для участников без пробного периода, после конвертации пробного периода или отмены подписки. Отсутствует, только если участника нет.

Example: true
memberTrialStartedAtstring · date-timeOptional

Начало пробного периода (момент подписки) в формате ISO 8601. Присутствует у активного участника с пробным периодом — и во время пробного периода, и после конвертации (тогда историческое значение). Отсутствует для не-пробных и отменённых участников.

Example: 2025-12-13T15:04:05Z
memberTrialEndsAtstring · date-timeOptional

Дата окончания пробного периода / первого списания в формате ISO 8601. Присутствует у активного участника с пробным периодом — и во время пробного периода, и после конвертации (тогда историческое значение). Отсутствует для не-пробных и отменённых участников.

Example: 2025-12-20T15:04:05Z
lastPaidTransactionAtstring · date-time · nullableOptional

Дата последней оплаченной транзакции в формате ISO 8601. Null, если транзакций нет.

Example: 2025-12-13T15:04:05Z
starsAmountinteger · int64Optional

Фиксированная сумма в Telegram Stars (0 если не задано)

Example: 0
onlyStarsbooleanOptional

Принимает ли заказ только оплату через Telegram Stars

Example: false
firstPeriodAmountinteger · int64 · nullableOptional

Цена первого периода в минимальных единицах валюты. Если задана — первое списание прошло по этой сумме, последующие списываются по amount. Отсутствует, если у заказа нет переопределения первого периода.

Example: 50000
sendEmailbooleanOptional

Отправляется ли покупателю чек на email после успешной оплаты (наследуется от магазина при создании)

Example: false
get/shop/orders
GET /api/v1/shop/orders HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "shopId": 1,
    "amount": 100000,
    "currency": "rub",
    "title": "Товар X",
    "description": "Подробное описание товара",
    "status": "paid",
    "email": "customer@example.com",
    "successUrl": "https://shop.com/success",
    "failUrl": "https://shop.com/fail",
    "paymentUrl": "https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000",
    "webappPaymentUrl": "https://t.me/tribute/app?startapp=b2RK4mN",
    "createdAt": "2025-11-13T15:04:05Z",
    "comment": "Особые пожелания",
    "period": "onetime",
    "memberStatus": "active",
    "memberExpiresAt": "2025-12-13T15:04:05Z",
    "memberInTrial": true,
    "memberTrialStartedAt": "2025-12-13T15:04:05Z",
    "memberTrialEndsAt": "2025-12-20T15:04:05Z",
    "lastPaidTransactionAt": "2025-12-13T15:04:05Z",
    "starsAmount": 0,
    "onlyStars": false,
    "firstPeriodAmount": 50000,
    "sendEmail": false,
    "image": {
      "id": 123,
      "path": "https://cdn.example.com/image.jpg",
      "thumbnail": "text",
      "width": 800,
      "height": 600,
      "fileType": "image"
    }
  }
]

Создать заказ в магазине

post

Создает новый заказ в магазине и возвращает ссылку для оплаты клиенту. Поддерживает разовые и рекуррентные платежи.

Authorizations
Api-KeystringRequired

API ключ для аутентификации.

Body
shopIdinteger · uint64Optional

ID магазина для создания заказа. Если не указан, заказ создаётся для первого (самого раннего) магазина аутентифицированного пользователя.

Example: 1
amountinteger · int64Optional

Сумма заказа в минимальных единицах валюты (центы для EUR/USD, копейки для RUB). Обязательна для обычных магазинов. Игнорируется для магазинов OnlyStars — заказ создаётся с amount=0, оплата идёт в Telegram Stars (через starsAmount). currency обязательна в любом случае.

Example: 100000
currencystring · enumRequired

Код валюты (в нижнем регистре). Обязательна для любого заказа, включая магазины OnlyStars — она задаёт фиатную цену на инвойсе (для OnlyStars выводится из starsAmount).

Example: rubPossible values:
titlestringRequired

Название заказа (обязательно, макс 100 символов UTF-16). Ведущие/замыкающие пробелы обрезаются; значение из одних пробелов отклоняется.

Example: Товар X
descriptionstringRequired

Описание заказа (обязательно, макс 300 символов UTF-16). Ведущие/замыкающие пробелы обрезаются; значение из одних пробелов отклоняется.

Example: Подробное описание товара
successUrlstring · uriOptional

URL редиректа при успешной оплате (опционально, должен быть валидным https:// URL)

Example: https://shop.com/success
failUrlstring · uriOptional

URL редиректа при неудачной оплате (опционально, должен быть валидным https:// URL)

Example: https://shop.com/fail
emailstring · emailOptional

Email клиента (опционально, валидируется если указан). Если задан, покупатель не вводит email при оплате (адрес остаётся на сервере). Чек отправляется только если у магазина sendEmail=true.

Example: customer@example.com
commentstringOptional

Комментарий к заказу (опционально)

Example: Особые пожелания
customerIdstring · max: 256Optional

Уникальный идентификатор клиента

Example: user_12345
periodstring · enumOptional

Период оплаты. По умолчанию "onetime". Рекуррентные периоды требуют shop.recurrent = true. Магазины с OnlyStars поддерживают только "onetime" и "monthly" (подписки Telegram Stars — 30-дневные циклы).

Default: onetimeExample: monthlyPossible values:
starsAmountinteger · int64 · min: 1Optional

Фиксированная сумма в Telegram Stars. Обязательна для магазинов OnlyStars. При установке включает оплату Stars. Поддерживается только для периодов onetime или monthly. Для ежемесячных заказов создаёт подписку Telegram Stars.

Example: 50
imageUrlstring · uriOptional

URL изображения для заказа. Будет отображаться в счетах и транзакциях Telegram Stars. При указании изображение загружается и сохраняется; если изображение с таким URL уже существует, оно используется повторно.

Example: https://example.com/product-image.jpg
firstPeriodAmountinteger · int64Optional

Цена первого периода в минимальных единицах валюты (центы/копейки). Если указана — первое списание идёт по этой сумме, последующие — по amount. Может быть меньше (промо) или больше amount. Лимиты по валюте те же, что и для amount. Должна отличаться от amount.

Допустима только при period != onetime. Не допускается для магазинов OnlyStars. Взаимоисключима со starsAmount: заказ может предлагать либо фиатное переопределение первого периода, либо фиксированную цену в Stars, но не одновременно. Платформа применяет переданное значение как есть, без дедупа по покупателю.

Example: 50000
trialPeriodstring · enumOptional

Даёт бесплатный пробный период покупателям, которые платят картой. Во время пробного периода списание не происходит; по его окончании первое списание — firstPeriodAmount (если задан), иначе amount, а каждый последующий период — amount.

Только для карт: СБП, Wallet и Telegram Stars игнорируют пробный период и списывают как обычно. Допустимо только при period != onetime. Не допускается для магазинов OnlyStars. Совместимо с firstPeriodAmount. Повторный пробный период для того же заказа не предоставляется.

Example: seven_daysPossible values:
Responses
200

Заказ успешно создан. Возвращается полный объект заказа — той же формы, что и GET /shop/orders/{orderUuid}. paymentUrl равен null для заказов OnlyStars.

application/json
uuidstring · uuidRequired

UUID заказа

Example: 550e8400-e29b-41d4-a716-446655440000
shopIdinteger · uint64Required

ID магазина, к которому относится заказ

Example: 1
amountinteger · int64Required

Сумма заказа в минимальных единицах валюты (центы/копейки)

Example: 100000
currencystring · enumRequired

Код валюты (в нижнем регистре)

Example: rubPossible values:
titlestringRequired

Название заказа (макс 100 символов UTF-16)

Example: Товар X
descriptionstringRequired

Описание заказа (макс 300 символов UTF-16)

Example: Подробное описание товара
statusstring · enumRequired

Статус заказа. prepaid опциональный (включается по запросу продавца): card-to-Stars заказы, где Stars зачислены покупателю, но он ещё не подтвердил списание. Продавцы без включения видят pending.

Отказ по карте статус не меняет — заказ остаётся в pending и доступен к оплате.

Example: paidPossible values:
emailstring · emailOptional

Email клиента (опционально)

Example: customer@example.com
successUrlstring · uriRequired

URL редиректа при успешной оплате

Example: https://shop.com/success
failUrlstring · uriRequired

URL редиректа при неудачной оплате

Example: https://shop.com/fail
paymentUrlstring · uri · nullableRequired

Веб-URL для завершения оплаты клиентом в браузере. null для заказов OnlyStars — их можно оплатить только внутри Telegram через webappPaymentUrl.

Example: https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000
webappPaymentUrlstring · uriOptional

URL для оплаты через Telegram WebApp

Example: https://t.me/tribute/app?startapp=b2RK4mN
createdAtstring · date-timeRequired

Время создания заказа в формате ISO 8601

Example: 2025-11-13T15:04:05Z
commentstringOptional

Комментарий к заказу (опционально)

Example: Особые пожелания
periodstring · enumRequired

Период оплаты для рекуррентных заказов

Example: onetimePossible values:
memberStatusstring · enumOptional

Статус рекуррентной подписки (только для рекуррентных заказов)

Example: activePossible values:
memberExpiresAtstring · date-timeOptional

Дата окончания рекуррентной подписки в формате ISO 8601 (только для рекуррентных заказов)

Example: 2025-12-13T15:04:05Z
memberInTrialbooleanOptional

True, пока активный участник ещё находится в бесплатном пробном периоде (подписан, но списание не произошло). Присутствует всегда, когда есть участник — false для участников без пробного периода, после конвертации пробного периода или отмены подписки. Отсутствует, только если участника нет.

Example: true
memberTrialStartedAtstring · date-timeOptional

Начало пробного периода (момент подписки) в формате ISO 8601. Присутствует у активного участника с пробным периодом — и во время пробного периода, и после конвертации (тогда историческое значение). Отсутствует для не-пробных и отменённых участников.

Example: 2025-12-13T15:04:05Z
memberTrialEndsAtstring · date-timeOptional

Дата окончания пробного периода / первого списания в формате ISO 8601. Присутствует у активного участника с пробным периодом — и во время пробного периода, и после конвертации (тогда историческое значение). Отсутствует для не-пробных и отменённых участников.

Example: 2025-12-20T15:04:05Z
lastPaidTransactionAtstring · date-time · nullableOptional

Дата последней оплаченной транзакции в формате ISO 8601. Null, если транзакций нет.

Example: 2025-12-13T15:04:05Z
starsAmountinteger · int64Optional

Фиксированная сумма в Telegram Stars (0 если не задано)

Example: 0
onlyStarsbooleanOptional

Принимает ли заказ только оплату через Telegram Stars

Example: false
firstPeriodAmountinteger · int64 · nullableOptional

Цена первого периода в минимальных единицах валюты. Если задана — первое списание прошло по этой сумме, последующие списываются по amount. Отсутствует, если у заказа нет переопределения первого периода.

Example: 50000
sendEmailbooleanOptional

Отправляется ли покупателю чек на email после успешной оплаты (наследуется от магазина при создании)

Example: false
post/shop/orders
POST /api/v1/shop/orders HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 448

{
  "shopId": 1,
  "amount": 100000,
  "currency": "rub",
  "title": "Товар X",
  "description": "Подробное описание товара",
  "successUrl": "https://shop.com/success",
  "failUrl": "https://shop.com/fail",
  "email": "customer@example.com",
  "comment": "Особые пожелания",
  "customerId": "user_12345",
  "period": "monthly",
  "starsAmount": 50,
  "imageUrl": "https://example.com/product-image.jpg",
  "firstPeriodAmount": 50000,
  "trialPeriod": "seven_days"
}
{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "shopId": 1,
  "amount": 100000,
  "currency": "rub",
  "title": "Товар X",
  "description": "Подробное описание товара",
  "status": "paid",
  "email": "customer@example.com",
  "successUrl": "https://shop.com/success",
  "failUrl": "https://shop.com/fail",
  "paymentUrl": "https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000",
  "webappPaymentUrl": "https://t.me/tribute/app?startapp=b2RK4mN",
  "createdAt": "2025-11-13T15:04:05Z",
  "comment": "Особые пожелания",
  "period": "onetime",
  "memberStatus": "active",
  "memberExpiresAt": "2025-12-13T15:04:05Z",
  "memberInTrial": true,
  "memberTrialStartedAt": "2025-12-13T15:04:05Z",
  "memberTrialEndsAt": "2025-12-20T15:04:05Z",
  "lastPaidTransactionAt": "2025-12-13T15:04:05Z",
  "starsAmount": 0,
  "onlyStars": false,
  "firstPeriodAmount": 50000,
  "sendEmail": false,
  "image": {
    "id": 123,
    "path": "https://cdn.example.com/image.jpg",
    "thumbnail": "text",
    "width": 800,
    "height": 600,
    "fileType": "image"
  }
}

Получить заказы магазина по статусу

get

Возвращает заказы магазина, сгруппированные по статусу, с поддержкой пагинации и количеством заказов.

Три режима использования:

  1. Начальная загрузка (без page, без status): Возвращает первую страницу заказов для каждого статуса (all, pending, paid, failed) и общее количество. Используйте при первой загрузке экрана.

  2. Пагинация «все» (page указан, без status или status=all): Возвращает конкретную страницу всех заказов под ключом all.

  3. Пагинация по статусу (page и status указаны): Возвращает конкретную страницу заказов для данного статуса под соответствующим ключом.

Заказы отсортированы по убыванию ID (сначала новые).

Authorizations
Api-KeystringRequired

API ключ для аутентификации.

Query parameters
shopIdinteger · uint64Optional

ID магазина, из которого читать заказы. По умолчанию — самый старый магазин пользователя.

Example: 1
statusstring · enumOptional

Фильтр по статусу заказа. Если не указан и page не задан, возвращает все статусы. Если установлен all или не указан вместе с page, возвращает все заказы.

prepaid опциональный (включается по запросу продавца): возвращает card-to-Stars заказы, где Stars уже зачислены покупателю, но он ещё не подтвердил списание. Запрос prepaid без включения вернёт HTTP 400.

Example: paidPossible values:
pageinteger · min: 1Optional

Номер страницы (начиная с 1). Если не указан, выполняется начальная группированная загрузка.

Example: 1
sizeinteger · min: 1 · max: 100Optional

Количество заказов на странице (по умолчанию 20, макс 100)

Default: 20Example: 20
dateFromstring · dateOptional

Начальная дата (включительно) в UTC, формат yyyy-mm-dd

Example: 2026-01-01
dateTostring · dateOptional

Конечная дата (включительно) в UTC, формат yyyy-mm-dd

Example: 2026-12-31
Responses
200

Успешный ответ

application/json
nextFromstringRequired

Номер следующей страницы в виде строки. Пустая строка, если страниц больше нет.

Example: 2
get/shop/orders_by_status
GET /api/v1/shop/orders_by_status HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "counts": {
    "all": 42,
    "pending": 5,
    "paid": 30,
    "failed": 7
  },
  "orders": {
    "all": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "amount": 100000,
        "currency": "rub",
        "title": "Товар X",
        "status": "paid"
      }
    ],
    "pending": [],
    "paid": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "amount": 100000,
        "currency": "rub",
        "title": "Товар X",
        "status": "paid"
      }
    ],
    "failed": []
  },
  "nextFrom": "2"
}

Получить заказ

get

Возвращает полные данные конкретного заказа магазина по его UUID. Включает статус подписки и изображение. Доступно только владельцу магазина.

Authorizations
Api-KeystringRequired

API ключ для аутентификации.

Path parameters
orderUuidstring · uuidRequired

UUID заказа

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
200

Успешный ответ

application/json
uuidstring · uuidRequired

UUID заказа

Example: 550e8400-e29b-41d4-a716-446655440000
shopIdinteger · uint64Required

ID магазина, к которому относится заказ

Example: 1
amountinteger · int64Required

Сумма заказа в минимальных единицах валюты (центы/копейки)

Example: 100000
currencystring · enumRequired

Код валюты (в нижнем регистре)

Example: rubPossible values:
titlestringRequired

Название заказа (макс 100 символов UTF-16)

Example: Товар X
descriptionstringRequired

Описание заказа (макс 300 символов UTF-16)

Example: Подробное описание товара
statusstring · enumRequired

Статус заказа. prepaid опциональный (включается по запросу продавца): card-to-Stars заказы, где Stars зачислены покупателю, но он ещё не подтвердил списание. Продавцы без включения видят pending.

Отказ по карте статус не меняет — заказ остаётся в pending и доступен к оплате.

Example: paidPossible values:
emailstring · emailOptional

Email клиента (опционально)

Example: customer@example.com
successUrlstring · uriRequired

URL редиректа при успешной оплате

Example: https://shop.com/success
failUrlstring · uriRequired

URL редиректа при неудачной оплате

Example: https://shop.com/fail
paymentUrlstring · uri · nullableRequired

Веб-URL для завершения оплаты клиентом в браузере. null для заказов OnlyStars — их можно оплатить только внутри Telegram через webappPaymentUrl.

Example: https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000
webappPaymentUrlstring · uriOptional

URL для оплаты через Telegram WebApp

Example: https://t.me/tribute/app?startapp=b2RK4mN
createdAtstring · date-timeRequired

Время создания заказа в формате ISO 8601

Example: 2025-11-13T15:04:05Z
commentstringOptional

Комментарий к заказу (опционально)

Example: Особые пожелания
periodstring · enumRequired

Период оплаты для рекуррентных заказов

Example: onetimePossible values:
memberStatusstring · enumOptional

Статус рекуррентной подписки (только для рекуррентных заказов)

Example: activePossible values:
memberExpiresAtstring · date-timeOptional

Дата окончания рекуррентной подписки в формате ISO 8601 (только для рекуррентных заказов)

Example: 2025-12-13T15:04:05Z
memberInTrialbooleanOptional

True, пока активный участник ещё находится в бесплатном пробном периоде (подписан, но списание не произошло). Присутствует всегда, когда есть участник — false для участников без пробного периода, после конвертации пробного периода или отмены подписки. Отсутствует, только если участника нет.

Example: true
memberTrialStartedAtstring · date-timeOptional

Начало пробного периода (момент подписки) в формате ISO 8601. Присутствует у активного участника с пробным периодом — и во время пробного периода, и после конвертации (тогда историческое значение). Отсутствует для не-пробных и отменённых участников.

Example: 2025-12-13T15:04:05Z
memberTrialEndsAtstring · date-timeOptional

Дата окончания пробного периода / первого списания в формате ISO 8601. Присутствует у активного участника с пробным периодом — и во время пробного периода, и после конвертации (тогда историческое значение). Отсутствует для не-пробных и отменённых участников.

Example: 2025-12-20T15:04:05Z
lastPaidTransactionAtstring · date-time · nullableOptional

Дата последней оплаченной транзакции в формате ISO 8601. Null, если транзакций нет.

Example: 2025-12-13T15:04:05Z
starsAmountinteger · int64Optional

Фиксированная сумма в Telegram Stars (0 если не задано)

Example: 0
onlyStarsbooleanOptional

Принимает ли заказ только оплату через Telegram Stars

Example: false
firstPeriodAmountinteger · int64 · nullableOptional

Цена первого периода в минимальных единицах валюты. Если задана — первое списание прошло по этой сумме, последующие списываются по amount. Отсутствует, если у заказа нет переопределения первого периода.

Example: 50000
sendEmailbooleanOptional

Отправляется ли покупателю чек на email после успешной оплаты (наследуется от магазина при создании)

Example: false
get/shop/orders/{orderUuid}
GET /api/v1/shop/orders/{orderUuid} HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "shopId": 1,
  "amount": 100000,
  "currency": "rub",
  "title": "Товар X",
  "description": "Подробное описание товара",
  "status": "paid",
  "email": "customer@example.com",
  "successUrl": "https://shop.com/success",
  "failUrl": "https://shop.com/fail",
  "paymentUrl": "https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000",
  "webappPaymentUrl": "https://t.me/tribute/app?startapp=b2RK4mN",
  "createdAt": "2025-11-13T15:04:05Z",
  "comment": "Особые пожелания",
  "period": "onetime",
  "memberStatus": "active",
  "memberExpiresAt": "2025-12-13T15:04:05Z",
  "memberInTrial": true,
  "memberTrialStartedAt": "2025-12-13T15:04:05Z",
  "memberTrialEndsAt": "2025-12-20T15:04:05Z",
  "lastPaidTransactionAt": "2025-12-13T15:04:05Z",
  "starsAmount": 0,
  "onlyStars": false,
  "firstPeriodAmount": 50000,
  "sendEmail": false,
  "image": {
    "id": 123,
    "path": "https://cdn.example.com/image.jpg",
    "thumbnail": "text",
    "width": 800,
    "height": 600,
    "fileType": "image"
  }
}

Получить статус заказа

get

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

Authorizations
Api-KeystringRequired

API ключ для аутентификации.

Path parameters
orderUuidstring · uuidRequired

UUID заказа

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
200

Успешный ответ

application/json
statusstring · enumRequired

Статус заказа. prepaid (card-to-Stars: Stars зачислены покупателю, ожидается подтверждение списания) возвращается только продавцам, включённым в раскатку — остальные видят pending, пока покупатель не подтвердит списание.

Example: paidPossible values:
get/shop/orders/{orderUuid}/status
GET /api/v1/shop/orders/{orderUuid}/status HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "status": "paid"
}

Отменить рекуррентный заказ

post

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

Authorizations
Api-KeystringRequired

API ключ для аутентификации.

Path parameters
orderUuidstring · uuidRequired

UUID заказа

Example: 550e8400-e29b-41d4-a716-446655440000
Responses
200

Заказ успешно отменен

application/json
successbooleanRequired

Успешность операции

Example: true
messagestringRequired

Сообщение об успехе

Example: recurring order cancelled
post/shop/orders/{orderUuid}/cancel
POST /api/v1/shop/orders/{orderUuid}/cancel HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "message": "recurring order cancelled"
}

Получить транзакции заказа

get

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

Authorizations
Api-KeystringRequired

API ключ для аутентификации.

Path parameters
orderUuidstring · uuidRequired

UUID заказа

Example: 550e8400-e29b-41d4-a716-446655440000
Query parameters
startFromintegerOptional

Смещение пагинации (количество записей для пропуска)

Default: 0Example: 0
Responses
200

Успешный ответ

application/json
nextFromstringRequired

Смещение для следующей страницы. Пустая строка если страниц больше нет

Example: 20
get/shop/orders/{orderUuid}/transactions
GET /api/v1/shop/orders/{orderUuid}/transactions HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "transactions": [
    {
      "id": 12345,
      "type": "shop_order_sell",
      "objectId": 100,
      "amount": 1000,
      "currency": "rub",
      "createdAt": 1731510245,
      "serviceFee": 80,
      "total": 920,
      "paymentMethod": "bank_card",
      "isRefunded": false,
      "isRefundable": true,
      "isRecurring": false,
      "shopOrder": {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Товар X",
        "description": "Подробное описание товара",
        "amount": 1000,
        "currency": "eur",
        "status": "paid",
        "email": "customer@example.com",
        "successUrl": "https://shop.com/success",
        "failUrl": "https://shop.com/fail",
        "createdAt": 1731510245,
        "comment": "Особые пожелания",
        "period": "onetime",
        "shopName": "Мой магазин",
        "starsAmount": 0,
        "onlyStars": false
      }
    }
  ],
  "nextFrom": "20"
}

Возврат по транзакции заказа

post

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

Authorizations
Api-KeystringRequired

API ключ для аутентификации.

Path parameters
orderUuidstring · uuidRequired

UUID заказа

Example: 550e8400-e29b-41d4-a716-446655440000
txIdinteger · uint64Required

ID транзакции (должна быть транзакцией продажи)

Example: 12345
Responses
200

Возврат успешно инициирован

application/json
successbooleanRequired

Успешность операции

Example: true
messagestringRequired

Сообщение об успехе

Example: refund initiated
statusstring · enumRequired

Статус возврата

Example: initiatedPossible values:
post/shop/orders/{orderUuid}/transactions/{txId}/refund
POST /api/v1/shop/orders/{orderUuid}/transactions/{txId}/refund HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "message": "refund initiated",
  "status": "initiated"
}

Повторить отправку вебхука заказа

post

Повторно доставляет последний уже отправлявшийся вебхук указанного типа события по заказу, клонируя его в новую попытку отправки. Доступно только владельцу магазина или авторизованным менеджерам. События, ещё стоящие в очереди или в процессе отправки, переотправить нельзя. Идемпотентно, пока переотправка стоит в очереди (возвращает 200 без постановки новой); не более одной переотправки на тип события по заказу в минуту.

Authorizations
Api-KeystringRequired

API ключ для аутентификации.

Path parameters
orderUuidstring · uuidRequired

UUID заказа

Example: 550e8400-e29b-41d4-a716-446655440000
Body
eventstring · enumRequired

Тип события вебхука для переотправки

Example: shop_order_charge_successPossible values:
Responses
200

Повтор запланирован успешно

application/json
successbooleanRequired

Запланирован ли повтор

Example: true
post/shop/orders/{orderUuid}/webhooks/resend
POST /api/v1/shop/orders/{orderUuid}/webhooks/resend HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 37

{
  "event": "shop_order_charge_success"
}
{
  "success": true
}
PreviousAPI Магазина
NextВебхуки

Last updated