---
name: telegram-payments
description: >-
  Guides through accepting Telegram bot payments via Smart Glocal API:
  connecting your bot via BotFather, sending invoices via sendInvoice,
  handling PreCheckoutQuery and answerPreCheckoutQuery, 3DS redirect,
  and recurring payments with save_card.
---

# Telegram Payments

## Purpose

Use this skill to accept payments directly inside a Telegram chat — the buyer pays without leaving the app. Covers bot connection, invoice sending, PreCheckoutQuery handling, 3DS, and recurring payments.

## Primary references

- [Telegram Bot API: sendInvoice](https://core.telegram.org/bots/api#sendinvoice)
- [Telegram Bot API: answerPreCheckoutQuery](https://core.telegram.org/bots/api#answerprecheckoutquery)
- [Connecting a Telegram bot](https://developer.smart-glocal.com/payments/payment-telegram-bot-connect)
- [Using your bot for payments](https://developer.smart-glocal.com/payments/payment-telegram-bot-use)
- [Recurring payments](https://developer.smart-glocal.com/payments/payment-recurring)

## Preconditions

- [ ] Telegram bot created via @BotFather
- [ ] Smart Glocal connected in @BotFather (Test or Live)
- [ ] `provider_token` obtained from @BotFather
- [ ] RSA keys and authentication configured (see [getting-started](https://developer.smart-glocal.com/assets/skills/getting-started/SKILL.md))

---

## 1. Connect Your Bot

### 1.1. Create a Bot (if you don't have one)

In Telegram: @BotFather → `/newbot` → get your `bot_token`.

### 1.2. Connect Smart Glocal

In @BotFather: `/mybots` → select your bot → **Payments** → scroll with arrow buttons until you see **Smart Glocal Test** (sandbox) or **Smart Glocal Live** (production). Select it → follow the instructions.

After connecting, @BotFather will issue a **provider_token** that you need to send invoices.

> **Two modes:**
> - **Smart Glocal Test** — test payments (via `demo.smart-glocal.com`)
> - **Smart Glocal Live** — real payments (via `proxy.smart-glocal.com`)

## 2. Payment Flow

```
Your bot → sendInvoice → Telegram → payment form
  → buyer taps "Pay"
  → Telegram → PreCheckoutQuery → your bot → answerPreCheckoutQuery
  → [3DS → action_required] → payment_finished (Smart Glocal)
  → SuccessfulPayment (Telegram)
```

## 3. Send an Invoice

Call the Telegram API method `sendInvoice` from your bot:

```json
{
  "chat_id": 123456789,
  "title": "Premium Subscription",
  "description": "Monthly subscription",
  "payload": "order_456",
  "provider_token": "0987654321:TEST",
  "currency": "USD",
  "prices": [{
    "label": "Amount",
    "amount": 2000
  }],
  "provider_data": {
    "email": "john@example.com",
    "full_name": "John Johnson",
    "country_iso2": "US",
    "ipv4": "127.0.0.1"
  },
  "need_phone_number": true
}
```

### provider_data (optional)

Additional data for the payment form. If not provided, Smart Glocal will ask the buyer to enter them manually:

| Field | Description |
|-------|-------------|
| `email` | Buyer's email |
| `full_name` | Full name |
| `city` | City |
| `state` | State (for US) |
| `address_line` | Address |
| `postal_code` | Postal code |
| `country_iso2` | Country code (ISO 3166-1 alpha-2) |
| `country_iso3` | Country code (ISO 3166-1 alpha-3) |
| `ipv4` | IPv4 address |

### Notes

- **Idempotency keys are not supported** — Telegram API doesn't use them.
- Amount in `prices[].amount` is in **cents/smallest currency unit** (2000 = 20 USD).

## 4. Handle PreCheckoutQuery

After the buyer taps "Pay", Telegram sends a `PreCheckoutQuery` object to your bot. Respond with `answerPreCheckoutQuery`:

```
bot.answerPreCheckoutQuery(pre_checkout_query_id, ok=True)
```

If everything is fine — pass `ok=True`. If there's an error (e.g., item out of stock) — pass `ok=False` with an error description.

## 5. 3D Secure

If the card requires 3DS:
- Smart Glocal sends an `action_required` webhook
- Telegram redirects the buyer for 3DS authentication
- After authentication, the payment continues automatically

## 6. Result

After a successful payment, you receive:

1. **`payment_finished`** from Smart Glocal (webhook) — final payment status
2. **`SuccessfulPayment`** from Telegram — contains `provider_payment_charge_id` (transaction ID). Save it for reconciliation.

## 7. Recurring (Save Card)

Telegram allows saving the buyer's card after the first payment for recurring charges.

### Option A: Checkbox in the UI

Telegram shows a "Save card" checkbox in the payment form automatically.

### Option B: save_card Parameter

Pass in `provider_data`:

```json
"provider_data": {
  "save_card": true
}
```

After a successful first payment, you receive a `recurrent` token in the `payment_finished` webhook. Subsequent payments use the standard [recurring flow](https://developer.smart-glocal.com/assets/skills/recurring/SKILL.md) with this token.