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 por minuto: 60.

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. Use em vez de fiat
fiat	string	modo fiat	a moeda fiduciária em que o preço é expresso (as linhas is_fiat do getCurrencies). Ignorado no modo cripto — para definir o preço em moeda fiduciária, defina currency_type: "fiat"
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, com até 512 caracteres — obrigatória quando paid_btn_name é definido e ignorada sem ele
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 = prazo padrão, hoje também de 31 dias. Confira expiration_date no resultado
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)

A descrição, o conteúdo após o pagamento e o botão podem ficar ocultos para quem paga enquanto o conteúdo estiver em análise ou não tiver sido aprovado. O valor da fatura continua podendo ser pago.

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 (sempre em unidades menores de cripto: numa fatura em cripto, o valor de face; numa fatura fiat, null até o pagamento e depois as unidades menores de paid_asset; numa fatura de valor livre, null até o pagamento) e, nas faturas fiat pagas, paid_asset / paid_amount / paid_fiat_rate — a cripto realmente cobrada e a cotação usada. Numa fatura fiat, asset continua null mesmo depois do pagamento.
• Taxa: fee_asset / fee_amount, registrados 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, definido quando o reembolso fica completo.
• Trava de cotação (extensão): rate_lock_until e rate_lock_rates — as cotações registradas por ativo, null quando nenhuma trava foi pedida.
• Datas e dados do pagamento: created_at, paid_at, paid_usd_rate (a cotação em USD registrada no pagamento).
• Como foi criada: currency_type, accepted_assets, open_amount, is_anonymous, 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 (no modo cripto falta asset; no modo fiat falta fiat, asset foi enviado junto ou open_amount foi definido), 400 invalid_amount (inclusive um valor que vira zero na precisão do ativo), 400 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 atualizada para um ativo aceito — tente de novo). 400 invalid_request indica parâmetros malformados: um currency_type ou paid_btn_name desconhecido, um texto acima do limite de tamanho, um expires_in fora de 0–2678400, um valor enviado como número JSON.

Como as faturas são pagas

Quem paga paga com o saldo da carteira no Mini App — na hora, sem taxa de rede, desde que haja saldo suficiente e o pagamento seja confirmado. Também dá para pagar com fundos de uma carteira externa: quando essa opção está disponível, o app mostra um endereço de depósito e um prazo. O depósito é creditado na carteira de quem paga. O pagamento automático exige um depósito naquele endereço, saldo disponível suficiente, nenhuma restrição de pagamentos de saída e que o pedido de pagamento e a fatura não tenham expirado. Um depósito atrasado fica na carteira de quem pagou e não comprova o pagamento da fatura. Em ambos os casos, você recebe uma fatura paid e um evento invoice_paid se houver uma URL de webhook configurada, sem parâmetros ou campos adicionais.

Em uma fatura fiat, o valor em cripto é calculado na hora do pagamento, arredondado para cima até a menor unidade do ativo escolhido. A taxa de comerciante é descontada desse valor em cripto. Se não houver cotação fixada ainda válida nem cotação atual, o pagamento falha para quem paga, em vez de ser liquidado por uma cotação desatualizada.

Travando a cotação em uma fatura fiat

Passe rate_lock_seconds para fixar, na criação, a cotação atual de todos os ativos aceitos. Enquanto ela vale, o pagador vê os valores fixados e paga por essa cotação — você assume o risco durante esse período. O parâmetro aceita de 0 a 86400 segundos: 0 significa sem fixação. Os demais valores são ajustados ao intervalo permitido — no mínimo 60 segundos e no máximo o limite da plataforma. Valores fora de 0–86400 são rejeitados com 400 invalid_request. Confira rate_lock_until no resultado para saber o prazo efetivo.

Quando a cotação fixada expira, uma fatura ainda válida pode ser paga pela cotação do momento. Para fazer os dois prazos coincidirem, use expires_in dentro do intervalo permitido para a cotação fixada e compare expiration_date com rate_lock_until na resposta.

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 (padrão 100, máx. 1000). Devolve {"items": [invoice, …]}, das mais novas para as mais antigas.

deleteInvoice

POST /pay/api/deleteInvoice — escopo invoices. Um parâmetro: invoice_id. Exclui uma fatura não paga — ativa ou expirada — e devolve true. A fatura é apagada, não apenas marcada: some do getInvoices, o pay_url dela para de funcionar e nenhum webhook é enviado. Se precisar desse registro, registre a exclusão no seu sistema. Erros: 404 invoice_not_found, 409 invoice_already_paid — uma fatura paga não pode ser excluída porque o dinheiro já foi movimentado.

refundInvoice

POST /pay/api/refundInvoice — escopo refunds, limite por minuto: 30. Uma extensão sobre o Crypto Bot: devolve toda ou parte da cripto efetivamente paga, do saldo do seu app para o pagador, inclusive se ele pagou anonimamente, sem revelar sua identidade. Em faturas fiat, use paid_asset e paid_amount; o reembolso não faz uma nova conversão de moeda fiduciária.

Parâmetro	Tipo	Obrigatório	O que significa
invoice_id	integer	sim	a fatura paga
amount	string	não	o valor em cripto a reembolsar, no ativo originalmente pago (paid_asset em faturas fiat). Omitido = todo o restante não reembolsado. Os reembolsos parciais se acumulam até o valor em cripto originalmente pago
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. Seu app precisa ter saldo suficiente no ativo original do pagamento, mesmo se swap_to converteu o recebimento em outro ativo. 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, 400 invalid_request (invoice_id ausente ou spend_id com mais de 64 caracteres), 403 verification_required (as operações de saída do dono estão restritas), 503 merchant_payouts_paused e o par do spend_id, 409 idempotency_conflict / 409 idempotency_in_progress.