Integrating Digital Products into Your Product

This guide is for Telegram bot and service owners who want to use Tribute as a payment system. Accept payments via SBP and Telegram Stars, receive withdrawals in USDT without complex payment provider

Benefits of Tribute Digital Products Integration

For you as a service owner:

Payment acceptance - SBP and Telegram Stars
Simple integration - create a product, get a link, set up a webhook
Ready infrastructure - no need to integrate payment providers yourself
Automatic withdrawals - receive money in USDT

For your users:

Convenient payment - one-click purchase through Telegram
Available payment methods - SBP, Telegram Stars

How it works: general scheme

1. You create a digital product in Tribute

For example, for an AI assistant it could be "AI Assistant Access for 1 month"

2. Get a unique payment link

Each product has its own link in the format:

For Telegram: https://telegram.me/tribute/app?startapp=p123
For browser: https://web.tribute.tg/p/123

3. Direct users to this link

In your bot or other service, add a "Pay" button that leads to the product link

4. User pays

The buyer can:

Pay directly with Telegram Stars (if available on balance)
Buy Stars via SBP and immediately exchange them for the product

5. You receive a webhook about successful payment

After payment, a POST request with purchase information arrives at your server. More about webhook format in the webhooks documentation

6. Provide access to the user

Activate the service for the user using the Telegram ID from the webhook

Step-by-step setup instructions

Step 1: Registration in Tribute

Open @tribute in Telegram
Click "Start" and follow the instructions
Go to the "Author Dashboard" section

Step 2: Creating a digital product

In the dashboard, select "Digital Products" → "Create instant product"
You will be redirected to the bot chat
Send the bot a message that will become your digital product. This can be any message - for example, a photo with description, video, file, or even a voice note.
Example text message for integration:
```
✅ Thank you for purchasing AI Assistant access for 1 month!
Access will be provided automatically.
To activate your subscription, return to @YourAIBot
```
Important: This is the exact message the buyer will receive after payment. Add instructions for the user so they understand what to do next. Once the product is created, this message cannot be edited (but you can always create a new digital product with a different message).
After sending the message, click the "Create Product" button from the bot's message
Fill in the required fields:
- Currency - choose the payment currency
- Name - what the buyer will see (for example: "AI Assistant for 1 month")
- Description - brief product description
- Price - cost in the selected currency
Save the product
After saving, you will receive a unique payment link that can be used in your integration

Step 3: Getting API key

In the dashboard, open the menu (three dots) → "Settings"
Go to the "API Keys" section
Click "Generate New Key"
Save the key in a safe place - you'll need it to verify webhooks

Step 4: Setting up webhooks

In the "API Keys" section, find the "Webhook URL" field
Specify your server address for receiving webhooks:
```
https://your-server.com/webhook/tribute
```
Save settings

Step 5: Processing webhooks on your server

After successful payment for a digital product, Tribute will send a POST request to your URL:

Webhook format

{
  "name": "new_digital_product",
  "created_at": "2025-03-20T01:15:58.332Z",
  "sent_at": "2025-03-20T01:15:58.542Z",
  "payload": {
    "product_id": 456,
    "amount": 500,
    "currency": "usd",
    "user_id": 31326,
    "telegram_user_id": 12321321
  }
}

Webhook signature verification

Each request contains a trbt-signature header with HMAC-SHA256 signature of the request body. Examples of signature verification and webhook processing are available in the webhooks documentation

Step 6: Integration into your bot

In your Telegram bot, add a payment button

Python code

# Python + python-telegram-bot
from telegram import InlineKeyboardButton, InlineKeyboardMarkup

def send_payment_button(update, context):
    keyboard = [[
        InlineKeyboardButton(
            "💳 Pay ($9.99)",
            url="https://telegram.me/tribute/app?startapp=p456"
        )
    ]]
    reply_markup = InlineKeyboardMarkup(keyboard)
    
    update.message.reply_text(
        "AI Assistant for 1 month - $9.99",
        reply_markup=reply_markup
    )

Working with API

Get Product by ID

get

Returns a single product by its ID

Authorizations

Api-KeystringRequired

API key for authentication.

Path parameters

idintegerRequired

Product ID

Responses

200

Successful response

application/json

idintegerRequired

Product ID

Example: 2548

typestring · enumRequired

Product type

Example: digitalPossible values:

namestringRequired

Product name

Example: VPN Access - 1 Month

descriptionstringOptional

Product description

Example: High-speed VPN service with unlimited bandwidth and 50+ server locations worldwide

amountinteger · int64Required

Product price in smallest currency units (cents for USD/EUR, kopecks for RUB). For physical products this is the starting price, taken from the cheapest variant.

Example: 499

currencystring · enumRequired

Currency code

Example: usdPossible values:

starsAmountintegerOptional

Price in Telegram Stars

Example: 100

starsAmountEnabledbooleanOptional

Whether payment with Stars is enabled

Example: true

statusstring · enumRequired

Product status

Example: approvedPossible values:

isCustombooleanRequired

Whether this is a custom product

Example: false

acceptCardsbooleanRequired

Whether card payments are accepted

Example: true

acceptWalletPaybooleanRequired

Whether wallet payments are accepted

Example: false

protectContentbooleanRequired

Whether content protection is enabled

Example: true

createdstring · date-timeRequired

Product creation date

Example: 2025-08-25T10:30:00Z

updatedstring · date-timeRequired

Product last update date

Example: 2025-08-25T10:30:00Z

pendingOrdersintegerOptional

Number of pending orders (for custom products)

Example: 3

imageUrlstring · uriOptional

Product image URL

Example: https://cdn.example.com/image.jpg

linkstring · uriRequired

Direct link to product in Telegram app

Example: https://t.me/tribute_bot/app?startapp=pf6

webLinkstring · uriRequired

Web link to product

Example: https://web.tribute.tg/p/f6

400

Bad request (invalid product ID format)

application/json

401

Unauthorized (invalid API key)

application/json

403

Access denied

application/json

404

Product not found

application/json

get/products/{id}

GET /api/v1/products/{id} HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "id": 2548,
  "type": "digital",
  "name": "VPN Access - 1 Month",
  "description": "High-speed VPN service with unlimited bandwidth and 50+ server locations worldwide",
  "amount": 499,
  "currency": "usd",
  "starsAmount": 100,
  "starsAmountEnabled": true,
  "status": "approved",
  "isCustom": false,
  "acceptCards": true,
  "acceptWalletPay": false,
  "protectContent": true,
  "created": "2025-08-25T10:30:00Z",
  "updated": "2025-08-25T10:30:00Z",
  "pendingOrders": 3,
  "imageUrl": "https://cdn.example.com/image.jpg",
  "link": "https://t.me/tribute_bot/app?startapp=pf6",
  "webLink": "https://web.tribute.tg/p/f6"
}

Get Products List

get

Returns a paginated list of products

Authorizations

Api-KeystringRequired

API key for authentication.

Query parameters

pageinteger · min: 1Optional

Page number

Default: 1

sizeinteger · min: 1 · max: 100Optional

Items per page

Default: 20

typestring · enumOptional

Filter by product type

Possible values:

descbooleanOptional

Sort by ID descending

Default: false

Responses

200

Successful response

application/json

400

Bad request

application/json

401

Unauthorized (invalid API key)

application/json

get/products

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

{
  "rows": [
    {
      "id": 2548,
      "type": "digital",
      "name": "VPN Access - 1 Month",
      "description": "High-speed VPN service with unlimited bandwidth and 50+ server locations worldwide",
      "amount": 499,
      "currency": "usd",
      "starsAmount": 100,
      "starsAmountEnabled": true,
      "status": "approved",
      "isCustom": false,
      "acceptCards": true,
      "acceptWalletPay": false,
      "protectContent": true,
      "created": "2025-08-25T10:30:00Z",
      "updated": "2025-08-25T10:30:00Z",
      "pendingOrders": 3,
      "imageUrl": "https://cdn.example.com/image.jpg",
      "link": "https://t.me/tribute_bot/app?startapp=pf6",
      "webLink": "https://web.tribute.tg/p/f6"
    }
  ],
  "meta": {
    "total": 1,
    "offset": 1,
    "limit": 1
  }
}

Cancel Digital Product Purchase

post

Cancels a digital product purchase and refunds the payment.

Important: This endpoint only supports refunds for purchases paid with Telegram Stars. Purchases paid with other payment methods cannot be refunded via this endpoint.

Authorizations

Api-KeystringRequired

API key for authentication.

Path parameters

purchaseIdintegerRequired

Digital product purchase ID (ProductPurchase.ID)

Example: 12345

Responses

200

Purchase successfully cancelled and payment refunded

application/json

successbooleanRequired

Operation success status

Example: true

purchaseIdintegerRequired

Cancelled purchase ID

Example: 12345

messagestringRequired

Success message

Example: purchase cancelled and payment refunded

400

Bad request

application/json

401

Unauthorized (invalid API key)

application/json

403

Access denied (not the product owner)

application/json

404

Purchase or user not found

application/json

500

Internal server error

application/json

post/products/purchases/{purchaseId}/cancel

POST /api/v1/products/purchases/{purchaseId}/cancel HTTP/1.1
Host: tribute.tg
Api-Key: YOUR_API_KEY
Accept: */*

{
  "success": true,
  "purchaseId": 12345,
  "message": "purchase cancelled and payment refunded"
}

New Digital Product Purchase

Notification about a digital product purchase

Payload

namestring · enumRequiredExample: new_digital_productPossible values:

created_atstring · date-timeRequired

Event creation time

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

sent_atstring · date-timeRequired

Event sending time

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

Responses

200

Webhook successfully processed

application/json

statusstringOptionalExample: ok

400

Invalid webhook data

401

Invalid webhook signature

Payload

{
  "name": "new_digital_product",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "product_id": 456,
    "product_name": "VPN Access - 1 Month",
    "amount": 500,
    "currency": "usd",
    "trb_user_id": "T-31326",
    "telegram_user_id": 12321321,
    "telegram_username": "durov",
    "purchase_id": 78901,
    "transaction_id": 234567,
    "purchase_created_at": "2025-03-20T01:15:58.33246Z"
  }
}

Digital Product Refunded

Notification about a digital product refund. This webhook is triggered when:

A user refunds Stars through App Store, Google Play, or their bank
A creator initiates a refund via the API

Important: Use purchase_id to match refunds with original purchases and revoke access to digital content.

Payload

namestring · enumRequiredExample: digital_product_refundedPossible values:

created_atstring · date-timeRequired

Event creation time

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

sent_atstring · date-timeRequired

Event sending time

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

Responses

200

Webhook successfully processed

application/json

statusstringOptionalExample: ok

400

Invalid webhook data

401

Invalid webhook signature

Payload

{
  "name": "digital_product_refunded",
  "created_at": "2025-03-20T01:15:58.33246Z",
  "sent_at": "2025-03-20T01:15:58.542279448Z",
  "payload": {
    "product_id": 456,
    "product_name": "VPN Access - 1 Month",
    "amount": 500,
    "currency": "usd",
    "trb_user_id": "T-31326",
    "telegram_user_id": 12321321,
    "telegram_username": "durov",
    "purchase_id": 78901,
    "transaction_id": 234567,
    "refund_reason": "telegram_refund",
    "refunded_at": "2025-03-20T02:30:00.33246Z"
  }
}

Creating different tariffs

For different tiers, create several digital products:

AI Assistant - 1 month (ID: 456) - $9.99
AI Assistant - 3 months (ID: 457) - $24.99
AI Assistant - 1 year (ID: 458) - $79.99

Handling retry attempts

When webhook delivery fails, Tribute retries after:

5 minutes
15 minutes
30 minutes
1 hour
10 hours

Make sure your handler is idempotent (reprocessing the same payment won't create duplicates).

Withdrawals

You can withdraw earned funds in USDT (bank card withdrawals will be added in the future). Set up automatic withdrawals in the "Wallet" section.

Frequently Asked Questions

How quickly do webhooks arrive?

Usually within 1-2 seconds after successful payment.

Can I cancel a payment?

Digital products can be canceled through Tribute support.

PreviousHow to set up web payment for digital products NextStatistics

Last updated 5 days ago