Products & Payments

TL;DR:

• Create Products under Workspace Settings → Products & Payments to define what users can buy.
• Enable Telegram Stars or Stripe under Workspace Settings → Payments.
• Products are provider-specific — choose Stars or Stripe when creating.
• Use products in scenario nodes: Message payment buttons or Actions → Create payment.

Who this is for

• Workspace owners and admins setting up payments for the first time.
• Bot builders creating paid products for their scenarios.
• Support teams managing product availability.

What you will learn

• How to enable Telegram Stars and Stripe payment providers.
• How to create and manage products.
• How product pricing works for each provider.
• How to view payment logs and analytics.

Overview

The Payments section in Workspace Settings has three pages:

Page	Purpose
Payments	Enable/disable providers, configure Stripe credentials, view quick metrics.
Products	Create and manage products that define what users buy.
Payment Logs	View individual payment transactions with audit details.
Payment Analytics	Revenue, conversion, and order analytics over time.

---

Step 1: Enable a payment provider

Before creating products, enable at least one payment provider.

1. Open Workspace Settings → Payments.
2. Choose your provider:

Telegram Stars

• Click Enable Stars to toggle on.
• No additional configuration needed — Telegram handles the payment flow natively.

Stripe

1. Check Enable Stripe payments.
2. Enter your Publishable Key (pk_live_... or pk_test_...).
3. Enter your Secret Key (sk_live_... or rk_live_...).
4. Enter your Webhook Signing Secret (whsec_...).
5. Click Save Stripe Settings.
6. Click Test Connection to verify credentials.

Stripe webhook URL: Configure this in your Stripe Dashboard:

/api/webhooks/stripe/{your-org-uid}

Listen for events: checkout.session.completed and checkout.session.expired.

WARNING

Stripe keys are stored encrypted per-organization. Never share your secret key.

---

Step 2: Create a product

1. Open Workspace Settings → Products & Payments.
2. Click Create Product.
3. Select the Provider:
   • Telegram Stars (XTR) — user pays with Telegram Stars inside the chat.
   • Stripe (Card / USD) — user pays by card on a Stripe Checkout page.
4. Fill in the product form.
5. Save.

Product fields

Field	Required	Stars	Stripe	Description
Provider	yes	telegram_stars	stripe	Cannot be changed after creation.
Name	yes	✅	✅	Shown in selectors and product lists.
Description	no	✅	✅	Internal note for your team.
Price	yes	Whole Stars (min 1)	USD (min $0.50)	Stars stored as integer; Stripe stored as cents.
Stripe Product ID	no	—	prod_...	Link to an existing Stripe product.
Stripe Price ID	no	—	price_...	If set, used in Checkout instead of creating a new price.

Price storage

Provider	You enter	Stored as	Display
Telegram Stars	100	100 (integer)	⭐ 100 Stars
Stripe	9.99	999 (cents)	$9.99

---

Step 3: Manage products

The Products page shows all products in a table:

Column	Description
Name	Product name and description.
Price	⭐ Stars or $ USD depending on provider.
Status	Active (green) or Inactive (gray).
Provider	Badge showing Stars or Stripe.
Created	Creation date.

Actions

• Edit — change name, description, or price (not provider).
• Deactivate — hides the product from selectors. Existing scenarios keep the reference but new selections should use an active product.
• Restore — re-activates a deactivated product.

WARNING

A product used in a published scenario cannot be deactivated. Unpublish the scenario first.

---

Step 4: Use products in scenarios

Products are selected in scenario nodes — they are not configured in the Products page itself.

Node	How to use	Pattern
Message	Text card button -> Action: Payment -> select product	User clicks to pay
Actions	Add action -> Payments -> Create payment -> select product	Automatic invoice
Condition	Rule: Payment status -> select product + status (Paid / Failed / Subscription active)	Branch on result

INFO

See Message Node — Payment Button for how to add a payment button and the full payment flow.

---

Payment Logs

Workspace Settings → Payment Logs shows all payment transactions:

• Payment ID — unique identifier (pay_...).
• Product — which product was purchased.
• Amount — ⭐ Stars or $ USD.
• Status — Paid, Pending, or Failed.
• User — Telegram user ID.
• Charge ID — provider payment ID for audit.
• Date — when the payment was created.

Filters

Filter	Description
Status	All, Paid, Pending, Failed.
Provider	All, Telegram Stars, Stripe.
Date range	From / To date pickers.

---

Payment Analytics

Workspace Settings → Payment Analytics shows revenue and conversion data:

Summary cards

• Stars Revenue — total XTR earned.
• USD Revenue — total USD earned (Stripe).
• Orders — total payment count.
• Conversion Rate — paid / total orders.
• Avg Order Value — revenue / paid orders.

Charts

• Revenue Over Time — bar chart by period.
• Orders Over Time — bar chart by period.
• Status Distribution — paid / failed / pending breakdown.

Filters

• Period — Daily, Weekly, Monthly.
• Date range — From / To.

---

Troubleshooting

Product does not appear in scenario selectors

Symptom: The product dropdown says no active products found. Cause: No active product exists, or the product is deactivated. Fix: Create or restore a product under Workspace Settings → Products & Payments.

Stripe "Test Connection" fails

Symptom: Error when clicking Test Connection. Cause: Invalid secret key or network issue. Fix: Verify the secret key starts with sk_live_ or sk_test_ and has not been revoked.

Stripe webhook not receiving events

Symptom: Payments complete on Stripe but status stays Pending. Cause: Webhook URL not configured or webhook secret mismatch. Fix: Set the webhook URL in Stripe Dashboard to /api/webhooks/stripe/{your-org-uid} and verify the signing secret matches.

Cannot deactivate a product

Symptom: Deactivate button returns an error. Cause: The product is used in a published scenario. Fix: Unpublish the scenario first, then deactivate the product.

---

FAQ

• Q: Can I use both Stars and Stripe for the same product?A: No. Each product has exactly one provider. Create two separate products if you want to offer both payment methods.

• Q: Can I change a product's provider after creation?A: No. Provider is fixed at creation. Create a new product with the other provider if needed.

• Q: Are Stripe prices in dollars or cents?A: You enter dollars (e.g. 9.99). Internally it's stored as cents (999). The UI displays $9.99.

• Q: Do refunds revoke access automatically?A: No. Neither Stars nor Stripe refunds trigger automatic access revocation. You must handle this manually or via scenario logic.

• Q: Where do I see Stripe payment details?A: Payment Logs shows all transactions. The Charge ID column shows Stripe's payment intent or checkout session ID.

---

Related pages

• Message Node — Payment Button — how to add a payment button and payment flow patterns.
• Condition Node — check payment status after a purchase.
• Roles & Permissions — who can access payment settings.
• Integrations — Sync HTTP and webhook configurations.