Setting up payments via Telegram Bots

Download the instructions in PDF format

To accept payments via Telegram, you will need to do three things:

To set up payments via the bot, you will need the shopId parameter that you can get after signing up for Yandex.Checkout.

How to create a bot

1. Open the chat with @BotFather in Telegram, send the /start command, then /newbot.

2. Give the bot a name and a username. The bot's name will be shown in the contact list and at the top of the chat, it can be non-unique. The username will be in the short link to the bot, and it must be unique.

3. Example:

Yandex.Checkout is the bot's name

YandexCheckoutPaymentBot is the bot's username

4. If the username is not taken, BotFather will respond to with the token, i.e. the "key" to access the created bot. Don't give this token to anyone else, even the Yandex.Checkout's or Telegram's support services.

Once you have the key, the bot is ready: you can add an icon and configure the dialog patterns for customers. You can also set up payments via the bot.

How to connect your bot to the Yandex.Checkout bot

1. Send the /mybots command to @BotFather. Click on your bot's name.

2. Select BotSettings — Payments in the bot's dashboard.

3. Select Connect Yandex.Checkout: payments in the following menu.

4. This opens the chat with the Yandex.Checkout bot. Send him the /start command, then your shopId (you can copy it from your Yandex.Checkout Merchant Profile.)

5. The bot will ask for your shopArticleId. If you don't know this parameter, send a 0 (zero) in response.

6. Return to the chat with @BotFather. It will send you the token required for invoicing. You can always view the token via BotSettings — Payments.

Setting up the bot to process payments

1. Implement the sendinvoice method from Telegram's payment API: your bot will start sending invoices to clients in response to this request. Invoices should include the price, name, product description, payload parameter, and provider_token parameter—the token provided by @BotFather after you connected your bot to the Yandex.Checkout bot.

View an example of the sendinvoice request

If you set up fiscalization via Yandex.Checkout, you will need to send data for fiscalization to Yandex.Checkout by adding the following parameters to the request:

  • need_phone_number or need_email
  • send_email_to_provider (if you requested customer's email address) или send_phone_number_to_provider (if you requested customer's phone number),
  • provider_data, and the receipt object in it. View the Yandex.Checkout API to learn more (see section Attributes — receipt).
View an example

You can request the customer's phone number or email address earlier, during the chat with the bot. Then the first two parameters are not required, and provider_data with the receipt object would be enough.

View an example

More about 54-FZ in interaction with Yandex.Checkout

If you need the customer to provide you with an address for delivery, implement the Shipping Query method. When the user provides the address, respond to this query with the answerShippingQuery method. Indicate the delivery methods and their prices in this method.

2. When the user confirms the payment, Telegram will send you a webhook with Update containing the PreCheckoutQuery object. You need to respond to this query within 10 seconds by calling the answerPreCheckoutQuery method.

3. You will receive two notifications:

  • Telegram will send you a webhook with Update containing the SuccessfulPayment object,
  • Yandex.Checkout will send you an email notification of transfer.

What payments via Telegram bot looks like

As an example, let's take the replenishment of the mobile phone balance via the Yandex.Checkout test bot, @testymppbot.

Payments via this bot can only be made from mobile phone and only with a bank card. No commission is charged.

1. Send the /start command to @testymppbot bot, then /invoice.

2. Send the phone number you want to top up in 7 XXX XXX XX XX format.

3. Specify the amount you want to add to the balance. You can select one of the offered options or enter any other amount manually.

4. The bot will send you a generated invoice. Check the details and click Pay.

5. This opens the payment page: enter the bank card details and click Pay.

Please note: some stores may also ask for an email address or a phone number.

6. Click Pay and confirm the payment with the password from your bank.

7. That's it: check your balance.