Checkout transparente ou hospedado: a cara da sua marca sem o PCI no seu colo

Checkout transparente é o modelo em que o comprador digita os dados de pagamento, inclusive o cartão, numa tela que parece 100% do seu site, sem ser levado para uma página do gateway. O HeroPay não oferece checkout transparente de cartão hoje: a API pública não tem campo para número de cartão nem CVV. O que o HeroPay oferece é o checkout hospedado, personalizável por oferta (banners, cores, identidade, pixels), com 40+ recursos de conversão prontos, Pix e boleto a R$ 0 e cartão a 3,49% por transação aprovada. Esta página explica os dois modelos com honestidade, inclusive a parte que quase ninguém conta: quem fica com o PCI DSS.

Criar conta sandbox · Ler a documentação

O que é checkout transparente?

Checkout transparente é o modelo de pagamento online em que o comprador conclui a compra inteira dentro do ambiente da loja, com o layout e a marca dela, sem ser redirecionado para uma página externa do gateway. Os dados de pagamento são capturados na tela da loja e enviados ao provedor de pagamento, normalmente trocados por um token antes de chegar ao servidor do lojista.

O nome vem da ideia de que o gateway fica "transparente", invisível para o comprador. Na prática de mercado, há dois jeitos de fazer isso:

1. Campos seguros do gateway embutidos na sua página. O formulário parece seu, mas os campos de cartão são servidos pelo provedor (em iframe) ou capturados por um JavaScript dele, que devolve um token. É o modelo que Mercado Pago e Pagar.me documentam para o transparente deles.
2. Formulário 100% próprio, com o cartão passando pelo seu servidor. Você recebe o número e repassa para a API do gateway. É o mais flexível e, de longe, o mais caro em segurança e auditoria.

O que é checkout hospedado?

Checkout hospedado é o modelo em que a página de pagamento é servida pelo próprio gateway: a loja envia o comprador para uma URL do provedor (ou gera essa URL por API), o comprador digita os dados ali e a loja recebe o resultado por redirecionamento e por webhook. O número do cartão nunca passa pela página nem pelo servidor da loja.

É o modelo do HeroPay. Você cria um link de pagamento por API, pelo painel ou por prompt, recebe a URL do checkout em data.offer.url e confirma a venda pelo webhook spark_payment_confirmed.

Checkout transparente vs hospedado: qual a diferença?

Verificado em setembro de 2026 · fontes: Mercado Pago Developers, PCI DSS (contagem de requisitos por tipo de SAQ), PCI Security Standards Council, atualização do SAQ A, OpenAPI do HeroPay. O enquadramento exato depende da sua integração: confirme com seu adquirente ou auditor.

Quais as vantagens e desvantagens do checkout transparente?

A favor do transparente:

• Controle total da experiência. Você decide cada pixel, a ordem dos campos, a microcopy e o fluxo entre carrinho e pagamento.
• Nenhuma troca de endereço na barra do navegador. O comprador não sai do seu domínio, o que agrada lojas com marca forte e fluxos longos (e-commerce com frete, por exemplo).
• Dados de navegação no seu analytics. Tudo acontece na sua página, sem configuração de pixel em domínio de terceiro.

Contra o transparente (a parte que as páginas de gateway costumam pular):

• O PCI DSS entra na sua página. Mesmo com campos seguros do gateway, desde 31 de março de 2025 o lojista que quer ficar no SAQ A com formulário embutido precisa confirmar que o site não é suscetível a ataques de scripts que afetem o pagamento (a regra que existe por causa de ataques de skimming, em que um script injetado copia o cartão enquanto o comprador digita). Na prática: inventário de scripts, controle de mudanças e monitoramento da página de pagamento. Com formulário próprio, você cai no SAQ D, com cerca de 250 requisitos.
• O formulário é seu para sempre. Validação de campo, máscara, bandeira, mensagens de recusa, acessibilidade, mobile, 3DS: tudo isso é código que você mantém.
• Conversão vira projeto seu. Order bump, upsell sem redigitar cartão, 2 cartões, retentativa após recusa, parcelamento que recupera recusa por limite: no transparente, cada um é uma sprint.
• Antifraude depende de você mandar os sinais. Dados de dispositivo e comportamento precisam ser coletados e enviados corretamente, ou a aprovação cai.

Quais as vantagens e desvantagens do checkout hospedado?

A favor do hospedado:

• Escopo de PCI mínimo. O cartão é digitado na página do gateway; seu site e seu servidor não tocam no dado. Quem integra assim normalmente se enquadra no SAQ A.
• Recursos de conversão prontos e já testados em volume. No HeroPay, são 40+ recursos no ar, de order bump a recuperação de carrinho.
• Integração em minutos. Uma chamada de API devolve a URL do checkout, e o webhook confirma a venda.

Contra o hospedado:

• O endereço muda. O comprador passa por um domínio do gateway na hora de pagar.
• A personalização tem limite. Você configura o que o gateway permite (banners, cores, campos), não desenha o formulário de cartão do zero.
• Seu analytics precisa de ponte. O rastreamento na página de pagamento depende dos pixels e integrações que o gateway oferece.

Por que as pessoas pedem checkout transparente (e como o hospedado do HeroPay resolve)

Quase ninguém quer o transparente pelo PCI. Quer por dois motivos: a tela de pagamento não parece da marca e o redirecionamento assusta o comprador. Os dois têm resposta no checkout hospedado do HeroPay.

1. "Quero que pareça meu." O checkout do HeroPay é personalizável por oferta:

• banners no topo e na lateral, com versões para desktop e mobile;
• cor ou imagem de fundo;
• identidade e pixels configurados por oferta (cada produto com a própria cara e o próprio rastreamento);
• campos configuráveis, cronômetro de escassez e prova social de compras recentes;
• página de obrigado própria.

2. "Não quero que o comprador estranhe o redirecionamento." O comprador sempre cai no mesmo domínio de pagamento, com HTTPS, e com os dados pré-preenchidos por URL quando você já os tem. A URL que a API devolve hoje fica em domínio de pagamento da HeroSpark, não no domínio do lojista. Para o comprador, a transição do seu site para o checkout é um clique para uma página com a sua identidade, não um salto para uma tela genérica.

3. O que o transparente não te daria de graça. Upsell one-click sem redigitar o cartão, pagamento com 2 cartões, Parcelamento Inteligente (até 3 retentativas por parcela em recusa por limite), retentativa pós-recusa, Apple Pay e Google Pay, compra 1-click com cartão salvo na rede, Meta Pixel com API de Conversões deduplicada e recuperação de carrinho abandonado com gatilho em 15 minutos. Tudo isso vem pronto no hospedado. No transparente, você construiria cada item.

Como funciona o checkout hospedado do HeroPay, do ponto de vista do dinheiro

1. Seu sistema cria a cobrança sem dado de cartão. POST /payment_links com nome, preço em centavos e métodos aceitos. A resposta traz a URL do checkout.
2. O comprador abre o checkout com a identidade da sua oferta e escolhe Pix, cartão em até 12x ou boleto.
3. No cartão, o dado é tokenizado e passa pelo antifraude incluso na taxa; no Pix, o checkout gera QR Code e copia e cola.
4. Seu sistema recebe o evento assinado. payment_pix_created quando o Pix é gerado, spark_payment_confirmed quando o pagamento confirma, payment_credit_cart_refused em recusa.
5. O dinheiro entra no saldo (GET /financial/balance) e sai por saque para a chave Pix do titular (POST /financial/withdrawals).

Na prática, por código

Crie a cobrança com Pix e cartão e mande o comprador para a URL devolvida:

curl -X POST "$HEROPAY_API_URL/payment_links" \
  -H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -H "Content-Type: application/json" \
  -d '{
    "payment_link": {
      "name": "Pedido 4821",
      "description": "Curso de Fotografia",
      "price_cents": 19700,
      "absorbs_fees": true,
      "max_installments": 12,
      "payment_methods": ["pix", "credit_card"],
      "src": "pedido-4821"
    }
  }'

Resposta 201 Created (trecho):

{
  "message": "Payment link created successfully",
  "data": {
    "id": 137,
    "name": "Pedido 4821",
    "price_cents": 19700,
    "max_installments": 12,
    "period": "unitary",
    "public_id": "fc280e25-7cbd-446f-b34f-5b8824bb5124",
    "offer": {
      "kind": "payment_link",
      "url": "https://pay.beta.herospark.com/fc280e25-7cbd-446f-b34f-5b8824bb5124-6094?src=pedido-4821",
      "accepted_payment_methods": ["pix", "credit_card"]
    }
  }
}

Cadastre os webhooks que fecham o ciclo sem polling:

curl -X POST "$HEROPAY_API_URL/webhook" \
  -H "Authorization: Bearer $HEROPAY_JWT_TOKEN" \
  -H "Accept: application/vnd.herospark.com; version=1" \
  -H "Content-Type: application/json" \
  -d '{
    "webhook": {
      "trigger": "spark_payment_confirmed",
      "webhook_url": "https://seuapp.com/webhooks/heropay",
      "request_method": "post"
    }
  }'

Repita com "trigger": "payment_pix_created" para saber quando o comprador gerou o Pix. O src que você mandou (pedido-4821) volta em cart.src em todo webhook, então você amarra o pagamento ao pedido do seu banco sem adivinhação. Valide sempre a assinatura X-HeroPay-Signature (HMAC SHA-256 do corpo bruto): o passo a passo está em /webhooks e em /seguranca.

Por prompt

Cole https://heropay.tech/llms.txt na conversa com Claude, ChatGPT, Cursor, Lovable e outros, e peça em português:

"Com base em https://heropay.tech/llms.txt, escreva o código que cria um link de pagamento HeroPay de R$ 197 para o pedido 4821, aceitando Pix e cartão em até 12x, com src pedido-4821, imprime a URL do checkout e cadastra o webhook de pagamento confirmado apontando para https://seuapp.com/webhooks/heropay."

A chave fica no seu ambiente, nunca colada no chat. Um MCP server oficial está em desenvolvimento; hoje o caminho é llms.txt, docs abertas e API REST. Detalhes em /ai.

E o Pix? Dá para mostrar o QR Code dentro do meu site?

Hoje, não. A API v1 do HeroPay não tem endpoint que crie uma cobrança Pix e devolva o QR Code ou o copia e cola para você exibir na sua própria tela. O Pix nasce do link de pagamento (payment_methods: ["pix"]) e o QR Code é gerado dentro do checkout hospedado.

O que dá para fazer hoje, e cobre boa parte do motivo de quem pede "Pix transparente":

• Seu fluxo até o botão de pagar é todo seu. Carrinho, cálculo de preço, cupom interno e cadastro acontecem no seu app; a API cria um link por pedido, com o valor exato e o src do pedido.
• Checkout só com Pix. Mande payment_methods: ["pix"] e o comprador cai direto numa tela de Pix, sem escolher método.
• Dados pré-preenchidos por URL, para o comprador não redigitar o que você já sabe.
• Evento de Pix gerado. O webhook payment_pix_created avisa quando o comprador gerou o Pix, e o spark_payment_confirmed confirma o pagamento, os dois com cart.src para achar o pedido. Com o evento de Pix gerado, seu sistema pode lembrar o comprador pelo seu canal e mandar de volta a URL do checkout.

Criar cobrança Pix avulsa por API, com QR Code e copia e cola na resposta, está listado como lacuna em /desenvolvedores e aberto para voto no roadmap público da comunidade, sem data prometida.

Casos de uso

Curso online de R$ 197 vendido pelo Instagram. O criador não quer construir tela de pagamento; quer que a página de pagamento tenha a cara do curso. Configura banner e cores na oferta, cria o link por API com src=instagram e manda na bio. No Pix, paga R$ 0 de tarifa e recebe os R$ 197 inteiros. No cartão, a tarifa é 3,49% de R$ 197, ou seja, R$ 6,88 por venda aprovada.

Micro-SaaS com app feito no Lovable. O dev tem o app pronto e quer cobrança sem tocar em cartão. O botão "assinar" chama uma função serverless que cria o link e redireciona para o checkout. O webhook spark_payment_confirmed libera o plano. Nenhum dado de cartão passa pelo app, e o dev não precisa de questionário de PCI além do mais simples. Veja /integracoes/lovable.

Loja que realmente precisa de transparente de cartão. Um e-commerce com checkout de várias etapas (frete, endereço, cupom) e requisito formal de manter o cartão na própria página. Aqui a resposta honesta é: o HeroPay não atende esse requisito hoje. Se o requisito for de marca, e não de arquitetura, o hospedado personalizado costuma resolver; se for de arquitetura, você precisa de um gateway com campos seguros embutidos.

Limites e regras honestas

• Sem checkout transparente de cartão: nenhum endpoint recebe número de cartão, validade ou CVV. O tema está aberto para voto no roadmap público da comunidade, sem data prometida.
• Sem Pix direto por API: o QR Code e o copia e cola são gerados no checkout hospedado, não devolvidos pela API.
• Checkout embutido em iframe no seu site: não está documentado; o fluxo suportado é redirecionar o comprador para a URL do checkout.
• Domínio próprio no checkout: não conte com ele; hoje a URL devolvida fica em domínio de pagamento da HeroSpark.
• Valores: mínimo de R$ 5,00 por link, parcela mínima de R$ 1,99, até 12x, sempre em centavos na API.

Comece pelo sandbox

O sandbox do HeroPay é gratuito e idêntico à produção: crie um link, personalize a oferta, pague pelo checkout de teste e veja o webhook chegar, sem fila de homologação. Quando estiver pronto, troque a chave.

Criar conta sandbox · Ler a documentação

Continue por: Checkout · Link de pagamento · Pix · Segurança e PCI DSS · Webhooks · Preços · Desenvolvedores · Glossário