Methods

Shop methods for managing orders and recurring payments

Get Shop

get

Returns shop information for the authenticated user

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Responses

200

Successful response

application/json

userIdintegerRequired

Shop owner user ID

Example: 123

namestringRequired

Shop name

Example: My Shop

linkstringRequired

Shop link/slug

Example: myshop

callbackUrlstring · uriRequired

Webhook callback URL for order notifications

Example: https://example.com/webhook

recurrentbooleanRequired

Whether recurring payments are available

Example: true

onlyStarsbooleanRequired

Whether only Telegram Stars payment is accepted

Example: false

tokenChargingbooleanOptional

Whether merchant-initiated token charging is enabled

Example: false

statusinteger · enumRequired

Shop status (0 = inactive, 1 = active)

Example: 1Possible values:

401

Unauthorized (invalid API key)

application/json

404

Shop not found

application/json

get

/shop

HTTPcURLJavaScriptPython

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

{
  "userId": 123,
  "name": "My Shop",
  "link": "myshop",
  "callbackUrl": "https://example.com/webhook",
  "recurrent": true,
  "onlyStars": false,
  "tokenCharging": false,
  "status": 1
}

Get Shop Orders

get

Returns a list of shop orders sorted by ID descending (newest first). Optionally filter by date range.

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Query parameters

dateFromstring · dateOptional

Start date (inclusive) in UTC, format yyyy-mm-dd

Example: 2026-01-01

dateTostring · dateOptional

End date (inclusive) in UTC, format yyyy-mm-dd

Example: 2026-12-31

Responses

200

Successful response

application/json

uuidstring · uuidRequired

Order UUID

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

amountinteger · int64Required

Order amount in smallest currency units (cents/kopecks)

Example: 100000

currencystring · enumRequired

Currency code (lowercase)

Example: rubPossible values:

titlestringRequired

Order title (max 100 UTF-16 characters)

Example: Product X

descriptionstringRequired

Order description (max 300 UTF-16 characters)

Example: Detailed product description

statusstring · enumRequired

Order status

Example: paidPossible values:

emailstring · emailOptional

Customer email (optional)

Example: [email protected]

successUrlstring · uriRequired

Redirect URL on successful payment

Example: https://shop.com/success

failUrlstring · uriRequired

Redirect URL on failed payment

Example: https://shop.com/fail

paymentUrlstring · uriRequired

URL for customer to complete payment

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

webappPaymentUrlstring · uriOptional

Telegram WebApp payment URL for in-app payment

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

createdAtstring · date-timeRequired

Order creation timestamp in ISO 8601 format

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

commentstringOptional

Optional comment for the order

Example: Special request

periodstring · enumRequired

Billing period for recurring orders

Example: onetimePossible values:

memberStatusstring · enumOptional

Recurring subscription status (only for recurring orders)

Example: activePossible values:

memberExpiresAtstring · date-timeOptional

Recurring subscription expiration date in ISO 8601 format (only for recurring orders)

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

starsAmountinteger · int64Optional

Fixed amount in Telegram Stars (0 if not set)

Example: 0

onlyStarsbooleanOptional

Whether this order only accepts Telegram Stars payment

Example: false

401

Unauthorized (invalid API key)

application/json

404

Shop not found

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": "Product X",
    "description": "Detailed product 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": "Special request",
    "period": "onetime",
    "memberStatus": "active",
    "memberExpiresAt": "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"
    }
  }
]

Create Shop Order

post

Creates a new shop order and returns a payment URL for the customer. Supports one-time and recurring payments.

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Body

application/json

amountinteger · int64Required

Order amount in smallest currency units (cents for EUR/USD, kopecks for RUB)

Example: 100000

currencystring · enumRequired

Currency code (lowercase)

Example: rubPossible values:

titlestringRequired

Order title (required, max 100 UTF-16 characters)

Example: Product X

descriptionstringRequired

Order description (required, max 300 UTF-16 characters)

Example: Detailed product description

successUrlstring · uriOptional

Redirect URL on successful payment (optional, must be valid URL)

Example: https://shop.com/success

failUrlstring · uriOptional

Redirect URL on failed payment (optional, must be valid URL)

Example: https://shop.com/fail

emailstring · emailOptional

Customer email (optional, validated if provided)

Example: [email protected]

commentstringOptional

Optional comment for the order

Example: Special request

customerIdstring · max: 256Optional

Unique customer identifier

Example: user_12345

periodstring · enumOptional

Billing period. Defaults to "onetime" if not specified. Recurring periods require shop.recurrent to be enabled. OnlyStars shops only support "onetime" and "monthly" periods (Telegram Stars subscriptions are 30-day cycles).

Default: onetimeExample: monthlyPossible values:

starsAmountinteger · int64 · min: 1Optional

Fixed amount in Telegram Stars. Required for OnlyStars shops. When set, enables Stars payment as an option. Only supported for onetime or monthly periods. For monthly orders, creates a Telegram Stars subscription.

Example: 50

imageUrlstring · uriOptional

Image URL for the order. Will be displayed in Telegram Stars invoices and transactions. If provided, the image is downloaded and stored; if an image with this URL already exists, it is reused.

Example: https://example.com/product-image.jpg

Responses

200

Order created successfully

application/json

uuidstring · uuidRequired

Order UUID

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

paymentUrlstring · uriRequired

Payment URL for customer to complete payment

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

webappPaymentUrlstring · uriRequired

Telegram WebApp payment URL for in-app payment

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

400

Bad request

application/json

401

Unauthorized (invalid API key)

application/json

404

Shop not found

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: 345

{
  "amount": 100000,
  "currency": "rub",
  "title": "Product X",
  "description": "Detailed product description",
  "successUrl": "https://shop.com/success",
  "failUrl": "https://shop.com/fail",
  "email": "[email protected]",
  "comment": "Special request",
  "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 Shop Orders by Status

get

Returns shop orders grouped by status with pagination support and order counts.

Three usage modes:

1. Initial load (no page, no status): Returns first page of orders for every status (all, pending, paid, failed) plus total counts. Use this on first screen load.

2. Paginated "all" (page provided, no status or status=all): Returns a specific page of all orders under the all key.

3. Paginated per status (page and status provided): Returns a specific page of orders for that status under the corresponding key.

Orders are sorted by ID descending (newest first).

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Query parameters

statusstring · enumOptional

Filter by order status. When omitted and page is not provided, returns all statuses. When set to all or omitted with page, returns all orders.

Example: paidPossible values:

pageinteger · min: 1Optional

Page number (1-based). When omitted, triggers the initial grouped load.

Example: 1

sizeinteger · min: 1 · max: 100Optional

Number of orders per page (default 20, max 100)

Default: 20Example: 20

dateFromstring · dateOptional

Start date (inclusive) in UTC, format yyyy-mm-dd

Example: 2026-01-01

dateTostring · dateOptional

End date (inclusive) in UTC, format yyyy-mm-dd

Example: 2026-12-31

Responses

200

Successful response

application/json

nextFromstringRequired

Next page number as string. Empty string if no more pages.

Example: 2

400

Bad request (invalid status parameter)

application/json

401

Unauthorized (invalid API key)

application/json

404

Shop not found

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": "Product X",
        "status": "paid"
      }
    ],
    "pending": [],
    "paid": [
      {
        "uuid": "550e8400-e29b-41d4-a716-446655440000",
        "amount": 100000,
        "currency": "rub",
        "title": "Product X",
        "status": "paid"
      }
    ],
    "failed": []
  },
  "nextFrom": "2"
}

Get Shop Order

get

Returns full details of a specific shop order by its UUID. Includes member status and image. Only accessible by the shop owner.

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Path parameters

orderUuidstring · uuidRequired

Order UUID

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

Responses

200

Successful response

application/json

uuidstring · uuidRequired

Order UUID

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

amountinteger · int64Required

Order amount in smallest currency units (cents/kopecks)

Example: 100000

currencystring · enumRequired

Currency code (lowercase)

Example: rubPossible values:

titlestringRequired

Order title (max 100 UTF-16 characters)

Example: Product X

descriptionstringRequired

Order description (max 300 UTF-16 characters)

Example: Detailed product description

statusstring · enumRequired

Order status

Example: paidPossible values:

emailstring · emailOptional

Customer email (optional)

Example: [email protected]

successUrlstring · uriRequired

Redirect URL on successful payment

Example: https://shop.com/success

failUrlstring · uriRequired

Redirect URL on failed payment

Example: https://shop.com/fail

paymentUrlstring · uriRequired

URL for customer to complete payment

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

webappPaymentUrlstring · uriOptional

Telegram WebApp payment URL for in-app payment

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

createdAtstring · date-timeRequired

Order creation timestamp in ISO 8601 format

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

commentstringOptional

Optional comment for the order

Example: Special request

periodstring · enumRequired

Billing period for recurring orders

Example: onetimePossible values:

memberStatusstring · enumOptional

Recurring subscription status (only for recurring orders)

Example: activePossible values:

memberExpiresAtstring · date-timeOptional

Recurring subscription expiration date in ISO 8601 format (only for recurring orders)

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

starsAmountinteger · int64Optional

Fixed amount in Telegram Stars (0 if not set)

Example: 0

onlyStarsbooleanOptional

Whether this order only accepts Telegram Stars payment

Example: false

401

Unauthorized (invalid API key)

application/json

403

Forbidden (order belongs to another shop)

application/json

404

Order or shop not found

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": "Product X",
  "description": "Detailed product 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": "Special request",
  "period": "onetime",
  "memberStatus": "active",
  "memberExpiresAt": "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 Shop Order Status

get

Returns the current status of a specific shop order by its UUID. Only accessible by the shop owner.

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Path parameters

orderUuidstring · uuidRequired

Order UUID

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

Responses

200

Successful response

application/json

statusstring · enumRequired

Order status

Example: paidPossible values:

401

Unauthorized (invalid API key)

application/json

403

Forbidden (order belongs to another shop)

application/json

404

Order or shop not found

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

Cancel Recurring Shop Order

post

Cancels a recurring shop order subscription. Only accessible by the shop owner or authorized managers.

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Path parameters

orderUuidstring · uuidRequired

Order UUID

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

Responses

200

Order cancelled successfully

application/json

successbooleanRequired

Whether the operation was successful

Example: true

messagestringRequired

Success message

Example: recurring order cancelled

400

Bad request

application/json

401

Unauthorized (invalid API key)

application/json

403

Forbidden (access denied)

application/json

404

Order, shop, or recurring subscription not found

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 Shop Order Transactions

get

Returns a paginated list of transactions for a specific shop order. Only accessible by the shop owner or authorized managers.

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Path parameters

orderUuidstring · uuidRequired

Order UUID

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

Query parameters

startFromintegerOptional

Pagination offset (number of records to skip)

Default: 0Example: 0

Responses

200

Successful response

application/json

nextFromstringRequired

Offset for the next page. Empty string if no more pages

Example: 20

401

Unauthorized (invalid API key)

application/json

403

Forbidden (access denied)

application/json

404

Order or shop not found

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": "Product X",
        "description": "Detailed product description",
        "amount": 1000,
        "currency": "eur",
        "status": "paid",
        "email": "[email protected]",
        "successUrl": "https://shop.com/success",
        "failUrl": "https://shop.com/fail",
        "createdAt": 1731510245,
        "comment": "Special request",
        "period": "onetime",
        "shopName": "My Shop",
        "starsAmount": 0,
        "onlyStars": false
      }
    }
  ],
  "nextFrom": "20"
}

Refund Shop Order Transaction

post

Initiates a refund for a specific transaction of a shop order. Only accessible by the shop owner or authorized managers. Only sell transactions from paid orders can be refunded.

Authorizations

ApiKeyAuth

Api-KeystringRequired

API key for authentication.

Path parameters

orderUuidstring · uuidRequired

Order UUID

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

txIdinteger · uint64Required

Transaction ID (must be a sell transaction)

Example: 12345

Responses

200

Refund initiated successfully

application/json

successbooleanRequired

Whether the operation was successful

Example: true

messagestringRequired

Success message

Example: refund initiated

statusstring · enumRequired

Refund status

Example: initiatedPossible values:

400

Bad request

application/json

401

Unauthorized (invalid API key)

application/json

403

Forbidden (access denied)

application/json

404

Order, shop, or transaction not found

application/json

500

Internal server error (refund processing failed)

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