Hi! This article is aimed at developers who already possess working knowledge of Telegram-Powered Bots, and want to implement a monetization option. I will outline the basic steps which must be undertaken to get your bot to start accepting payments using the official Bot payment API and Paymentwall provider.
This article does not go into technical detail and discuss any code necessary for implementation, but it can give you a basic general understanding of the integration process.
What is Bot Payments API?
Last year, Telegram released an important update which facilitated the creation of bots to generate invoice message and show native payment dialogue. However, this feature is currently only supported on mobile devices and is not compatible with the desktop and web version. As Telegram official documentation says:
Telegram bots can accept payments for goods and services from users as of Bot API v.3.0. Users will need Telegram v.4.0 or higher to pay for your goods and services.
Using Telegram Web, the user will not be able to get even invoice message. Attempting to open a payment dialogue with the desktop or web version will result in the following error message:
However, don’t fret as almost all payment processors offer you the opportunity to generate a payment widget which can be integrated in your bot and opened using a browser. You will need to add all the relevant product details. You will need to specify your product details, like price, name, currency, etc to get the link. All payment processors will provide technical documentation about implementation:
So now you have two possibilities for using your bot:
- In-app payment (Bot Payments API)
- Using web payment widget (Payment provider API should support this)
I decided to implement both in my bot game, see the screenshot below:
In-app and web payments
Using Telegram Bot API you won’t be able to get user location, which means that you will be unable to specify the necessary currency for invoicing. There are no chance to track user location even through analytics tools like Yandex AppMetrica or Google Analytics (you will track Botswana as a location for every user). But you still can give your user a UI to select currency.
Also, there is no chance to get user client platform from your bot message data**.** So you can’t switch payment options on the fly based on user platform.
Summing up:
- Only credit card payments
- Available for Telegram mobile apps only
- Users will pay inside the application
💳 Payment provider
Telegram does not process payments from users and instead relies on 3rd party payment processors. They are the ones that will handle and store all the sensitive information such as card details, name and address. Neither Telegram nor the bot developers have access to it.
So, Telegram acts like a middleware between user and payment provider, and it also doesn’t charge any commission for this option. At the moment Telegram Bot Payments API is integrated with several payment processors:
I was looking for payment provider which will support processing for users from CIS region and Paymentwall came across as the best option for myself. It’s API provides support for generating payment widget for the browser as well as processing credit cards payments through Bot Payments API, furthermore, it supports a far larger number of countries in comparison to the providers mentioned in the list above.
🇺🇸 🇨🇦 🇩🇿 🇦🇸 🇦🇩 🇦🇷 🇦🇲 🇸🇭 🇦🇺 🇦🇹 🇦🇿 🇧🇸 🇧🇭 🇧🇩 🇧🇧 🇧🇪 🇧🇿 🇧🇲 🇧🇷 🇧🇳 🇧🇬 🇰🇭 🇰🇾 🇨🇱 🇨🇳 🇨🇰 🇨🇷 🇭🇷 🇨🇾 🇨🇿 🇩🇰 🇩🇲 🇩🇴 🇪🇨 🇪🇬 🇸🇻 🇪🇪 🇫🇰 🇫🇴 🇫🇯 🇫🇮 🇫🇷 🇬🇫 🇵🇫 🇬🇪 🇩🇪 🇬🇮 🇬🇷 🇬🇱 🇬🇩 🇬🇵 🇬🇺 🇬🇹 🇬🇾 🇭🇳 🇭🇰 🇭🇺 🇮🇸 🇮🇳 🇮🇩 🇮🇪 🇮🇲 🇮🇱 🇮🇹 🇯🇲 🇯🇵 🇯🇴 🇰🇿 🇰🇷 🇰🇼 🇰🇬 🇱🇻 🇱🇮 🇱🇹 🇱🇺 🇲🇴 🇲🇰 🇲🇾 🇲🇻 🇲🇹 🇲🇭 🇲🇶 🇲🇺 🇲🇽 🇲🇩 🇲🇨 🇲🇪 🇲🇦 🇳🇵 🇳🇱 🇳🇨 🇳🇿 🇳🇮 🇳🇺 🇳🇫 🇲🇵 🇳🇴 🇴🇲 🇵🇼 🇵🇦 🇵🇾 🇵🇪 🇵🇭 🇵🇳 🇵🇱 🇵🇹 🇵🇷 🇶🇦 🇷🇪 🇷🇴 🇷🇺 🇻🇨 🇸🇲 🇸🇦 🇷🇸 🇸🇨 🇸🇬 🇸🇰 🇸🇮 🇿🇦 🇬🇸 🇪🇸 🇱🇰 🇰🇳 🇱🇨 🇵🇲 🇸🇷 🇸🇪 🇨🇭 🇹🇼 🇹🇭 🇹🇰 🇹🇴 🇹🇹 🇹🇷 🇹🇲 🇹🇨 🇹🇻 🇺🇦 🇦🇪 🇬🇧 🇺🇾 🇻🇳 🇻🇬 🇻🇮 🇼🇫 🇼🇸 🇦🇼
I haven’t made a comparison between rates and the commission surcharge for each and every, so it’s entirely possible that other providers might be cheaper than Paymentwall. You can carry out some independent research and pick the one that will fit your bill. The main requirement is that your provider’s API should have an option to generate payment widget for the browser as well as support Bot Payments API.
Please note, that every provider will verify you as a merchant, and you should be ready to send them all of required documents when requested. Products you want to sell, and your bot will be verified based on provider rules and restrictions. They will verify you in order to make sure that you are selling authentic products.
For example, here is the list of prohibited areas that Paymentwall will not be able to work with.
In my case, I was planning to sell an in-game virtual currency, so it was a typical case for verification process. My verification took approximately 2 weeks, but that’s because I wasn’t able to prepare all documents in time, so it could be faster. I was receiving full support about needed documents and technical integration during set up.
Summing up:
- Your provider should support Bot Payments API as well as payment widget generation for the browser.
- It should have convenient rates and commissions that will fit your expectations.
- Should support your target countries, and credit cards processing in that countries.
📃 Terms and conditions
You must have clear terms and conditions document with the refund policy. Users should accept it before actual payment or before registration. You also must provide customer support and be able to handle refund or other payments related requests from your bot users, they shouldn’t go to payment provider or Telegram support.
There are no strict rules about writing terms and conditions, but the main point that you should specify in which period your user can request a refund after the payment was done.
Refund — Product return, a process in which a consumer returns a product to the original retailer in exchange for money previously paid. Money back guarantee — a guarantee that, if a buyer is not satisfied with a product or service, a refund will be made.
Here are the Terms and Conditions from my bot game. Feel free to use it as an example for your bot. I’m showing it in the payments step because I don’t want to block the user with it during registration.
Payment step message from bot
Summing up:
- You need terms and conditions with the refund policy
- Users should accept your terms and conditions before payment
- You need to provide customer support for your users, every user should easily find support link.
📝 Registration and integration
I’m using Paymentwall for my bot game, so next words will be about integration with this payment provider.
First of all, you need to connect your bot to the payment provider you select. For that you need to go to the BotFather, select your bot, click Payments, select Paymentwall from the list and click Connect Paymentwall Test (you will be able to Connect Paymentwall Live after test integration)
After the click, you will be redirected to the provider’s authorization bot. Here you just click Start, like in regular Telegram Bot, and then you will see next message:
Paymentwall authorization bot
The link from button leads to Paymentwall OAuth step, where you will be asked for approval to authorize your account if you have one.
Paymentwall oAuth step
But probably you don’t, so after redirect you will see account registration form. Proceed with it and then you will be redirected to that step. After authorization, you should be redirected back to the Paymentwall Bot where you will get a message that your account was successfully authorized in the system.
Authorization complete
BotFather will show you test token for Bot Payments API, you will use it for sending invoice messages. Telegram has an article and API docs about how to implement invoice messages logic in your bot.
During test integration, you will need to make test payments. You can use test credit cards and codes from Paymentwall sandbox to emulate different responses.
In your Paymentwall dashboard you will see My Projects section where all your projects are listed. After registration there will be two tests projects, one for bot payments, it’s name will start from numbers and contain Test label. The second project is created by default, you will be able to use it for displaying payment widget in the browser. You can read more about payment widget integration in API docs.
Note, that payment web widget provides several payment options, which depend on user country and your project settings, while Bot Payment API supports credit cards only.
Now you can start to fill in business profile and upload required documents (Go to Account -> Business Profile). Documents list is based on your country of registration and business type (individual or company) and you will see it on the last step of the business profile form. If you will have any issues, feel free to contact the support team, they should consult you during merchant validation process.
Summing up:
- Authorize through BotFather and connect Test project.
- Implement send invoice mechanism in your bot.
- Complete your business profile and upload required documents.
Docs:
🚀 Going live
Once your merchant account will be approved and test integration will be done, you can go to the @BotFather and Connect Paymentwall Live. You will go through the same process as connecting test. New project with label Live in the name, will be created in your projects list. BotFather will show you a live token for bot payments.
Now you can submit your live projects for review by Paymentwall integration team. On this step, they will verify how legal is your product and whether it satisfies all requirements. They will be checking your user policies, so you should prepare this documents before this step.
They will also check how technical integration was made and does your application correctly handles service pingbacks from Paymentwall.
And once project review process is done, you are ready to start accepting payments from mobile, web and desktop Telegram users 🎉
Your telegram mobile and Paymentwall Web widget (on the yellow background)
P.S.
If you want to see a live demo, check my bot game by this link. You will need to register your character and the go to the 🏘 Town — 🏦 Bank — 💎 Buy diamonds to be able to check payments flow.
Thank you for reading! Cheers! 🍻