Referência da API: faturas e reembolsos

Os métodos de fatura: createInvoice, getInvoices, deleteInvoice, refundInvoice. As convenções (autenticação, envelope, valores, spend_id) estão na página da referência da API para comerciantes; o passo a passo guiado está em aceitando pagamentos com faturas.

createInvoice

POST /pay/api/createInvoice — escopo invoices, limite de 60 por minuto.

Parâmetro	Tipo	Obrigatório	O que significa
currency_type	string	não	crypto (padrão) ou fiat
asset	string	modo cripto	o ativo a cobrar, por exemplo USDT. Não pode ir junto com fiat
fiat	string	modo fiat	a moeda fiduciária em que o preço está (as linhas is_fiat do getCurrencies)
accepted_assets	string / array	não	só no modo fiat: os ativos com que quem paga pode pagar — uma string separada por vírgulas ("USDT,GRAM") ou um array JSON. Omitido = todos os ativos suportados
amount	string	sim, a menos que open_amount esteja definido	string decimal positiva: unidades do ativo no modo cripto, unidades fiduciárias (máx. 2 casas decimais) no modo fiat
open_amount	boolean	não	extensão, só no modo cripto: sem valor fixo — quem paga informa um na hora do pagamento (doações e gorjetas). Excludente com amount
description	string	não	até 1024 caracteres, mostrada a quem paga
hidden_message	string	não	até 2048 caracteres, revelada a quem paga só depois do pagamento
payload	string	não	até 4096 caracteres de dados seus, devolvidos na fatura e no webhook
allow_comments	boolean	não	deixa quem paga anexar um comentário (padrão true)
allow_anonymous	boolean	não	deixa quem paga esconder a identidade (padrão true)
paid_btn_name	string	não	botão pós-pagamento: viewItem, openChannel, openBot ou callback
paid_btn_url	string	não	a URL http(s) do botão — obrigatória quando paid_btn_name é definido
swap_to	string	não	converte automaticamente os pagamentos recebidos neste ativo. Melhor esforço: se a troca não puder ser feita na hora do pagamento, o pagamento continua valendo sem a troca
expires_in	integer	não	segundos até a fatura expirar, até 2678400 (31 dias); omitido ou 0 = nunca
rate_lock_seconds	integer	não	extensão, só no modo fiat: congela as cotações de conversão na criação por esta janela (veja abaixo)

O resultado — e o payload do webhook invoice_paid — é o objeto de fatura. Os campos principais dele:

• Identidade e estado: invoice_id, hash (o id público dentro de pay_url), status (active / paid / expired), pay_url — o link t.me que você manda para quem paga (bot_invoice_url, mini_app_invoice_url, web_app_invoice_url são aliases dele).
• Valores: amount (o valor de face — unidades fiduciárias em uma fatura fiat, cripto no resto; null enquanto uma fatura de valor livre não é paga), amount_minor e, nas faturas fiat pagas, paid_asset / paid_amount / paid_fiat_rate — a cripto realmente cobrada e a cotação usada.
• Taxa: fee_asset / fee_amount, carimbados no pagamento — o número que vale para a sua contabilidade (fee e usd_rate são aliases obsoletos do Crypto Bot). Veja taxas e limites.
• Quem pagou: paid_by_user_id (null quando a pessoa escolheu o anonimato), paid_anonymously, comment.
• Reembolsos (extensão): refunded_amount / refunded_minor (acumulados) e refunded_at, carimbado quando o reembolso fica completo.
• Trava de cotação (extensão): rate_lock_until e rate_lock_rates — as cotações carimbadas por ativo, null quando nenhuma trava foi pedida.
• Como foi criada: description, hidden_message, payload, paid_btn_name / paid_btn_url, expiration_date (expires_at é um alias), os campos de troca (swap_to, is_swapped, swapped_to, swapped_rate, swapped_output, …).

Erros: 400 invalid_currency (asset e fiat trocados), 400 invalid_amount, 404 unknown_asset, 400 unsupported_fiat, 400 paid_btn_url_required e, para pedidos de trava de cotação, 400 rate_lock_fiat_only, 409 ratelock_disabled, 409 rate_unavailable (sem cotação fresca para um ativo aceito — tente de novo).

Como as faturas são pagas

Quem paga paga com o saldo da carteira no Mini App — na hora, sem taxa de rede. Também dá para bancar a fatura de uma carteira externa: o app mostra um endereço de depósito, a transferência cai na carteira da própria pessoa e a fatura é liquidada automaticamente quando o valor chega. De um jeito ou de outro você vê a mesma coisa: uma fatura paid normal e um webhook invoice_paid — não tem parâmetro nem campo extra para tratar.

Em uma fatura fiat, o valor em cripto é calculado na hora do pagamento, arredondado a seu favor, então você nunca recebe menos que o valor de face em moeda fiduciária. Se não houver cotação fresca, o pagamento falha do lado de quem paga, em vez de ser liquidado por uma cotação velha.

Travando a cotação em uma fatura fiat

Passe rate_lock_seconds para carimbar a cotação atual de todos os ativos aceitos na criação. Enquanto a trava vale, quem paga vê exatamente os valores carimbados, e o pagamento converte pela cotação carimbada — você assume o risco de cotação durante a janela. O servidor limita a janela entre 60 segundos e o máximo da plataforma (hoje, 15 minutos).

Quando a trava acaba, a fatura continua pagável e volta em silêncio para a conversão na hora do pagamento. Se você quer que a fatura morra junto com a cotação, defina expires_in com o mesmo valor.

getInvoices

GET /pay/api/getInvoices — escopo read. Filtros: asset, fiat, invoice_ids (separados por vírgula), status (active / paid / expired — expired é uma extensão; active exclui as faturas que já passaram do prazo), além de offset / count. Devolve {"items": [invoice, …]}, dos mais novos para os mais antigos.

deleteInvoice

POST /pay/api/deleteInvoice — escopo invoices. Um parâmetro: invoice_id. Cancela uma fatura não paga e devolve true. Erros: 404 invoice_not_found, 409 invoice_already_paid — uma fatura paga não pode ser excluída, o dinheiro já se moveu.

refundInvoice

POST /pay/api/refundInvoice — escopo refunds, limite de 30 por minuto. Uma extensão sobre o Crypto Bot: devolve o valor de face de uma fatura paga — ou parte dele — do saldo do seu app para quem pagou, inclusive quem pagou anonimamente, sem revelar quem foi.

Parâmetro	Tipo	Obrigatório	O que significa
invoice_id	integer	sim	a fatura paga
amount	string	não	o valor a reembolsar, no ativo da fatura. Omitido = todo o restante não reembolsado. Os reembolsos parciais se acumulam até o valor de face
spend_id	string	não	chave de idempotência — use uma, para que uma nova tentativa depois de um timeout repita a resposta em vez de reembolsar duas vezes

O resultado é o objeto de fatura atualizado, com o refunded_amount / refunded_minor acumulados; o refunded_at é carimbado quando a fatura fica totalmente reembolsada. O status continua paid. A taxa da plataforma não é devolvida. Cada reembolso dispara o webhook opcional refund_completed.

Erros: 404 invoice_not_found, 409 invoice_not_paid, 409 already_refunded (não sobrou nada a reembolsar), 409 amount_too_big (mais que o restante não reembolsado), 409 insufficient_funds, 400 invalid_amount e o par do spend_id, 409 idempotency_conflict / 409 idempotency_in_progress.