Cryptanio
Conta

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:

É 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

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

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

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

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

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:

#!/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.

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

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

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.

Artigos relacionados