Integração via Iframe

Antes de começar: autorize o seu domínio

O navegador só permite o iframe em páginas de domínios que você tenha autorizado. Cadastre-os no console, em Checkout. Sem isso, o iframe é bloqueado pela política de segurança da página (frame-ancestors) e aparece em branco, mesmo com o payload correto.

Cadastre cada origem na forma https://seudominio.com, sem caminho nem query, e inclua também os domínios de homologação. Apenas o owner do parceiro pode alterar a lista.

Uso básico

Incorpore o checkout diretamente no seu site:

<iframe
  src="https://trp.tonramp.io/trp/{payload}"
  width="440"
  height="700"
  frameborder="0"
  style="border: none; border-radius: 12px;"
></iframe>

Com domínio próprio ativo, troque o src por https://trp.seudominio.com/trp/{payload}. Autorizar o domínio da página que embute o iframe continua obrigatório — isso é outra lista, na mesma tela Checkout.

Gerando o payload

Gere o payload pela API autenticada (POST /v1/wallet/trp/generate) e use o campo payload da resposta na URL do iframe. A página só renderiza pagamentos para a carteira de um parceiro cadastrado.

Parâmetros

O iframe carrega a mesma página de checkout. Não precisa de parâmetros adicionais além do payload na URL.

Dimensões recomendadas

Dispositivo	Largura	Altura
Mobile	`100%`	`700px`
Desktop	`440px`	`700px`

Exemplo completo

<!DOCTYPE html>
<html>
<head>
  <title>Pagamento - Minha Loja</title>
</head>
<body>
  <h1>Finalize seu pagamento</h1>

  <div style="max-width: 440px; margin: 0 auto;">
    <iframe
      src="https://trp.tonramp.io/trp/trp010148UQBJ6gU8..."
      width="100%"
      height="700"
      frameborder="0"
      style="border: none; border-radius: 12px; box-shadow: 0 4px 12px rgba(0,0,0,0.1);"
    ></iframe>
  </div>
</body>
</html>

Tema

O iframe respeita o tema do sistema operacional do usuário (light/dark) automaticamente via prefers-color-scheme. O usuário também pode alternar manualmente dentro do checkout.

Onde o pagamento acontece

A página incorporada do checkout TRP é a porta de entrada: ela mostra o estabelecimento, o valor, o QR do link e o status ao vivo. O pagamento em USDT acontece no app do TonRamp, aberto pelos botões da página, e por isso sai do iframe (os links usam target="_top").

O checkout PIX é o contrário: https://api.tonramp.io/v1/c/{id} mostra o QR PIX e o pagamento fecha dentro do frame.