Методы

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

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

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

Стандартные заказы (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

Возвращает информацию о магазине для аутентифицированного пользователя

Authorizations

ApiKeyAuth

Api-KeystringRequired

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

Responses

200

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

application/json

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:

401

Неавторизован (неверный API ключ)

application/json

404

Магазин не найден

application/json

get

/shop

HTTPcURLJavaScriptPython

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

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

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

get

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

Authorizations

ApiKeyAuth

Api-KeystringRequired

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

Query parameters

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

amountinteger · int64Required

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

Example: 100000

currencystring · enumRequired

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

Example: rubPossible values:

titlestringRequired

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

Example: Товар X

descriptionstringRequired

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

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

statusstring · enumRequired

Статус заказа

Example: paidPossible values:

emailstring · emailOptional

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

Example: [email protected]

successUrlstring · uriRequired

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

Example: https://shop.com/success

failUrlstring · uriRequired

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

Example: https://shop.com/fail

paymentUrlstring · uriRequired

URL для завершения оплаты клиентом

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

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

401

Неавторизован (неверный API ключ)

application/json

404

Магазин не найден

application/json

get

/shop/orders

HTTPcURLJavaScriptPython

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

[
  {
    "uuid": "550e8400-e29b-41d4-a716-446655440000",
    "amount": 100000,
    "currency": "rub",
    "title": "Товар X",
    "description": "Подробное описание товара",
    "status": "paid",
    "email": "[email protected]",
    "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",
    "lastPaidTransactionAt": "2025-12-13T15:04:05Z",
    "starsAmount": 0,
    "onlyStars": false,
    "image": {
      "id": 123,
      "path": "https://cdn.example.com/image.jpg",
      "thumbnail": "text",
      "width": 800,
      "height": 600,
      "fileType": "image"
    }
  }
]

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

post

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

Authorizations

ApiKeyAuth

Api-KeystringRequired

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

Body

application/json

amountinteger · int64Required

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

Example: 100000

currencystring · enumRequired

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

Example: rubPossible values:

titlestringRequired

Название заказа (обязательно, макс 100 символов UTF-16)

Example: Товар X

descriptionstringRequired

Описание заказа (обязательно, макс 300 символов UTF-16)

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

successUrlstring · uriOptional

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

Example: https://shop.com/success

failUrlstring · uriOptional

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

Example: https://shop.com/fail

emailstring · emailOptional

Email клиента (опционально, валидируется если указан)

Example: [email protected]

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

Responses

200

Заказ успешно создан

application/json

uuidstring · uuidRequired

UUID заказа

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

paymentUrlstring · uriRequired

URL для завершения оплаты клиентом

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

webappPaymentUrlstring · uriRequired

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

Example: https://t.me/tribute/app?startapp=b2RK4mN

400

Некорректный запрос

application/json

401

Неавторизован (неверный API ключ)

application/json

404

Магазин не найден

application/json

post

/shop/orders

HTTPcURLJavaScriptPython

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

{
  "amount": 100000,
  "currency": "rub",
  "title": "Товар X",
  "description": "Подробное описание товара",
  "successUrl": "https://shop.com/success",
  "failUrl": "https://shop.com/fail",
  "email": "[email protected]",
  "comment": "Особые пожелания",
  "customerId": "user_12345",
  "period": "monthly",
  "starsAmount": 50,
  "imageUrl": "https://example.com/product-image.jpg"
}

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "paymentUrl": "https://web.tribute.tg/shop/pay/550e8400-e29b-41d4-a716-446655440000",
  "webappPaymentUrl": "https://t.me/tribute/app?startapp=b2RK4mN"
}

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

get

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

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

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

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

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

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

Authorizations

ApiKeyAuth

Api-KeystringRequired

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

Query parameters

statusstring · enumOptional

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

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

400

Некорректный запрос (неверный параметр status)

application/json

401

Неавторизован (неверный API ключ)

application/json

404

Магазин не найден

application/json

get

/shop/orders_by_status

HTTPcURLJavaScriptPython

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

ApiKeyAuth

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

amountinteger · int64Required

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

Example: 100000

currencystring · enumRequired

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

Example: rubPossible values:

titlestringRequired

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

Example: Товар X

descriptionstringRequired

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

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

statusstring · enumRequired

Статус заказа

Example: paidPossible values:

emailstring · emailOptional

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

Example: [email protected]

successUrlstring · uriRequired

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

Example: https://shop.com/success

failUrlstring · uriRequired

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

Example: https://shop.com/fail

paymentUrlstring · uriRequired

URL для завершения оплаты клиентом

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

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

401

Неавторизован (неверный API ключ)

application/json

403

Запрещено (заказ принадлежит другому магазину)

application/json

404

Заказ или магазин не найден

application/json

get

/shop/orders/{orderUuid}

HTTPcURLJavaScriptPython

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

{
  "uuid": "550e8400-e29b-41d4-a716-446655440000",
  "amount": 100000,
  "currency": "rub",
  "title": "Товар X",
  "description": "Подробное описание товара",
  "status": "paid",
  "email": "[email protected]",
  "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",
  "lastPaidTransactionAt": "2025-12-13T15:04:05Z",
  "starsAmount": 0,
  "onlyStars": false,
  "image": {
    "id": 123,
    "path": "https://cdn.example.com/image.jpg",
    "thumbnail": "text",
    "width": 800,
    "height": 600,
    "fileType": "image"
  }
}

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

get

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

Authorizations

ApiKeyAuth

Api-KeystringRequired

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

Path parameters

orderUuidstring · uuidRequired

UUID заказа

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

Responses

200

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

application/json

statusstring · enumRequired

Статус заказа

Example: paidPossible values:

401

Неавторизован (неверный API ключ)

application/json

403

Запрещено (заказ принадлежит другому магазину)

application/json

404

Заказ или магазин не найден

application/json

get

/shop/orders/{orderUuid}/status

HTTPcURLJavaScriptPython

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

{
  "status": "paid"
}

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

post

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

Authorizations

ApiKeyAuth

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

400

Некорректный запрос

application/json

401

Неавторизован (неверный API ключ)

application/json

403

Запрещено (доступ запрещен)

application/json

404

Заказ, магазин или рекуррентная подписка не найдены

application/json

post

/shop/orders/{orderUuid}/cancel

HTTPcURLJavaScriptPython

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

ApiKeyAuth

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

401

Неавторизован (неверный API ключ)

application/json

403

Запрещено (доступ запрещен)

application/json

404

Заказ или магазин не найден

application/json

get

/shop/orders/{orderUuid}/transactions

HTTPcURLJavaScriptPython

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": "[email protected]",
        "successUrl": "https://shop.com/success",
        "failUrl": "https://shop.com/fail",
        "createdAt": 1731510245,
        "comment": "Особые пожелания",
        "period": "onetime",
        "shopName": "Мой магазин",
        "starsAmount": 0,
        "onlyStars": false
      }
    }
  ],
  "nextFrom": "20"
}

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

post

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

Authorizations

ApiKeyAuth

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:

400

Некорректный запрос

application/json

401

Неавторизован (неверный API ключ)

application/json

403

Запрещено (доступ запрещен)

application/json

404

Заказ, магазин или транзакция не найдены

application/json

500

Внутренняя ошибка сервера (ошибка обработки возврата)

application/json

post

/shop/orders/{orderUuid}/transactions/{txId}/refund

HTTPcURLJavaScriptPython

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"
}