Referência da API: transferências e cheques

Estes são os métodos de pagamento. Uma transferência envia fundos do saldo do seu app para a carteira de um usuário do Telegram ou os mantém retidos até que um novo destinatário abra o bot. Um cheque é um link de resgate cujo valor fica reservado no seu saldo desde a criação. As convenções (autenticação, envelope, valores, spend_id) estão na página da referência da API para comerciantes.

Os três métodos que tiram dinheiro do saldo obedecem ao modo de pagamentos do app: um app novo paga qualquer pessoa desde o início; se o dono restringiu o modo, só quem está na lista pode ser pago (403 recipient_not_allowed), ou ninguém (403 payouts_disabled). Quem define o modo é o dono, no Mini App; pela API não dá. Os fins permitidos para esses pagamentos estão nos termos da API para comerciantes.

transfer

POST /pay/api/transfer — escopo payouts, limite de 30 por minuto. Se o destinatário já usa o app, recebe o pagamento na hora. Um username desconhecido cria uma transferência com status pending: os fundos ficam em escrow até que o destinatário abra o bot pela primeira vez com esse nome de usuário. Os fundos não recebidos são devolvidos ao saldo do app após o prazo de 30 dias (expires_at). Confirme a devolução pelo status: "returned" antes de considerar esses fundos na sua contabilidade. Envie você mesmo o invite_url ao destinatário — o bot não consegue enviar mensagens a quem nunca o iniciou. O status final é completed ou returned. Para acompanhá-lo, ative os webhooks transfer_completed e transfer_returned ou consulte getTransfers.

Parâmetro	Tipo	Obrigatório	O que significa
user_id	integer	um dos dois: user_id / username	ID do destinatário no Telegram; ele já precisa usar o app
username	string	um dos dois: user_id / username	nome de usuário do destinatário, com ou sem @; um nome desconhecido cria um pagamento pendente
asset	string	sim	código do ativo
amount	string	sim	string decimal positiva; também limitada pelo mínimo e pelo máximo por transferência da plataforma (uma estimativa equivalente em dólares pelas cotações do momento)
spend_id	string	sim	chave de idempotência, de 1 a 64 caracteres, única por pagamento
comment	string	não	até 1024 caracteres, mostrado a quem recebe
disable_send_notification	boolean	não	true = não avisar o destinatário no Telegram em pagamentos imediatos; não suprime o aviso quando uma transferência pendente é recebida

Informe apenas um dos campos de destinatário: user_id ou username.

O resultado é o objeto de transferência: transfer_id, hash, user_id, recipient_username, asset, amount, amount_minor, spend_id, comment, status (pending / completed / returned), created_at, completed_at, expires_at, invite_url. O campo user_id pode ser null enquanto a transferência aguarda o novo destinatário; completed_at é null até a conclusão.

Erros: 403 payouts_disabled / 403 recipient_not_allowed (o modo de pagamentos), 404 user_not_found (ID desconhecido ou destinatário indisponível), 400 invalid_recipient (nome de usuário do destinatário inválido), 400 amount_too_small / 400 amount_too_big (fora dos limites por transferência), 409 insufficient_funds, 400 unknown_asset, 400 invalid_amount e o par do spend_id, 409 idempotency_conflict / 409 idempotency_in_progress.

transferBatch

POST /pay/api/transferBatch — escopo payouts, limite de 10 por minuto. Uma extensão para pagamentos em massa: até 100 transferências em uma chamada.

Um parâmetro: items — um array em que cada item é um conjunto completo de parâmetros do transfer (user_id ou username, asset, amount, spend_id, além de comment e disable_send_notification opcionais). Os spend_id precisam ser únicos dentro do lote; se não, a chamada inteira falha com 400 duplicate_spend_id antes de qualquer execução. Uma estrutura inválida nos itens, o modo de pagamentos do app ou o limite diário também podem causar a rejeição da chamada inteira antes de qualquer pagamento. Se a chamada for aceita, os resultados vêm em result.items.

Os itens são liquidados de forma independente, em ordem — um item que falha nunca desfaz os outros. A chamada devolve HTTP 200 com ok: true mesmo quando alguns itens falharam, então sempre confira cada item:

• sucesso: {"ok": true, "spend_id": "…", "result": <transfer object>}
• falha: {"ok": false, "spend_id": "…", "error": {"code": …, "name": "…"}} com os mesmos nomes de erro de um transfer único.

Os itens do lote compartilham o espaço de idempotência com as transferências únicas: repetir o lote inteiro — ou reenviar um item como um transfer único com o mesmo spend_id — repete a resposta em vez de pagar duas vezes.

getTransfers

GET /pay/api/getTransfers — escopo read. Filtros: asset, transfer_ids (separados por vírgula), spend_id (correspondência exata — busque um pagamento pela sua própria chave), status (pending / completed / returned), além de offset / count. Devolve {"items": [transfer, …]}, dos mais novos para os mais antigos.

createCheck

POST /pay/api/createCheck — escopo checks, limite de 60 por minuto. Por padrão, cria um cheque de resgate único com fundos do saldo do seu app. Qualquer pessoa com o link, ou apenas o usuário definido, pode resgatá-lo. A extensão recipients cria uma lista de destinatários com um valor separado para cada um. O total é reservado na criação (sai de available e vai para onhold no getBalance). A criação de cheques está sujeita aos mesmos limites de valor e de pagamentos diários das transferências.

Parâmetro	Tipo	Obrigatório	O que significa
asset	string	sim	código do ativo
amount	string	exceto quando recipients é informado	string decimal positiva; com recipients, o total é calculado a partir da lista
pin_to_user_id	integer	não	só este id de usuário do Telegram pode resgatar
pin_to_username	string	não	só este @usuário pode resgatar (o @ é opcional; ignorado quando pin_to_user_id também é definido). O nome de usuário precisa pertencer a alguém que já usa o app
spend_id	string	não	chave de idempotência (extensão) — use uma
recipients	array	não	extensão: de 1 a 100 itens, cada um com user_id ou username e um amount positivo em string decimal. Não pode ser combinado com um usuário definido para o cheque
password	string	não	extensão: senha exigida para resgatar; até 64 caracteres
expires_in	integer	não	extensão: prazo em segundos; omitido ou 0 = sem expiração

O resultado é o objeto de cheque: check_id, hash, asset, amount, amount_minor, bot_check_url (o link t.me de resgate), status (active / activated), pin_to_user_id, created_at, activated_at, expires_at e recipients (null para um cheque comum; caso contrário, cada item contém user_id, username, amount, amount_minor e claimed_at). Cada resgate dispara o webhook opcional check_activated; no caso de uma lista de destinatários, ele também inclui activated_slot. A expiração devolve o saldo não resgatado; a expiração de um cheque com lista de destinatários pode enviar check_expired.

A resposta atual usa status: "active" para todo cheque que não foi resgatado por completo, inclusive os expirados. Confira também expires_at: o status active sozinho não garante que o link ainda possa ser resgatado.

Erros: 403 payouts_disabled / 403 recipient_not_allowed (o modo de pagamentos — no modo allowlist, todo destinatário definido individualmente ou na lista do cheque precisa estar autorizado), 400 unknown_asset, 400 invalid_amount, 404 user_not_found (o nome de usuário fixado não corresponde a ninguém), 409 insufficient_funds e o par do spend_id.

deleteCheck

POST /pay/api/deleteCheck — escopo checks. Um parâmetro: check_id. Cancela um cheque ativo e devolve o saldo não resgatado ao saldo do app; retorna true. Erros: 404 check_not_found, 409 check_not_active (resgatado por completo, expirado ou excluído).

getChecks

GET /pay/api/getChecks — escopo read. Filtros: asset, check_ids (separados por vírgula), status (active / activated), além de offset / count. Devolve {"items": [check, …]}, dos mais novos para os mais antigos; os cheques excluídos nunca são devolvidos.