Referência da API: transferências e cheques

Os métodos de pagamento. Uma transferência manda fundos do saldo do seu app direto para a carteira de um usuário do Telegram; um cheque é um link resgatável que você banca antes. As convenções (autenticação, envelope, valores, spend_id) estão na página da referência da API para comerciantes.

transfer

POST /pay/api/transfer — escopo payouts, limite de 30 por minuto. Liquida na hora e de forma atômica; não existe estado pendente.

Parâmetro	Tipo	Obrigatório	O que significa
user_id	integer	sim	o id de usuário do Telegram de quem recebe. A pessoa já precisa ser usuária do app — um pagamento para um id desconhecido dá erro, em vez de deixar fundos perdidos
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 quem recebe no Telegram

O resultado é o objeto de transferência: transfer_id, hash, user_id, asset, amount, amount_minor, spend_id, comment, status (sempre completed), created_at, completed_at.

Erros: 404 user_not_found (quem recebe nunca usou o app), 409 recipient_blocked, 400 amount_too_small / 400 amount_too_big (fora dos limites por transferência), 409 insufficient_funds, 404 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, 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.

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), 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. Cria um cheque de resgate único bancado pelo saldo do seu app; qualquer pessoa com o link — ou só o usuário fixado — pode resgatá-lo para a carteira dela. O valor é reservado no momento em que o cheque é criado (ele sai de available e vai para onhold no getBalance).

Parâmetro	Tipo	Obrigatório	O que significa
asset	string	sim	código do ativo
amount	string	sim	string decimal positiva
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 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

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. Um resgate dispara o webhook opcional check_activated.

Erros: 404 unknown_asset, 400 invalid_amount, 404 user_not_found (o 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 não resgatado e devolve o valor reservado para o saldo do seu app; retorna true. Erros: 404 check_not_found, 409 check_not_active (já resgatado 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.