Como conectar um provedor de pagamento

O Telegram possui um sistema de pagamento integrado. Para aceitar pagamentos dentro do Telegram, você precisa:

  1. Conectar um provedor de pagamento ao seu bot através do BotFather.
  2. Abrir as configurações do seu bot no BotFather e selecionar Payments.

Siga as instruções para conectar um dos provedores de pagamento disponíveis e copie o token do provedor gerado.

Como enviar uma fatura

Para enviar uma fatura no Telegram, use a seguinte função:

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
)
Parâmetro Descrição
provider_token Obrigatório. Token do provedor recebido do BotFather após conectar seu provedor de pagamento.
platform_id Obrigatório. Identificador do destinatário (ID do usuário, grupo ou canal).
title Obrigatório. Título do produto (1–32 caracteres).
description Obrigatório. Descrição do produto (1–255 caracteres).
currency Obrigatório. Moeda de pagamento (por exemplo: EUR, USD, UAH). Veja a lista de moedas suportadas: https://core.telegram.org/bots/payments#supported-currencies
prices Array descrevendo os itens da fatura. Cada item contém um título e um valor. Os valores podem ser números inteiros ou decimais.

Exemplo:
[["Produto", 2000], ["IVA", 20.75], ["Embalagem", 100]]
photo_url URL da imagem do produto.
payload Payload personalizado retornado no callback de pagamento. Padrão: tg_payment.
protect_content 1 — proteger conteúdo contra cópia e capturas de tela.
0 — sem proteção.
disable_notification 1 — enviar silenciosamente.
0 — enviar com notificação.
need_name 1 — solicitar o nome completo do cliente.
0 — não solicitar.
need_phone_number 1 — solicitar o número de telefone do cliente.
0 — não solicitar.
need_email 1 — solicitar o endereço de e-mail do cliente.
0 — não solicitar.
reply_to_message_id ID da mensagem para responder. Use '' para enviar a fatura como uma mensagem separada.
reply_markup Configuração do teclado. O primeiro botão deve ter o tipo pay.
message_thread_id ID do tópico para supergrupos com fórum ativado.
provider_data Objeto JSON com dados de pagamento específicos do provedor. Consulte a documentação do seu provedor de pagamento para os campos obrigatórios.

Importante

Os parâmetros devem ser passados na ordem exata mostrada acima.

Se você precisar pular parâmetros opcionais, deixe-os vazios ou passe os valores padrão descritos na documentação.

Exemplo

Se algum dos seguintes parâmetros estiver ativado:

  • need_name
  • need_phone_number
  • need_email

O Telegram solicitará ao cliente as informações solicitadas antes do pagamento.

Após um pagamento bem-sucedido, as informações coletadas são automaticamente salvas nas variáveis de cliente correspondentes.

Exemplo:

Callback de pagamento

Após um pagamento bem-sucedido, o Telegram envia o seguinte callback para o bot:

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

Onde:

  1. tg_payment — o valor do payload especificado ao criar a fatura.
  2. 1372995196 — o ID do chat onde a fatura foi originalmente enviada.
  3. 120.75 — o valor do pagamento.
  4. USD — a moeda do pagamento.
  5. 2ff747b9-000f-5000-b000-16d7e3517aa9 — o ID do pagamento retornado pelo provedor de pagamento.

Se as informações do cliente foram solicitadas, as seguintes variáveis de cliente também serão preenchidas automaticamente:

  • tg_payment_name
  • tg_payment_phone
  • tg_payment_email

O callback de pagamento é enviado para o chat privado do usuário com o bot.

O usuário deve ter iniciado uma conversa com o bot antes de fazer o pagamento. Caso contrário, o Telegram não pode entregar a mensagem de callback.

Após receber o webhook de pagamento, o MaviBot confirma automaticamente o pagamento usando o método answerPreCheckoutQuery.

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

Fixar uma mensagem de fatura

Após conectar um provedor de pagamento, você pode fixar a mensagem da fatura.

Use a função:

tg_pin_chat_message(platform_id, message_id, disable_notification)
Parâmetro Descrição
platform_id ID do chat do Telegram.
message_id ID da mensagem a ser fixada.
disable_notification Controla se o Telegram envia uma notificação sobre a mensagem fixada.

1 — sem notificação.
0 — enviar notificação.

As notificações são sempre desativadas em chats privados e canais.

Exemplo

Passo 1

prices = [["Curso", 100], ["IVA", 20.75]]

result = tg_send_invoice(
    '381764678:TEST:129736',
    platform_id,
    'Curso',
    'Criar cursos é fácil',
    'USD',
    prices,
    'https://salebot.pro/promo.png',
    'course_pay',
    '0',
    '0',
    '1',
    '1',
    '1',
    '',
    '{"inline_keyboard":[[{"text":"Pagar","pay":"True"}]]}'
)

Passo 2

Extraia o message_id da resposta:

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

Em seguida, fixe a mensagem:

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

Exemplo: parâmetros mínimos obrigatórios

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

result = tg_send_invoice(
    '381764678:TEST:129736',
    platform_id,
    'Curso',
    'Criar cursos é super fácil',
    'USD',
    prices
)

Exemplo: fatura com teclado inline

prices = [["Curso", 100], ["IVA", 20.75]]

tg_send_invoice(
    '381764678:TEST:129736',
    platform_id,
    'Curso',
    'Criar cursos é fácil',
    'USD',
    prices,
    'https://mavibot.ai/promo.png',
    'course_pay',
    '0',
    '0',
    '1',
    '1',
    '1',
    '',
    '{"inline_keyboard":[[{"text":"Pagar","pay":"True"}],[{"text":"Outro botão","callback_data":"Outro botão"}]]}'
)