Source: https://cryptanio.com/pt/wiki/receber-pagamentos-cripto-bot-telegram/ Language: pt # Como receber pagamentos em criptomoedas em um bot do Telegram Como vincular um pedido de produto físico no seu próprio bot do Telegram a uma fatura do Cryptanio\, enviar o link de pagamento e verificar o pagamento\. Com as restrições de Telegram Stars e Mini Apps\. Atualizado: 2026-11-14 É possível vincular um pagamento em criptomoedas a um pedido no seu próprio bot do Telegram\: o servidor cria uma fatura do Cryptanio\, o bot envia o link ao comprador e\, depois de verificar o pagamento\, informa que o pedido foi aceito\. A seguir\, vamos usar uma loja de produtos físicos\, como pôsteres impressos\. O bot e o processamento dos pedidos continuam sendo desenvolvidos por você\. ## Primeiro\, confira as regras do Telegram {#primeiro-confira-as-regras-do-telegram} Para produtos e serviços digitais vendidos dentro do Telegram\, é obrigatório usar Telegram Stars\, identificadas por XTR\. Isso inclui\, por exemplo\, o acesso pago ao conteúdo de um bot\. Um link para um site externo não cria uma exceção\: você não pode oferecer criptomoedas no lugar de Stars para esse tipo de compra\. Essas restrições estão descritas expressamente na [documentação de Telegram Stars]()\. Nosso cenário é um bot comum\, sem Mini App\, e um pedido de produto físico\. Mini Apps e os bots associados a elas estão sujeitos a restrições adicionais para integrações com blockchain\, incluindo o uso de TON\. Bots comuns sem Mini App são explicitamente excluídos dessas regras nas [Blockchain Guidelines do Telegram]()\. Portanto\, não aplique esta instrução a uma Mini App sem uma verificação adicional\. As regras do Telegram foram verificadas em 13 de novembro de 2026\. ## O que você vai precisar {#o-que-voc-vai-precisar} Prepare seu próprio bot\, um servidor para executá\-lo\, uma conta do Cryptanio e um projeto com o serviço Payments ativo\. Você precisa de endereços de recebimento conectados ao Payments desse projeto e de uma chave API de modo real com permissões para faturas e para o serviço necessário\. Guarde no servidor o token do bot do Telegram\, a chave API do Cryptanio e o segredo usado para verificar o webhook\. O comprador recebe somente seu link de pagamento\. Este cenário não pressupõe uma integração pronta que crie sua loja e processe os pedidos por conta própria\. ## 1\. Prepare o projeto de pagamentos {#1-prepare-o-projeto-de-pagamentos} Ative o Payments e adicione os endereços de recebimento ao conjunto de endereços do serviço pelo painel\. Cadastrar o endereço apenas no catálogo de endereços não é suficiente\. Confirme que a rede e o ativo desejados estão disponíveis no projeto\; não prometa ao comprador opções que não aparecem na página de pagamento\. Se a diferença entre USDT e a rede ainda não estiver clara\, leia primeiro [“Rede e token”]()\. A [fatura]() vincula uma solicitação específica de pagamento ao seu estado\. ## 2\. Vincule o pedido ao comprador {#2-vincule-o-pedido-ao-comprador} Quando o usuário escolher um pôster e confirmar o pedido\, o servidor cria um número interno para esse pedido\. Guarde a relação entre o pedido\, o comprador do Telegram e o futuro ID da fatura\. Mantenha os dados de contato e o endereço de entrega no seu próprio sistema\: não é necessário incluí\-los no link técnico nem em uma mensagem pública\. Deve ser possível localizar cada pedido de forma inequívoca pelo ID da fatura salvo\. Isso permite processar o pagamento mesmo depois de reiniciar o bot\. ## 3\. Crie uma fatura separada {#3-crie-uma-fatura-separada} Solicite a criação da fatura pela API v1 no servidor\. Para o cenário em que o comprador escolhe a rede e o ativo\, defina a cotação do pedido por invoice\_currency e invoice\_amount\. Por exemplo\, USD 12\.50 é uma unidade de cotação\, enquanto o pagamento é feito em uma criptomoeda compatível\. Isso não representa o recebimento de dólares nem uma conversão automática dos fundos\. Abaixo está uma referência ao exemplo compatível de criação de pedido no catálogo da documentação\: ```bash #!/usr/bin/env bash set -euo pipefail : "${CRYPTANIO_API_KEY:?Set CRYPTANIO_API_KEY}" : "${CRYPTANIO_OPERATION_ID:?Set CRYPTANIO_OPERATION_ID}" : "${CRYPTANIO_PROJECT_ID:?Set CRYPTANIO_PROJECT_ID}" json_string() { local text="$1" char code index output='"' for ((index=0; index<${#text}; index++)); do char="${text:index:1}" case "$char" in '"'|'\') output+="\\$char" ;; *) printf -v code '%d' "'$char" if ((code < 32)); then printf -v char '\\u%04x' "$code"; fi output+="$char" ;; esac done printf '%s"' "$output" } response_file="$(mktemp)" trap 'rm -f "$response_file"' EXIT transfer_status=0 http_status="$(curl \ --silent --show-error --max-time 30 --request POST \ --header "Authorization: Bearer $CRYPTANIO_API_KEY" \ --header 'Accept: application/json' \ --header 'Content-Type: application/json' \ --header "Idempotency-Key: $CRYPTANIO_OPERATION_ID" \ --data-binary '{"project":'"$(json_string "$CRYPTANIO_PROJECT_ID")"',"invoice_currency":"USD","invoice_amount":"12.50","reference":"order-42"}' \ "https://api.cryptanio.com/v1/invoices" \ --output "$response_file" --write-out '%{http_code}')" || transfer_status=$? if [[ "$http_status" == 2?? ]]; then cat "$response_file" exit "$transfer_status" fi printf 'HTTP %s\n' "$http_status" >&2 cat "$response_file" >&2 exit 1 ``` [Transferir exemplo]() Informe os parâmetros do seu próprio pedido\. Uma nova operação exige um Idempotency\-Key exclusivo\; ao repetir a mesma solicitação depois de uma falha\, mantenha a chave anterior\. Assim\, um novo clique não deve criar outra fatura\. Os detalhes estão no [guia de confirmação de pedidos]()\. ## 4\. Envie o link ao comprador {#4-envie-o-link-ao-comprador} Guarde checkout\_url da resposta de criação e envie\-o em um botão com link no chat privado\. A Bot API aceita botões de URL\, conforme descrito em [InlineKeyboardButton]()\. O comprador abre a página do Cryptanio e escolhe um método de pagamento disponível\. Envie exatamente a URL recebida\. Não monte o link a partir do ID\: o link retornado ao consultar a fatura serve apenas para visualização\. A resposta de criação salva é necessária para continuar o pagamento interativo\. ## 5\. Confirme o pagamento no servidor {#5-confirme-o-pagamento-no-servidor} Configure o [webhook]() do projeto para o seu processador e verifique a assinatura usando o corpo original da solicitação\. Relacione o evento à fatura salva e depois confira o estado atual dela pela API\. Encaminhe o pedido para processamento somente com o estado de sucesso paid\. A detecção de uma transação\, o retorno do comprador ao chat e a mensagem “já paguei” não são essa confirmação\. Pagamentos parciais\, insuficientes\, excedentes ou atrasados podem exigir uma decisão separada\; não confirme esses pedidos automaticamente\. Uma nova entrega do mesmo webhook não deve iniciar a execução do pedido outra vez\. ## Como testar o fluxo e localizar erros {#como-testar-o-fluxo-e-localizar-erros} Verifique o caminho completo com um pedido seu\: criação\, abertura do link\, pagamento\, alteração de estado e mensagem do bot\. Considere as taxas de rede\; essa criação de fatura trabalha com dados reais\. Teste separadamente um novo clique no botão e a entrega repetida do evento\. Se os fundos foram enviados\, mas o pedido não foi confirmado\, confira a rede\, o ativo\, os dados de pagamento e as [confirmações da transação]()\. Se o estado já for paid\, procure o erro na relação entre pedido e fatura e no processador do bot\. As notificações ao proprietário no Telegram podem ser configuradas por uma [instrução separada]()\; por si só\, elas não substituem a verificação do pedido pelo servidor\. Etiquetas: [Pagamentos](https://cryptanio.com/pt/wiki/tag/payments/), [Telegram](https://cryptanio.com/pt/wiki/tag/telegram/), [Webhooks](https://cryptanio.com/pt/wiki/tag/webhooks/) ## Artigos relacionados - [A diferença entre rede e token](https://cryptanio.com/pt/wiki/rede-e-token/) - [O que é uma fatura de pagamento](https://cryptanio.com/pt/wiki/o-que-e-uma-fatura/) - [Como confirmar automaticamente o pagamento de um pedido por webhook](https://cryptanio.com/pt/wiki/confirmar-pagamento-de-pedido-por-webhook/)