Renderizar smart checkout

Após a criação, a API retorna o checkout_token, utilizado para abrir ou incorporar o smart checkout no canal desejado.

O smart checkout pode ser renderizado de diferentes formas, conforme a experiência definida pelo cliente:

• Redirect / Hosted
• iFrame
• WebView
• SDK Mobile

🔗 URL do smart checkout

Para renderizar o smart checkout, basta informar o checkout_token recebido na etapa de criação usando a URL do ambiente desejado:

Também é possível informar o idioma da experiência através do parâmetro locale.

Exemplo de uso: https://smartcheckout.pagaragora.com.br/bsc/checkout?code={{checkout_token}}&locale={{locale}}

Valores possíveis:

🔀 Renderização via redirect/hosted

Neste modelo, o usuário é redirecionado para a URL do smart checkout, onde toda a jornada de pagamento é conduzida em uma página segura e hospedada pela Paytime. Alternativamente, essa mesma URL pode ser compartilhada diretamente com o usuário por meio de canais como WhatsApp, e-mail ou SMS, permitindo uma experiência de pagamento via link.

Esse formato é recomendado para integrações rápidas e de baixo esforço técnico, pois não exige implementação de interface de pagamento no lado do cliente, garantindo ao mesmo tempo uma experiência padronizada, atualizada e compatível com todos os métodos de pagamento suportados.

Exemplo de uso:

window.location.href = "https://smartcheckout.pagaragora.com.br/bsc/checkout?code={{checkout_token}}";

🧩 Renderização via iFrame

Neste modelo, o smart checkout é incorporado diretamente dentro da aplicação web do cliente.

Recomendação de uso:

<iframe
  src="https://smartcheckout.pagaragora.com.br/bsc/checkout?code={{checkout_token}}"
  allow="payment; clipboard-read; clipboard-write; publickey-credentials-get; publickey-credentials-create;">
</iframe>

Permissões de segurança no iFrame

Devido às políticas modernas de segurança adotadas pelos navegadores, é necessário declarar explicitamente permissões na propriedade allow da tag <iframe> para garantir o funcionamento adequado de determinados recursos do smart checkout, como cópia de código Pix, carteiras digitais, autenticação, etc.

Essas permissões controlam o acesso a funcionalidades sensíveis do navegador, como área de transferência e APIs de pagamento.

Compatibilidade e recomendações

Navegadores modernos como Chrome, Edge e versões recentes do Firefox aplicam políticas mais restritivas de sandbox e isolamento de conteúdo. Nesses ambientes, a ausência das permissões adequadas pode comprometer funcionalidades do checkout.

Para garantir uma integração estável:

• teste o iFrame em diferentes navegadores e dispositivos;
• valide o funcionamento de todos os métodos de pagamento habilitados;
• verifique se há bloqueios relacionados a permissões no console do navegador.

Uso do atributo sandbox

Caso o atributo sandbox esteja presente no <iframe>, ele pode restringir funcionalidades mesmo quando allow estiver configurado.

Dependendo da configuração, será necessário ajustar o sandbox para não bloquear recursos essenciais do smart checkout.

Exemplo de uso: sandbox="allow-scripts allow-forms allow-same-origin"

📱 Renderização via WebView

Para aplicações mobile que utilizam WebView, o smart checkout pode ser aberto utilizando a mesma URL.

Esse modelo permite que o pagamento seja realizado dentro do aplicativo do cliente, mantendo a experiência integrada à jornada do usuário.

Recomendações:

• habilitar JavaScript;
• permitir abertura de links externos quando necessário;
• tratar callbacks de sucesso, erro e pendência;
• validar comportamento em Android e iOS;
• garantir suporte a cópia de código Pix e boleto.

🧠 Boas práticas

• Utilize sempre o checkout_token retornado na criação do smart checkout.
• Não exponha chaves de autenticação no frontend.
• Para iFrame, informe corretamente o atributo allow.
• Teste a renderização em múltiplos navegadores e dispositivos.
• Valide o comportamento de Pix, boleto, cartão e carteiras digitais separadamente.
• Use webhooks como fonte oficial do status da transação.