How to accept payments using your Telegram bot

The information below is provided for bots that use Telegram API. For bots created using other services, refer to the appropriate API description.

Making a payment using your bot

To accept payments using your bot connected with the Smart Glocal bot, complete the following steps:

1. To be able to send invoices to your customers, call the sendinvoice method from your bot. Make sure you include all the mandatory parameters along with the provider_token value you got from @BotFather after connecting your bot to the Smart Glocal bot.
   If required, you can send some extra parameters within the provider_data object.

   Extra parameters

   email - email address (string)
   state - U.S. state of residence (2 characters, string)
   city - city of residence (50 characters, string)
   address line - address (200 characters, string)
   full_name - full name (string)
   postal_code - postal code (50 characters, string)
   country_iso2 - country code (ISO 3166-1 alpha-2) (2 characters, string)
   country_iso3 - country code (ISO 3166-1 alpha-3) (3 characters, string)
   ipv4 - IPv4 address (string)
   

   Request example

   {
    "chat_id": 0000000,
    "need_phone_number": true,
    "title": "*",
    "description": "*",
    "payload": "*",
    "provider_token": "0987654321:TEST",
    "currency": "USD",
    "prices": [
        {
            "label": "Amount",
            "amount": 200
        }
     ],
    "provider_data": {
        "email": "johnjohnson@example.com",
        "state": "TX",
        "city": "Dallas",
        "address_line": "Riot Ave",
        "full_name": "John Johnson",
        "postal_code": "129164",
        "country_iso2": "US",
        "country_iso3": "USA",
        "ipv4": "127.0.0.1"
    }
    }

2. In response Telegram will render a form containing all the required fields you passed in the request above.

3. After the customer completes the fields, Telegram renders a payment form.

4. After the customer clicks Pay, Telegram will send a webhook with the PreCheckoutQuery object.

5. Your bot should send answerPreCheckoutQuery in response.

6. If 3DS is required, you will receive an action_reqired webhook and Telegram will redirect the customer for 3DS.

7. Once the payment is successfully completed:

   • the customer will see the payment result on the screen
   • you will receive a payment_finished webhook from Smart Glocal (please reply with 200 OK to it)
   • Telegram will send you a payment confirmation containing the SuccessfulPayment object with the provider_payment_charge_id parameter (transaction ID) (store this ID for future references)

Recurring payments via Telegram

Telegram allows storing a customer's credit card data after their first payment and handle further (recurring) payments without involving the customer using a recurring payment token.

You can save a customer's card data if the customer checks the respective checkbox when paying:

Alternatively, you can pass the provider_data object with the "save_card": true parameter in the sendinvoice method.

To know more about recurring payments, see here.

Sequence diagram of payments made using the Telegram bot