# Integrating Digital Products into Your Product
### 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](https://wiki.tribute.tg/en/for-content-creators/digital-product/how-to-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://t.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](https://wiki.tribute.tg/for-content-creators/api-documentation/webhooks#newdigitalproduct)
#### 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
1. Open [@tribute](https://t.me/tribute) in Telegram
2. Click "Start" and follow the instructions
3. Go to the "Author Dashboard" section
#### Step 2: Creating a digital product
1. **In the dashboard, select "Digital Products" → "Create instant product"**
2. **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).
3. **After sending the message, click the "Create Product" button from the bot's message**
4. **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
5. **Save the product**
After saving, you will receive a unique payment link that can be used in your integration
#### Step 3: Getting API key
1. In the dashboard, open the menu (three dots) → "Settings"
2. Go to the "API Keys" section
3. Click "Generate New Key"
4. Save the key in a safe place - you'll need it to verify webhooks
#### Step 4: Setting up webhooks
1. In the "API Keys" section, find the "Webhook URL" field
2. Specify your server address for receiving webhooks:
```
https://your-server.com/webhook/tribute
```
3. 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
```json
{
"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](https://wiki.tribute.tg/for-content-creators/api-documentation/webhooks)
#### Step 6: Integration into your bot
In your Telegram bot, add a payment button
Python code
```python
# Python + python-telegram-bot
from telegram import InlineKeyboardButton, InlineKeyboardMarkup
def send_payment_button(update, context):
keyboard = [[
InlineKeyboardButton(
"💳 Pay ($9.99)",
url="https://t.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
> Returns a single product by its ID
```json
{"openapi":"3.1.0","info":{"title":"Tribute API","version":"1.0.0"},"tags":[{"name":"Products","description":"Product operations. Products exist in three types:\n\n- `digital` - [Digital product](https://wiki.tribute.tg/for-content-creators/digital-product). Any Telegram message with optional attachments\n- `custom` - [Custom product](https://wiki.tribute.tg/for-content-creators/digital-product/digital-custom-product). On-demand content, e.g., personalized video greetings\n- `physical` - [Physical product](https://wiki.tribute.tg/for-content-creators/fizicheskie-tovary). Merchandise with shipping, e.g., printed t-shirts\n\nAll amounts are in smallest currency units (cents/kopecks)\n"}],"servers":[{"url":"https://tribute.tg/api/v1","description":"Tribute API v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API key for authentication."}},"schemas":{"Product":{"type":"object","required":["id","type","name","amount","currency","status","isCustom","acceptCards","acceptWalletPay","protectContent","created","updated","link","webLink"],"properties":{"id":{"type":"integer","description":"Product ID"},"type":{"type":"string","description":"Product type","enum":["digital","custom","physical"]},"name":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"},"amount":{"type":"integer","format":"int64","description":"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."},"currency":{"type":"string","description":"Currency code","enum":["USD","EUR","RUB"]},"starsAmount":{"type":"integer","description":"Price in Telegram Stars"},"starsAmountEnabled":{"type":"boolean","description":"Whether payment with Stars is enabled"},"status":{"type":"string","description":"Product status","enum":["pending","approved","rejected"]},"isCustom":{"type":"boolean","description":"Whether this is a custom product"},"acceptCards":{"type":"boolean","description":"Whether card payments are accepted"},"acceptWalletPay":{"type":"boolean","description":"Whether wallet payments are accepted"},"protectContent":{"type":"boolean","description":"Whether content protection is enabled"},"created":{"type":"string","format":"date-time","description":"Product creation date"},"updated":{"type":"string","format":"date-time","description":"Product last update date"},"pendingOrders":{"type":"integer","description":"Number of pending orders (for custom products)"},"imageUrl":{"type":"string","format":"uri","description":"Product image URL"},"link":{"type":"string","format":"uri","description":"Direct link to product in Telegram app"},"webLink":{"type":"string","format":"uri","description":"Web link to product"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code","enum":["error_bad_request","error_not_found","error_not_permitted","no_access"]},"message":{"type":"string","description":"Error description"}}}}},"paths":{"/products/{id}":{"get":{"summary":"Get Product by ID","description":"Returns a single product by its ID","tags":["Products"],"parameters":[{"name":"id","in":"path","description":"Product ID","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Product"}}}},"400":{"description":"Bad request (invalid product ID format)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Product not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Get Products List
> Returns a paginated list of products
```json
{"openapi":"3.1.0","info":{"title":"Tribute API","version":"1.0.0"},"tags":[{"name":"Products","description":"Product operations. Products exist in three types:\n\n- `digital` - [Digital product](https://wiki.tribute.tg/for-content-creators/digital-product). Any Telegram message with optional attachments\n- `custom` - [Custom product](https://wiki.tribute.tg/for-content-creators/digital-product/digital-custom-product). On-demand content, e.g., personalized video greetings\n- `physical` - [Physical product](https://wiki.tribute.tg/for-content-creators/fizicheskie-tovary). Merchandise with shipping, e.g., printed t-shirts\n\nAll amounts are in smallest currency units (cents/kopecks)\n"}],"servers":[{"url":"https://tribute.tg/api/v1","description":"Tribute API v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API key for authentication."}},"schemas":{"Product":{"type":"object","required":["id","type","name","amount","currency","status","isCustom","acceptCards","acceptWalletPay","protectContent","created","updated","link","webLink"],"properties":{"id":{"type":"integer","description":"Product ID"},"type":{"type":"string","description":"Product type","enum":["digital","custom","physical"]},"name":{"type":"string","description":"Product name"},"description":{"type":"string","description":"Product description"},"amount":{"type":"integer","format":"int64","description":"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."},"currency":{"type":"string","description":"Currency code","enum":["USD","EUR","RUB"]},"starsAmount":{"type":"integer","description":"Price in Telegram Stars"},"starsAmountEnabled":{"type":"boolean","description":"Whether payment with Stars is enabled"},"status":{"type":"string","description":"Product status","enum":["pending","approved","rejected"]},"isCustom":{"type":"boolean","description":"Whether this is a custom product"},"acceptCards":{"type":"boolean","description":"Whether card payments are accepted"},"acceptWalletPay":{"type":"boolean","description":"Whether wallet payments are accepted"},"protectContent":{"type":"boolean","description":"Whether content protection is enabled"},"created":{"type":"string","format":"date-time","description":"Product creation date"},"updated":{"type":"string","format":"date-time","description":"Product last update date"},"pendingOrders":{"type":"integer","description":"Number of pending orders (for custom products)"},"imageUrl":{"type":"string","format":"uri","description":"Product image URL"},"link":{"type":"string","format":"uri","description":"Direct link to product in Telegram app"},"webLink":{"type":"string","format":"uri","description":"Web link to product"}}},"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code","enum":["error_bad_request","error_not_found","error_not_permitted","no_access"]},"message":{"type":"string","description":"Error description"}}}}},"paths":{"/products":{"get":{"summary":"Get Products List","description":"Returns a paginated list of products","tags":["Products"],"parameters":[{"name":"page","in":"query","description":"Page number","required":false,"schema":{"type":"integer","minimum":1,"default":1}},{"name":"size","in":"query","description":"Items per page","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"type","in":"query","description":"Filter by product type","required":false,"schema":{"type":"string","enum":["digital","custom","physical"]}},{"name":"desc","in":"query","description":"Sort by ID descending","required":false,"schema":{"type":"boolean","default":false}}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"type":"object","properties":{"rows":{"type":"array","items":{"$ref":"#/components/schemas/Product"}},"meta":{"type":"object","properties":{"total":{"type":"integer","format":"int64","description":"Total number of items"},"offset":{"type":"integer","format":"int64","description":"Current page number"},"limit":{"type":"integer","format":"int64","description":"Page size"}}}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Cancel Digital Product Purchase
> 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.
```json
{"openapi":"3.1.0","info":{"title":"Tribute API","version":"1.0.0"},"tags":[{"name":"Products","description":"Product operations. Products exist in three types:\n\n- `digital` - [Digital product](https://wiki.tribute.tg/for-content-creators/digital-product). Any Telegram message with optional attachments\n- `custom` - [Custom product](https://wiki.tribute.tg/for-content-creators/digital-product/digital-custom-product). On-demand content, e.g., personalized video greetings\n- `physical` - [Physical product](https://wiki.tribute.tg/for-content-creators/fizicheskie-tovary). Merchandise with shipping, e.g., printed t-shirts\n\nAll amounts are in smallest currency units (cents/kopecks)\n"}],"servers":[{"url":"https://tribute.tg/api/v1","description":"Tribute API v1"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"Api-Key","description":"API key for authentication."}},"schemas":{"Error":{"type":"object","required":["error","message"],"properties":{"error":{"type":"string","description":"Error code","enum":["error_bad_request","error_not_found","error_not_permitted","no_access"]},"message":{"type":"string","description":"Error description"}}}}},"paths":{"/products/purchases/{purchaseId}/cancel":{"post":{"summary":"Cancel Digital Product Purchase","description":"Cancels a digital product purchase and refunds the payment.\n\n**Important:** This endpoint only supports refunds for purchases paid with Telegram Stars.\nPurchases paid with other payment methods cannot be refunded via this endpoint.\n","tags":["Products"],"parameters":[{"name":"purchaseId","in":"path","description":"Digital product purchase ID (ProductPurchase.ID)","required":true,"schema":{"type":"integer"}}],"responses":{"200":{"description":"Purchase successfully cancelled and payment refunded","content":{"application/json":{"schema":{"type":"object","required":["success","purchaseId","message"],"properties":{"success":{"type":"boolean","description":"Operation success status"},"purchaseId":{"type":"integer","description":"Cancelled purchase ID"},"message":{"type":"string","description":"Success message"}}}}}},"400":{"description":"Bad request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized (invalid API key)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Access denied (not the product owner)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Purchase or user not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
{% openapi-webhook spec="api-en" name="newDigitalProduct" method="post" %}
[api-en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
{% openapi-webhook spec="api-en" name="digitalProductRefund" method="post" %}
[api-en](https://tribute.tg/api/v1/openapi/en)
{% endopenapi-webhook %}
### Creating different tariffs
For different tiers, create several digital products:
1. **AI Assistant - 1 month** (ID: 456) - $9.99
2. **AI Assistant - 3 months** (ID: 457) - $24.99
3. **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.
***
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://wiki.tribute.tg/for-content-creators/info-products-and-content/api-integration.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.