Checkout

Fluxo do checkout

Seu backend gera um payload TRP com os dados do pagamento (em USDT)
O payload é enviado para o frontend como link universal
O comprador escaneia o QR code ou clica no link
A página de checkout detecta a plataforma:
- Telegram User-Agent → redireciona para o bot
- Cookie de preferência → redireciona conforme salvo
- Sem preferência → exibe página com botões (Telegram / Web)
O comprador confirma o valor e assina a transferência USDT via TonConnect
O merchant recebe USDT na wallet informada no payload
Seu sistema consulta o status via API

Gerando o checkout

Via API

curl -X POST https://api.tonramp.io/v1/wallet/trp/generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer tonr_SUA_API_KEY" \
  -d '{
    "wallet": "UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ",
    "merchant": "store123",
    "amount": "100.00",
    "currency": "USDT",
    "tx_id": "tx123456"
  }'

Via código (client-side)

import { generateTrpPayload } from '@/utils/trp'

const payload = generateTrpPayload(
  'UQBJ6gU8gh_jRrzYDlfw9cpCwHaSn2mrK4O-1h8CDENehGYJ',
  'store123',
  '100.00',
  'USDT',
  'tx123456'
)

const checkoutUrl = `https://trp.tonramp.io/trp/${payload}`

Página de checkout

A página de checkout em trp.tonramp.io/trp/\{payload\} exibe:

Seu logo, quando cadastrado, ou o logo TonRamp
Nome do estabelecimento
Valor formatado em USDT
QR code com o link universal
Botão “Pagar via Telegram”
Botão “Pagar via Navegador”
Status do pagamento (polling a cada 5 segundos)

Sua marca no checkout

No console, em Checkout, você define a marca que aparece na página de pagamento das suas cobranças:

Logo: PNG, JPEG ou WebP, até 96 KB. Fundo transparente funciona melhor, porque a página tem tema claro e escuro.
Cor da marca: usada no valor e no botão de pagar. A cor do texto sobre ela é escolhida automaticamente por contraste, então uma marca clara não gera botão ilegível.

Apenas o owner do parceiro altera a marca.

O que não muda: a assinatura “Powered by TonRamp” continua no rodapé, e o pagamento em si acontece no app do TonRamp, aberto pelos botões da página. A marca cobre a página de entrada, não o fluxo inteiro.

Domínio próprio (CNAME para hosted.tonramp.io), o que a marca não cobre e o passo a passo de DNS estão em White label.

Consultando status

Após o comprador acessar o link, você pode consultar o status:

curl "https://api.tonramp.io/v1/trp/status/{tx_id}?token={token}"

Resposta:

{
  "status": "pending",
  "amount": "10000",
  "currency": "USDT",
  "updated_at": "2025-03-05T12:00:00Z"
}

Status possíveis: pending (aguardando pagamento), error (falha no processamento), paid (pagamento recebido, processando a entrega), completed (USDT entregue, concluída), expired (expirou sem pagamento).

Cotação (Quote API)

Antes de confirmar o pagamento, o mini app consulta a quote para obter valor final (com fee) e saldo:

curl -H "Authorization: Bearer {token}" \
  https://api.tonramp.io/v1/trp/quote/{payload}

Resposta:

{
  "merchant": "store123",
  "wallet_dest": "UQBJ6gU8gh_...",
  "amount_usdt": 100.00,
  "fee_usdt": 1.0,
  "total_required_usdt": 101.00,
  "user_balance_usdt": 120.0,
  "has_sufficient_balance": true,
  "tx_id": "tx123456",
  "quote_id": "abc123",
  "quote_ttl_seconds": 120
}

Taxas

Cada pagamento TRP cobra:

Taxa fixa: máx(1 USDT, 1% do valor cobrado)
Gas TON: pequeno custo on-chain de alguns milicentavos de TON, pago pelo comprador na wallet dele

Exemplo para cobrança de 100 USDT:

Valor para o merchant: 100,00 USDT
Taxa TonRamp: 1,00 USDT
Total debitado do comprador: 101,00 USDT

Fluxo de pagamento no mini app

Quando o comprador clica em “Pagar via Telegram” ou “Pagar via Navegador”:

O mini app lê o start_param do Telegram WebApp (ou ?startapp= da URL)
Se o parâmetro começa com trp01, redireciona para a tela de confirmação
A tela consulta GET /v1/trp/quote/{payload} para obter valor, fee, total e saldo
Exibe: merchant, valor USDT, taxa, total, saldo do comprador
Se saldo insuficiente: botão “Carregar com PIX” (fluxo de top-up em evolução)
Se saldo suficiente: botão “Confirmar pagamento” gera a transação TonConnect
O comprador assina a transferência na wallet dele
USDT é transferido: valor para o merchant + taxa para a hot wallet TonRamp, de forma atômica em uma única assinatura