Telegram Bot Crypto Payments

Take crypto payments in a Telegram bot for subscriptions or access.

Open the interactive version or read this guide as markdown.

Tags: Telegram, Payments, Webhooks, Node.js

Paste this prompt into Claude, ChatGPT, or any AI tool. It works best with the CoinCircuit MCP server connected: https://mcp.coincircuit.io

You are helping me integrate CoinCircuit crypto payments into my existing Telegram bot. I have the CoinCircuit MCP server connected.

If you have access to the CoinCircuit MCP server, call these tools for the most accurate and detailed schema outputs:

Use the live MCP data as your source of truth. The details below are a guide, but if the MCP returns something different, trust the MCP.

API Basics

Project Context

I have an existing Telegram bot and I want to add crypto payment support using CoinCircuit. The integration should:

  1. Create a CoinCircuit payment session when a user wants to pay
  2. Send the hosted checkout URL to the user in chat
  3. Listen for payment confirmation via webhook
  4. Trigger the appropriate action in my bot (grant access, deliver content, activate subscription, etc.)

This pattern works for any Telegram bot use case: subscription access, one-time purchases, premium features, tip jars, or pay-per-use commands.

What I Need You to Implement

1. Create a payment session from a bot command

When a user triggers a payment (e.g. via a command or button callback), create a CoinCircuit payment session from your bot's backend:

Endpoint: POST /api/v1/payments (Call get_endpoint with method post, path /api/v1/payments, section request in the CoinCircuit MCP for the exact request body schema.)

Required fields:

Optional fields:

Example request body:

{
  "title": "Premium Channel - 30 Days",
  "description": "Subscription payment for premium Telegram access",
  "amount": "9.99",
  "currency": "USD",
  "customer": {
    "email": "user@example.com",
    "telegramId": "123456789"
  },
  "metadata": {
    "telegramUserId": "123456789",
    "telegramUsername": "johndoe",
    "plan": "premium-monthly",
    "channelId": "-1001234567890",
    "subscriptionPeriodEnd": "2026-04-30T23:59:59.000Z"
  },
  "successUrl": "https://mybot.com/subscription/success"
}

Response (201): Returns a session object. Key fields:

(Call get_endpoint with method post, path /api/v1/payments, section success in the CoinCircuit MCP for the full response schema.)

2. Send checkout link to the user

After creating the session, send the data.url to the user in chat. The hosted checkout page handles crypto selection, address display, and payment detection automatically. No additional frontend work needed.

3. Webhook handler: process payment confirmation

Set up an endpoint to receive CoinCircuit webhooks. This is where your bot takes action after payment.

(Call get_schema with name PaymentCompletedWebhookDto in the CoinCircuit MCP for the full payload.)

Payment events (envelope: { event: string, data: { session: PaymentSession } }):

Transaction events:

Webhook security:

4. Track payment state

Store a record linking the CoinCircuit session to your bot's user:

This lets you look up payment status when a user asks, and lets your webhook handler find the right user to notify.

5. Recurring payments (if applicable)

For subscription-based flows, create a new payment session each billing cycle:

  1. Before expiry: Send the user a renewal payment link
  2. On expiry: If not renewed, revoke access or downgrade
  3. On renewal payment: Update the subscription period

Store the subscriptionPeriodEnd in session metadata so your webhook handler knows the new expiry.

Constraints