Payments Integration

TL;DR:

• Enable Telegram Stars for native virtual currency payments — no API keys needed.
• Connect Stripe to accept credit and debit cards via Stripe Checkout.
• You can enable both payment methods at the same time.

Who this is for

• Workspace owners and admins who want to sell products or services directly in Telegram.
• Anyone needing to accept payments from users inside bot conversations.

What you will learn

• How to enable Telegram Stars — the simplest payment method.
• How to configure Stripe with API keys and webhooks.
• Which payment method to choose for your use case.
• How to troubleshoot common payment issues.

Overview

Configure payment providers to accept payments directly inside your Telegram bot. The platform supports two payment methods: Telegram Stars and Stripe.

Key concepts

• Telegram Stars — Telegram's native virtual currency. Users buy Stars in Telegram and spend them in bots.
• Stripe — global payment processor for credit/debit cards.
• Product — an item you sell that can accept one or both payment methods.

TIP

You can enable both payment methods at the same time. Users can choose which method to use at checkout.

In the UI

• Location: Workspace Settings → Integrations → Payments
• Main controls:
  • Telegram Stars toggle — enables/disables Stars payments.
  • Stripe toggle — enables/disables Stripe payments.
  • Stripe Configure button — opens modal to enter API keys.

Telegram Stars

Telegram Stars is the native virtual currency on Telegram. Users can purchase Stars directly in Telegram and use them to pay for products and services inside bots.

How to enable

1. Open Workspace Settings → Integrations and click the Payments tab.
2. Find Telegram Stars in the list.
3. Toggle the switch to enable.
4. Click Save if prompted.

That's it — no API keys or configuration needed. Telegram handles Stars payments automatically.

How it works for users

When a user selects Telegram Stars as payment:

1. They see a payment preview with the amount in Stars.
2. They confirm the payment using Telegram's built-in payment flow.
3. Stars are deducted from their balance and transferred to your workspace.

INFO

For more details on accepting Stars in products, see Products & Payments.

Requirements

• Telegram Stars must be enabled in your workspace settings.
• Products must be configured with Stars as an accepted payment method.
• Your workspace must meet Telegram's requirements for accepting payments (typically requires being a verified business).

Stripe

Stripe is a global payment processor that accepts credit and debit cards. Use Stripe when you want to accept traditional card payments.

How to enable

1. Open Workspace Settings → Integrations and click the Payments tab.
2. Find Stripe in the list.
3. Click Configure to open the Stripe settings modal.
4. Enter your Stripe API keys:
   • Publishable Key — starts with pk_...
   • Secret Key — starts with sk_...
5. Configure the webhook URL in your Stripe dashboard:
   • Copy the webhook URL from the settings modal
   • Go to Stripe Dashboard → Webhooks
   • Add the webhook URL and select events: checkout.session.completed, payment_intent.succeeded, payment_intent.payment_failed
6. Toggle the switch to enable Stripe.
7. Click Save.

How it works for users

When a user selects Stripe as payment:

1. They are redirected to Stripe Checkout to enter card details.
2. After successful payment, they are redirected back to your bot.
3. The bot receives a webhook from Stripe confirming the payment.

INFO

For more details on Stripe integration in products, see Products & Payments.

Requirements

• A Stripe account (sign up at stripe.com).
• Publishable and Secret API keys from your Stripe dashboard.
• Webhook endpoint configured to receive payment events.

Configuration details

Setting	Description
Publishable Key	Frontend key for Stripe Checkout (starts with pk_)
Secret Key	Backend key for API calls (starts with sk_)
Webhook URL	URL Stripe sends payment events to
Webhook Secret	Key to verify webhook signatures

Examples

Example 1 — Digital product with Stars

Goal: Sell a digital guide for 50 Stars.
Setup: Enable Telegram Stars in workspace settings. Create a product priced at 50 Stars.
Result: Users can buy instantly without leaving Telegram.

Example 2 — Premium subscription with card

Goal: Sell a monthly subscription for $9.99.
Setup: Enable Stripe, enter production API keys. Create a recurring product.
Result: Users pay via Stripe Checkout and are redirected back to the bot.

Example 3 — Both payment options

Goal: Let users choose how to pay.
Setup: Enable both Telegram Stars and Stripe. Create a product accepting both methods.
Result: At checkout, users see both options and pick their preference.

Troubleshooting

Symptom: Users cannot pay with Stars

Cause: Telegram Stars is disabled, product doesn't accept Stars, or workspace isn't allowed to accept payments.
Fix: Verify that Telegram Stars is enabled in Workspace Settings → Integrations → Payments. Check that the product accepts Stars as a payment method.
Prevention: Ensure your workspace meets Telegram's requirements for accepting payments.

Symptom: Stripe checkout not loading

Cause: Invalid or expired API keys, or webhook URL not publicly accessible.
Fix: Verify your API keys are correct and not expired. Check that the webhook URL is publicly accessible.
Prevention: Use environment variables or secrets management for API keys.

Symptom: Payments not being recognized

Cause: Webhook not configured correctly in Stripe Dashboard with the required events.
Fix: Check that webhook is configured in Stripe Dashboard with the correct events. Verify the webhook URL matches the one shown in your workspace settings.
Prevention: Double-check webhook configuration after any changes in Stripe Dashboard.

Symptom: Test payments not working

Cause: Using production keys instead of test mode keys.
Fix: Use Stripe's test mode keys (starting with sk_test_ / pk_test_) for testing.
Prevention: Keep test and production keys separate.

FAQ

• Q: Can I use both payment methods at the same time?
  A: Yes. Enable both and configure products to accept one or both methods.

• Q: Do I need a business verification for Telegram Stars?
  A: Typically yes. Telegram requires businesses to be verified to accept Stars payments.

• Q: How do I test Stripe payments without using real money?
  A: Use Stripe's test mode with test API keys and test card numbers from Stripe documentation.

• Q: What happens when a payment fails?
  A: The user is notified of the failure. You can configure retry logic in your scenario.

• Q: Can I refund a payment?
  A: Yes, through your Stripe Dashboard or Telegram Stars management interface.

Related pages

• Products & Payments — creating products with payment options
• Message Node — selling products in conversations
• Integrations Overview

Notes / Limits

• Payment integration may be feature-gated by plan.
• Telegram Stars availability depends on your region and Telegram's policies.
• Stripe requires a verified Stripe account.
• Webhook must be publicly accessible for Stripe to send payment events.
• Both payment methods can be enabled simultaneously.