Aceitando pagamentos com faturas

Uma fatura é como você cobra um usuário do Telegram. Você cria uma pela API, manda o link para quem vai pagar, e o saldo do seu app é creditado no instante em que a pessoa confirma.

O fluxo

1. Crie a fatura com createInvoice, informando um ativo e um valor (ou um preço em moeda fiduciária — veja abaixo).
2. Mande o link da resposta para quem vai pagar. Abrir o link leva a pessoa para a tela de pagamento do app.
3. A pessoa confirma e paga com o saldo dela — na hora, sem taxa de rede. Quem não tem saldo suficiente pode bancar a fatura de uma carteira externa; ela é liquidada automaticamente quando a transferência chega, e para você parece igual.
4. Você é avisado. O webhook invoice_paid dispara e o valor cai no saldo do seu app.
5. Entregue o pedido. Não espere mais nada; o pagamento é definitivo a partir dali.

Se você preferir consultar em vez de receber webhook, o getInvoices devolve suas faturas com o status atual. O webhook é o caminho mais rápido — a consulta é o plano B.

Preço em moeda fiduciária

Uma fatura pode ser precificada em cripto ou em uma moeda fiduciária, com uma lista de ativos aceitos. Quem paga então liquida no ativo aceito que tiver, convertido pela cotação do momento do pagamento. Essa é a escolha comum para uma loja cujo catálogo é em uma moeda do mundo real.

Se você preferir cotar um preço firme, o rate_lock_seconds congela as cotações de conversão na criação por uma janela limitada — quem paga vê exatamente os valores travados, e você assume o risco de cotação por esses minutos. Detalhes na referência de faturas.

Você também pode definir swap_to para os pagamentos recebidos serem convertidos em um único ativo conforme chegam — útil para manter seu saldo em uma stablecoin sem fazer as trocas por conta própria.

Opções úteis da fatura

• description — mostrada a quem paga na tela de pagamento.
• hidden_message — revelada a quem paga só depois do pagamento. É assim que você entrega um código, uma chave ou um link sem precisar de outro canal de entrega.
• payload — sua própria string opaca, devolvida no webhook. Coloque aqui o ID do seu pedido.
• expires_in — um prazo, depois do qual a fatura não pode mais ser paga.
• paid_btn_name / paid_btn_url — o botão que quem paga vê depois do pagamento, para voltar ao seu bot, canal ou página do item.
• open_amount — sem valor fixo; quem paga informa um na hora do pagamento. O formato natural para doações e gorjetas.

Uma fatura não paga pode ser cancelada com deleteInvoice.

Reembolsos

O refundInvoice devolve o valor de face de uma fatura paga — ou qualquer parte dele — do saldo do seu app para quem pagou, inclusive para quem pagou anonimamente, sem revelar quem foi. Os reembolsos parciais se acumulam até o valor de face; a fatura acompanha isso em refunded_amount. Passe um spend_id para que uma nova tentativa depois de um timeout repita a resposta em vez de reembolsar duas vezes. A taxa da plataforma não é devolvida.

⚠️ Verifique a assinatura do webhook antes de entregar

Qualquer um pode fazer POST na sua URL de webhook. Confira o cabeçalho TgPayCrypto-API-Signature — HMAC-SHA256 sobre o corpo bruto da requisição, com chave igual ao SHA-256 do seu token de API — antes de tratar um pagamento como real, e deduplique pelo update_id, para que uma nova tentativa não envie o pedido duas vezes.