Comment connecter un fournisseur de paiement

Telegram dispose d'un système de paiement intégré. Pour accepter des paiements dans Telegram, vous devez :

  1. Connecter un fournisseur de paiement à votre bot via BotFather.
  2. Ouvrir les paramètres de votre bot dans BotFather et sélectionner Paiements.

Suivez les instructions pour connecter l'un des fournisseurs de paiement disponibles, puis copiez le jeton de fournisseur généré.

Comment envoyer une facture

Pour envoyer une facture dans Telegram, utilisez la fonction suivante :

tg_send_invoice(
    provider_token,
    platform_id,
    title,
    description,
    currency,
    prices,
    photo_url,
    payload,
    protect_content,
    disable_notification,
    need_name,
    need_phone_number,
    need_email,
    reply_to_message_id,
    reply_markup,
    message_thread_id,
    provider_data
)
Paramètre Description
provider_token Obligatoire. Jeton de fournisseur reçu de BotFather après avoir connecté votre fournisseur de paiement.
platform_id Obligatoire. Identifiant du destinataire (ID d'utilisateur, de groupe ou de canal).
title Obligatoire. Titre du produit (1 à 32 caractères).
description Obligatoire. Description du produit (1 à 255 caractères).
currency Obligatoire. Devise de paiement (par exemple : EUR, USD, UAH). Voir la liste des devises prises en charge : https://core.telegram.org/bots/payments#supported-currencies
prices Tableau décrivant les articles de la facture. Chaque article contient un titre et un montant. Les montants peuvent être des entiers ou des nombres décimaux.

Exemple :
[["Product", 2000], ["VAT", 20.75], ["Packaging", 100]]
photo_url URL de l'image du produit.
payload Charge utile personnalisée renvoyée dans le callback de paiement. Par défaut : tg_payment.
protect_content 1 — protéger le contenu contre la copie et les captures d'écran.
0 — aucune protection.
disable_notification 1 — envoyer silencieusement.
0 — envoyer avec notification.
need_name 1 — demander le nom complet du client.
0 — ne pas le demander.
need_phone_number 1 — demander le numéro de téléphone du client.
0 — ne pas le demander.
need_email 1 — demander l'adresse e-mail du client.
0 — ne pas la demander.
reply_to_message_id ID du message auquel répondre. Utilisez '' pour envoyer la facture comme un message séparé.
reply_markup Configuration du clavier. Le premier bouton doit être de type pay.
message_thread_id ID du sujet pour les supergroupes avec forum activé.
provider_data Objet JSON avec les données de paiement spécifiques au fournisseur. Consultez la documentation de votre fournisseur de paiement pour les champs requis.

Important

Les paramètres doivent être passés dans l'ordre exact indiqué ci-dessus.

Si vous devez ignorer des paramètres facultatifs, laissez-les vides ou passez les valeurs par défaut décrites dans la documentation.

Exemple

Si l'un des paramètres suivants est activé :

  • need_name
  • need_phone_number
  • need_email

Telegram demandera au client les informations requises avant le paiement.

Après un paiement réussi, les informations collectées sont automatiquement enregistrées dans les variables client correspondantes.

Exemple :

Callback de paiement

Après un paiement réussi, Telegram envoie le callback suivant au bot :

tg_payment 1372995196 120.75 USD 2ff747b9-000f-5000-b000-16d7e3517aa9

Où :

  1. tg_payment — la valeur de la charge utile spécifiée lors de la création de la facture.
  2. 1372995196 — l'ID du chat où la facture a été initialement envoyée.
  3. 120.75 — le montant du paiement.
  4. USD — la devise du paiement.
  5. 2ff747b9-000f-5000-b000-16d7e3517aa9 — l'ID de paiement renvoyé par le fournisseur de paiement.

Si des informations client ont été demandées, les variables client suivantes seront également renseignées automatiquement :

  • tg_payment_name
  • tg_payment_phone
  • tg_payment_email

Le callback de paiement est envoyé dans le chat privé de l'utilisateur avec le bot.

L'utilisateur doit avoir déjà démarré une conversation avec le bot avant d'effectuer le paiement. Sinon, Telegram ne peut pas délivrer le message de callback.

Après avoir reçu le webhook de paiement, MaviBot confirme automatiquement le paiement en utilisant la méthode answerPreCheckoutQuery.

https://core.telegram.org/bots/api#answerprecheckoutquery

Épingler un message de facture

Après avoir connecté un fournisseur de paiement, vous pouvez épingler le message de facture.

Utilisez la fonction :

tg_pin_chat_message(platform_id, message_id, disable_notification)
Paramètre Description
platform_id ID du chat Telegram.
message_id ID du message à épingler.
disable_notification Contrôle si Telegram envoie une notification concernant le message épinglé.

1 — aucune notification.
0 — envoyer une notification.

Les notifications sont toujours désactivées dans les chats privés et les canaux.

Exemple

Étape 1

prices = [["Course", 100], ["VAT", 20.75]]

result = tg_send_invoice(
    '381764678:TEST:129736',
    platform_id,
    'Course',
    'Creating courses is easy',
    'USD',
    prices,
    'https://salebot.pro/promo.png',
    'course_pay',
    '0',
    '0',
    '1',
    '1',
    '1',
    '',
    '{"inline_keyboard":[[{"text":"Pay","pay":"True"}]]}'
)

Étape 2

Extrayez le message_id de la réponse :

res = get(result, 'result')
m_id = get(res, 'message_id')

Ensuite, épinglez le message :

tg_pin_chat_message(#{platform_id}, #{m_id}, 1)

Exemple : paramètres minimum requis

prices = [["Super course", 100]]

result = tg_send_invoice(
    '381764678:TEST:129736',
    platform_id,
    'Course',
    'Creating courses is super easy',
    'USD',
    prices
)

Exemple : facture avec un clavier inline

prices = [["Course", 100], ["VAT", 20.75]]

tg_send_invoice(
    '381764678:TEST:129736',
    platform_id,
    'Course',
    'Creating courses is easy',
    'USD',
    prices,
    'https://mavibot.ai/promo.png',
    'course_pay',
    '0',
    '0',
    '1',
    '1',
    '1',
    '',
    '{"inline_keyboard":[[{"text":"Pay","pay":"True"}],[{"text":"Another button","callback_data":"Another button"}]]}'
)