Paystation Client Public Docs

Appearance

Embed do iframe do Checkout (Upsell) na página de Obrigado ​

Esta documentação mostra como injetar dinamicamente um iframe com o checkout (upsell) após a compra.

A ideia é simples:

  1. O comprador finaliza o pagamento e é redirecionado para a sua página de obrigado.
  2. A URL dessa página contém alguns parâmetros (ex.: client_token, upsell_ids, etc.).
  3. Um script na página lê esses parâmetros, monta a URL do checkout embutido e cria o iframe dentro de um container.

Quando usar ​

  • Você quer embedar (incorporar) o checkout/upsell em um iframe dentro de uma página que já existe (ex.: obrigado.html).
  • Você controla o HTML da página de obrigado (site próprio, página estática, WordPress, etc.).
  • O serviço que renderiza o checkout em iframe permite ser embutido (ver seção “Requisitos e segurança”).

Como funciona o script do obrigado.html ​

O script que está no final do obrigado.html faz:

  1. Define uma lista “permitida” de parâmetros (paramsList) que serão repassados ao iframe.
  2. Procura um container na página via seletor CSS (por padrão: [data-upsell-container]).
  3. Lê os parâmetros atuais da URL da página (window.location.search).
  4. Monta a URL do iframe no formato:
{BASE_URL}/{client_token}/{upsell_ids}?<querystring>
  1. Cria o elemento <iframe> e injeta dentro do container.

Integração (passo a passo) ​

1) Crie (ou escolha) um container para o iframe ​

O exemplo usa um atributo data- para localizar onde o iframe vai aparecer:

html
<div data-upsell-container></div>

Você pode trocar a estratégia (ex.: id="upsell"), desde que também ajuste o seletor dentro do script.

2) Cole o script no final do <body> ​

Coloque o script depois do container (ou garanta que rode apenas após o DOM estar pronto). No exemplo, o script está ao final do <body>.

3) URL base do checkout (BASE_URL) ​

js
const iframeUrl = new URL(
  `http://localhost:3070/${currentParams.get('client_token')}/${currentParams.get('upsell_ids')}`
);

Para homologação, troque a URL para https://paystation-client-homolog.quero.space.

4) Garanta que a sua página de obrigado receba os parâmetros na URL ​

O script depende de parâmetros presentes em window.location.search.

Exemplo de URL da sua página de obrigado:

https://www.sualoja.com/obrigado.html?client_token=SEU_TOKEN&upsell_ids=10,12&transaction_id=abc123

Se client_token e upsell_ids não estiverem presentes, a URL gerada para o iframe ficará incorreta (ex.: .../null/null).

Exemplo completo (copiar e colar) ​

Este é o mesmo padrão usado em obrigado.html (ajuste o BASE_URL e, se quiser, o targetSelector):

html
<div data-upsell-container></div>

<script>
  (function () {
    const paramsList = [
      'client_token',
      'upsell_ids',
      'transaction_id',
      'transaction_type',
      'signature',
      'full_name',
      'email',
      'cpf',
      'phone_number',
    ];

    const targetSelector = '[data-upsell-container]';
    const targetDiv =
      document.querySelector(targetSelector) ||
      document.body.appendChild(document.createElement('div'));

    const currentParams = new URLSearchParams(window.location.search);

    const BASE_URL = 'https://SEU-DOMINIO-DO-CHECKOUT'; // ajuste aqui
    const iframeUrl = new URL(
      `${BASE_URL}/${currentParams.get('client_token')}/${currentParams.get('upsell_ids')}`
    );

    paramsList.forEach((param) => {
      const value = currentParams.get(param);
      if (value !== null && value !== '') {
        iframeUrl.searchParams.set(param, value);
      }
    });

    const iframe = document.createElement('iframe');
    iframe.src = iframeUrl.toString();
    iframe.title = 'Checkout (Upsell)';
    iframe.width = '100%';
    iframe.height = '480';
    iframe.style.border = '1px solid #e1e8ed';
    iframe.style.borderRadius = '12px';
    iframe.loading = 'lazy';

    targetDiv.appendChild(iframe);
  })();
</script>

Exemplo de src gerado ​

Se a sua página estiver em:

https://www.sualoja.com/obrigado.html?client_token=abc&upsell_ids=10,12&transaction_id=tx_123

O iframe.src deverá ficar assim:

https://paystation-client.quero.space/abc/10,12?client_token=abc&upsell_ids=10,12&transaction_id=tx_123

Parâmetros suportados (repassados ao iframe) ​

O script repassa para o iframe apenas os parâmetros listados em paramsList:

ParâmetroObrigatórioPara que serve (visão geral)
client_tokenSimIdentifica o cliente/conta/ambiente do checkout embutido. Também é usado no caminho da URL do iframe.
upsell_idsSimIDs das ofertas/upsells a exibir (geralmente uma lista, ex.: 10,12). Também é usado no caminho da URL do iframe.
transaction_idRecomendadoIdentificador da transação original.
transaction_typeOpcionalTipo de transação (ex.: cartão/pix/boleto), conforme o serviço espera.
signatureRecomendadoAssinatura para validação (ex.: HMAC) e prevenção de fraude/forja de parâmetros, conforme contrato do serviço.
full_nameOpcionalNome do comprador (pré-preenchimento).
emailOpcionalE-mail do comprador (pré-preenchimento).
cpfOpcionalCPF do comprador (pré-preenchimento).
phone_numberOpcionalTelefone do comprador (pré-preenchimento).

Notas importantes:

  • client_token e upsell_ids são usados tanto no caminho (/.../...) quanto repassados na querystring (por estarem na lista). Se o serviço não precisar deles na querystring, você pode removê-los do paramsList.
  • Todos os valores são lidos da URL atual e repassados como texto. Garanta que a origem desses parâmetros seja confiável (ver “Requisitos e segurança”).

Configurações que você pode querer ajustar ​

Container de destino ​

O seletor atual é:

js
const targetSelector = '[data-upsell-container]';

Se preferir usar id:

html
<div id="upsell"></div>

E no script:

js
const targetSelector = '#upsell';

Tamanho e estilo do iframe ​

No exemplo:

  • iframe.width = '100%'
  • iframe.height = '480'

Se o checkout ficar “cortado”, aumente o height ou implemente auto-resize (ver “Troubleshooting”).

Requisitos e segurança (essencial para produção) ​

1) Evite “mixed content” ​

Se a sua página de obrigado estiver em https://, o navegador bloqueia iframes http://.

  • Página: https://...
  • Iframe: http://... ❌ (provável bloqueio)

Use https:// no BASE_URL do iframe em produção.

2) O domínio do checkout precisa permitir ser embutido ​

O servidor do checkout embutido deve permitir framing pelo seu domínio.

Na prática, isso costuma ser feito com:

  • Content-Security-Policy: frame-ancestors ... (recomendado)
  • e/ou X-Frame-Options (legado; cuidado com compatibilidade)

Se estiver bloqueado, o iframe pode ficar em branco ou o navegador pode mostrar erro no console.

Solicite ao time de suporte do Paystation para que seu domínio seja liberado para utilização.

3) Se sua página tiver CSP, libere o domínio do iframe ​

Se você usa Content-Security-Policy na página de obrigado, precisa permitir o domínio do checkout em diretivas como frame-src (ou child-src, dependendo do caso).

4) Privacidade e dados sensíveis em querystring ​

O script repassa dados via URL (GET). Isso pode parar em:

  • histórico do navegador,
  • logs de servidor/proxy,
  • ferramentas de analytics.

Recomendações:

  • repasse apenas o necessário;
  • prefira tokens curtos e de uso único;
  • use signature/validação do lado do servidor do checkout;
  • use HTTPS sempre.

Troubleshooting (problemas comuns) ​

Iframe não carrega / fica vazio ​

Checklist:

  • A URL do BASE_URL está correta e acessível?
  • client_token e upsell_ids estão presentes na URL da página de obrigado?
  • A página está em HTTPS e o iframe também? (mixed content)
  • O serviço do iframe permite ser embutido (CSP frame-ancestors / X-Frame-Options)?

Conteúdo “cortado” (altura insuficiente) ​

Ajuste iframe.height para um valor maior.

Se o conteúdo muda de altura dinamicamente, a solução ideal é implementar um mecanismo de auto-resize via postMessage (precisa de suporte do conteúdo dentro do iframe).