Payments by using Telegram bot

Overview

ecommpay payment platform supports payments processing with a Telegram bot. Telegram bot is a piece of software that enables interaction with customers through Telegram service and, for this purpose, exposes two interfaces:

• special Telegram account which is an interface to interact with customers
• specialised API which is an interface for merchant

Telegram allows you to perform one-time one-step purchases through the ecommpay payment platform with an option to save cards details to use in more purchases with Telegram bots. This payment type is convenient when you communicate with the customer by using Telegram.

Such payments are processed by using Payment Page which is displayed to the customer right in the Telegram mobile application (and Telegram for tablets). Payment processing may require auxiliary procedures, such as 3‑D Secure authentication, submission of additional payment information, or currency conversion. These auxiliary procedures are fully performed by Payment Page and do not require any additional actions on the merchant's web service side.

Since payments are processed through Payment Page, merchant is not required to have a PCI DSS compliance certificate, however, if merchant is not PCI DSS compliant, they are required to complete Self-Assessment Questionnaire.

Capabilities

Payment processing with Telegram bot is performed by using the ecommpay payment form which provides the following features:

• Support for multiple languages (see more)
• Custom payment form design (see more)
• Collection of additional customer data (see more)
• Submission of additional payment information (see more)
• Support for 3‑D Secure 2 authentication (see more)
• Support of retry payment feature to enable for additional attempts to perform payments (see more)
• Provision of payment information to customer. All payment form pages include an information button; at any time, you can click this button to get some information about the payment including: payment ID, amount, date, and description.
• Sending messages to customers (more).

Some capabilities may require you to include additional parameters in payment requests, for example when collecting of additional customer data or sending messages to customers. See below in this section for more information about these parameters.

When using Telegram bot, you can also use additional pre-checkout capabilities supported by Telegram, such as providing the customer with an option to select one of the shipping methods with adding shipping fee to the amount of payment or showing a reason for failure to complete the order (for instance, absence of goods in merchant warehouse). For more information about these capabilities see the Bot Payments API section of the Telegram documentation.

Restrictions

When processing payments with Telegram, you need to consider the following limitations:

• The customer must use Telegram 4.0 and higher (more).
• The currency of purchase can be EUR, USD, or GBP. Any other currency will be converted by the payment platform (for more details, see Currency conversion)
• Payment amount may be limited by Telegram (more) and the payment environment (for more details, contact your ecommpay account manager).
• The country of the merchant may be only one of the following: Austria, Belgium, Bulgaria, Croatia, Cyprus, Czech Republic, Denmark, Estonia, Finland, France, Germany, Gibraltar, Italy, Latvia, Liechtenstein, Luxembourg, Malta, the Netherlands, Norway, Poland, Romania, Portugal, Slovakia, Slovenia, Spain, Sweden, Switzerland, the United Kingdom.
• A message with a pay button can only be sent to a private chat with the user. Groups and channels are not supported.

Apart from the named restrictions, in particular cases additional limitations may be enforced. For more information, contact your ecommpay Key Account Manager.

Integration and usage

In order to perform payment processing with Telegram, you need to do the following:

1. Address the following organisational interaction issues with ecommpay:

   1. If your company has not yet obtained any ID from ecommpay, you need to submit an application for connecting to the ecommpay payment platform (https://ecommpay.com/apply-now/).
   2. If your company has already obtained a project ID from ecommpay, start preparation activities (see more).
2. Create a bot (or reuse an existing one), code the bot to use Telegram Bot API and configure the bot to accept payments with Telegram Bot Payments API (or MTProto API).
3. Connect ecommpay test bot ecommpay (@ECOMMPAY_testbot).
4. Test and put payment processing with Telegram bot into operation. For testing, you should use ecommpay Test Bot and test card details provided in Test cards.
5. Put the merchant bot into operation, by connecting to the ecommpay Live Bot (@ECOMMPAY_livebot).

The following sections contain detailed information about configuring merchant bot and connecting test and operating ecommpay bots to merchant bot. If you have any questions, contact ecommpay technical support (support@ecommpay.com).

The ecommpay supports payments with Telegram bot both with and without saved payment data. The initial purchase is performed without saved payment data.

Payments without saved data are performed in two stages: first, customer payment card token is created, and then it is used to perform payment.

Purchase without saved data

1. The customer opens the merchant bot, and a message with a description of the goods or service, amount to be paid and other information is displayed to the customer. The information displayed to the customer depends on the configurations of the merchant bot.
   
   
2. The customer confirms the purchase, and Payment Page with fields for specifying payment card details, except for verification code (such as CVV), is displayed to the customer.
   
   
3. The customer specifies payment card details, the customer is redirected to the Telegram service, and a message from Telegram is displayed to the customer.
   
   
4. The customer agrees to proceed with payment.
   
   
5. The payment form Payment Page in the Purchase mode is displayed to the customer where customer enters CVV code and confirms payment.
   
   
6. Preloader page is displayed to the customer and 3‑D Secure authentication page and (or) page for submitting additional information, if it is required.
   
   
7. The customer is redirected to the merchant bot to view the payment processing result information. The customer also has an option to view the receipt.
   
   

Purchase with using saved data

1. The customer opens the merchant bot and sees a message with a description of the goods or service, amount to be paid and other information. The information that is displayed to the customer depends on the configurations of the merchant bot.
   
   
2. The customer selects payment method.
   
   
3. A request for message payment confirmation from the Telegram service is displayed to the customer and the customer agrees to proceed with the purchase.
   
   
4. The payment form Payment Page in the Purchase mode is displayed to the customer where customer enters CVV code and confirms payment.
   
   
5. Preloader page is displayed to the customer and 3‑D Secure authentication page and (or) page for submitting additional information, if it is required.
6. The customer is redirected to the merchant bot to view the payment processing result information. The customer also has an option to view the receipt.
   
   

Creating merchant bot

To create a Telegram bot, you complete the following steps:

1. In the Telegram interface find the BotFather bot (@botfather) and open the chat with it.
2. In the chat window, type run the /newbot command and follow the bot instructions.

By following these steps, you will create an authorisation token which is required to receive and send messages using the Telegram API. This token is critical piece of authentication data which must be prevented from compromising.

Connecting to ecommpay Test Bot

To connect the ecommpay Test Bot (@ECOMMPAY_testbot) to the merchant bot, complete the following steps:

1. In Telegram, find the BotFather bot (@botfather) and open a chat with it.
2. Inside the chat, run the /mybots command and select the bot you need from the list.
3. In the bot configuration menu, click Payments, select ecommpay, and then click Connect ECOMMPAY Test.
4. In the chat that opens, click Start, and then click Request ECOMMPAY TEST ENVIROMENT button.
5. If you have not previously connected to ecommpay bots, follow the link, complete and submit the application.
6. Accept ecommpay confirmation of readiness to process test payments involving the use of Telegram bot.

By following these steps, you will create an payment token which is required to processing test payments with merchant bot. This token is critical piece of authentication data which must be prevented from compromising.

Connecting to ecommpay Live Bot

To connect the ecommpay Live Bot to the merchant bot (@ECOMMPAY_livebot), you need to perform the following steps:

1. In the Telegram interface find the BotFather bot (@botfather) and open a chat with this bot.
2. In the new opened chat type the /mybots command and select the required bot from the list.
3. In the configuration menu of the selected bot click the Payments button and select ecommpay from the list, and then click Connect ECOMMPAY Live.
4. In the chat that opens, click the Start button and click the Connect to ECOMMPAY Live Bot button.
5. If you have not previously connected ecommpay bots, follow the link, complete and submit the application for conecting to the bot.
6. Acknowledge readiness to process production payments by using the Telegram bot from ecommpay.

By following these steps, you will create an payment token required for processing test payments with merchant bot. This token is a critical piece of authentication data which must be prevented from compromising.

Unlike any other payment methods, payments with Telegram bot do not use digital signatures. Instead, authentication is performed by using authorisation and payment tokens; authorisation is required token to send and receive messages through the Telegram API while payment token is required to perform payments—either in test or production mode. Authorisation token is generated when creating merchant bot, and payment token is generated when integrating the bot with ecommpay

To perform purchase, do the following on merchant side:

• Send purchase request to the Telegram service and accept the reply with receipt acknowledgement.
• Confirm purchase and accept the reply with success confirmation.
• Accept purchase processing result from the Telegram service.

Any interaction with the Telegram service must follow the Telegram Bot Payments API (or MTProto API) specification.

Purchase processing may require you to perform additional procedures like 3‑D Secure authentication, providing follow-up information about the payment, or currency exchange. All these procedures are performed by Payment Page, no additional actions are required from merchant's web service.

The following diagram provides the detailed picture of an ordinary one-step purchase processing procedure without additional procedures.

In terms of payment processing with the Telegram bot, payment form is opened by using a message sent to the customer with information about the payment and a button redirecting the customer to payment procedure. In order for this message to be created and sent, you need to configure merchant web service to sends HTTPS request sendInvoice by using GET or POST methods as specified in Telegram Bot Payments API or messages.sendMedia request compliant with MTProto API.

Besides mandatory parameters, in the provider_data object, you can specify parameters with information about the payment, the customer, or parameters that modify the payment form displayed to the customer:

• Parameters with additional customer data:
  • customer_birthplace—location where customer was born
  • customer_day_of_birth—customer day of birth in the DD-MM-YYYY format
  • customer_email—customer email
  • customer_first_name—first name of the customer
  • customer_last_name—last name of the customer
  • customer_middle_name—customer middle name
  • customer_phone—customer phone number (4 to 24 digits);
  • customer_ssn—the last 4 digits of US social security number
  • identify_doc_number—identity verification document
• Parameters with customer address data:
  • customer_address—address of the customer
  • customer_city—city of the customer address
  • customer_country—country of the customer address in ISO 3166-1 alpha-2 format
  • customer_state—state of the customer address
  • customer_street—street of the customer address
  • customer_zip—ZIP code of the customer address
• Parameters with customer billing address information:
  • billing_address—street of the customer billing address
  • billing_city—city of the customer billing address
  • billing_country —country of the customer billing address in the ISO 3166-1 alpha-2 format
  • billing_postal—postcode of the customer billing address
  • billing_region—state, province, or region of customer billing address
  • billing_region_code—state, province, or region code in the ISO 3166-2 format (used with billing_country)
• Parameters with additional purchase information:
  • addendum_data—a Base64-encoded string with all relevant booking itinerary information, including but not limited to booking number and hotel guests names
  • best_before—date and time when the payment expires in YYYY-MM-DDThh:mm:ss±hh format
  • receipt_data—a Base64-encoded string that contains information required to send notification to a customer
  • descriptor—information which identifies the merchant that performs the operation
• Parameters that affect rendering of payment form:
  • language_code—language in which payment page will be opened to customer
  • region_code—customer country in ISO 3166 alpha-2 format
• Parameter that may promote selection of frictionless flow when authenticating user (more information):
  • customer_account_info—a Base64-encoded string with information about the customer account and contact data with web service
  • customer_shipping—a Base64-encoded string that contains order shipping information
  • payment_merchant_risk—a Base64-encoded string that contains purchase details information and preferred authentication flow

The following is an example of parameters that can be included in the message to perform a payment in accordance with the Telegram Bot API.

{
    "chat_id": 0007, // ID of target chat
    "title": "How to communicate with aliens", // Name of a purchased item or service
    "description": "A book", // Purchase description
    "payload": "telegram_payment_1204", // Payment ID
    "provider_token": "12343124:LIVE:42345", // Payment token created 
                                             //  after connecting ecommpay bot 
    "start_parameter": "...",
    "currency": "EUR", // Currency code in the ISO-4217 alpha-3 format
    "prices": [{
        "label": "...",
        "amount": 5990
    }],
    // Object with parameters for opening the payment form
    "provider_data": {
        "language_code": "EN", // Language code in the ISO 639-1 alpha-2 format 
                               //  for displaying the payment form in this language
        "customer_email": "janedoe@example.com" // Customer email
    }
}

For more information about the parameters you can include in the provider_data object, see Parameters for opening payment form.

Processing payments with the Telegram bot usually requires a bare minimum of data. However, in order to gather more data about customers, you can send and/or request additional data, such as customer phone number or email. If you need to add in payment form additional fields to collect additional data, contact ecommpay technical support.

To send additional customer data, you need to define a list of additional parameters and specify their values in the provider_data object. In this case, the data is displayed in the corresponding fields of the payment form, provided this functionality is enabled and configured by technical support specialists.

To request additional customer data,, you need to define a list of additional parameters in the provider_data object, but not specify any values for the parameters. In this case, the corresponding empty fields available for data entry by customer will be displayed on the payment form, provided this functionality is enabled and configured by technical support specialists..

For more information, see Collecting customer data.