Referência do SDK v3

Use esta página quando precisar do contrato exato do SDK de navegador para Payment Element v3.

Carregue o SDK

<script src="https://js.pagou.ai/payments/v3.js"></script>

O script expõe window.Pagou.

Pagou.setEnvironment("sandbox");

Ambientes suportados:

Ambiente	Uso
`production`	Padrão. Usa endpoints de coleta de produção.
`sandbox`	Use com chaves públicas e transações de teste.
`local`	Apenas desenvolvimento local.

Inicialize Elements

const elements = Pagou.elements({
  publicKey: "pk_test_sua_chave_publica",
  locale: "pt-BR",
  origin: window.location.origin,
});

Opções:

Opção	Obrigatória	Descrição
`publicKey`	Sim, antes do submit	Chave pública da empresa. Use `pk_test_` em sandbox e `pk_live_` em produção.
`locale`	Não	Locale enviado ao campo hospedado de cartão. O padrão é `pt-BR`.
`origin`	Não	Origem do checkout armazenada na sessão do Element. O padrão é `window.location.origin`.

Você pode atualizar uma instância existente antes do submit:

elements.update({
  publicKey: "pk_live_sua_chave_publica",
  locale: "pt-BR",
});

Crie e monte o campo de cartão

<div id="card-element"></div>

const card = elements.create("card", {
  theme: "default",
  locale: "pt-BR",
});

card.mount("#card-element");

elements.create("card") cria um campo hospedado de cartão. Se já existir um campo de cartão na mesma instância de elements, o SDK desmonta o campo anterior antes de criar o novo. Opções do cartão:

Opção	Descrição
`theme`	`default`, `night` ou `flat`.
`locale`	Sobrescreve o locale de Elements para este campo.
`style`	Objeto de estilo enviado ao campo hospedado.
`mountTimeoutMs`	Timeout de montagem em milissegundos. O padrão é `8000`.
`telemetry`	Envia telemetria best-effort de falha de montagem quando suportado. O padrão é `true`.

Eventos do cartão

card.on("ready", () => {
  messageEl.textContent = "";
});

card.on("change", (event) => {
  submitButton.disabled = !event.valid;
  brandEl.textContent = event.brand ?? "";
  errorEl.textContent = Object.values(event.errors ?? {})[0] ?? "";
});

card.on("error", (event) => {
  errorEl.textContent = event.message;
});

Eventos suportados:

Evento	Payload	Uso
`ready`	`{}`	O iframe hospedado carregou e concluiu o handshake com o SDK.
`change`	`{ valid, brand, errors }`	Habilite o submit apenas quando `valid` for `true`.
`error`	`{ code, message }`	Exiba erros de inicialização, montagem ou campo de cartão.

Remova handlers durante o teardown do componente quando a mesma instância de cartão puder continuar viva:

card.off("change", handleCardChange);

Envie um pagamento

elements.submit(...) é a ação principal do SDK. Ela cria uma sessão de Element, tokeniza o campo hospedado, chama seu callback createTransaction, conclui qualquer autenticação de cartão que o pagamento exija e resolve o resultado final.

const result = await elements.submit({
  createTransaction: async (tokenData) => {
    const response = await fetch("/api/pay", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({
        external_ref: "order_2001",
        amount: 2490,
        currency: "BRL",
        method: "credit_card",
        token: tokenData.token,
        installments: 1,
      }),
    });

    const payload = await response.json();
    return payload.data ?? payload;
  },
});

createTransaction recebe:

{
  "token": "pgct_token_from_browser",
  "brand": "visa",
  "last4": "4242",
  "exp_month": "12",
  "exp_year": "2029"
}

Envie apenas token ao seu back-end como credencial de pagamento. Trate brand, last4, exp_month e exp_year como metadados para exibição ou bookkeeping.

Resultado do submit

{
  "status": "pending",
  "transaction": {
    "id": "018f1f2e-7b43-7c9a-8d3e-1a2b3c4d5e70",
    "status": "pending"
  }
}

Valores possíveis de status incluem:

Status	Significado
Status da transaction	Quando nada mais é necessário, o SDK retorna o status da transaction vindo do seu back-end.
`completed`	Fallback quando a resposta do back-end não tem `status`.
`processing`	O pagamento ainda está sendo resolvido. Aguarde webhook ou reconciliação.
`requires_action`	Ainda há ação necessária e o tratamento automático está desabilitado para a sessão do Element.
`requires_reentry`	Retornado por `resume()` quando um pagamento com 3DS pré-cobrança precisa que o cartão seja reinserido após um reload. Monte um novo `CardElement` e chame `resume()` de novo com o mesmo `transactionId`.
`succeeded`	O pagamento foi aprovado.
`failed`	O pagamento falhou, ou a autenticação de cartão exigida não pôde ser concluída.
`refused`	A autenticação do cartão foi recusada.
`canceled`	Comprador fechou a janela de autenticação.
`timed_out`	A autenticação não finalizou dentro do timeout do SDK.
`error`	Falha de tokenização, criação de sessão, callback ou fluxo do SDK.

Não libere o pedido usando apenas o status do navegador. Use webhook ou reconciliação no servidor como fonte final de verdade.

3D Secure

elements.submit(...) conclui a autenticação do cartão para você quando o pagamento exige, usando o buyer e os products que o seu servidor já envia ao criar a transaction. Você não coleta nada a mais no navegador. Veja 3D Secure. Retorne o payload da transaction do seu back-end sem alterações. Se ele pedir alguma ação adicional, o SDK detecta e continua o fluxo. Se você já criou a transaction server-side e só precisa que o SDK conclua uma ação que ela reportou, repasse essa ação diretamente:

const result = await Pagou.handleNextAction(transaction.next_action);

Ou passe a transaction para uma instância de Elements:

const result = await elements.submit({
  transaction,
  createTransaction: async () => transaction,
});

Retomar após um reload

Se a página recarregar ou o comprador sair no meio do pagamento, retome a mesma transaction em vez de iniciar uma nova tentativa de checkout. resume() recria a sessão de Element a partir da sua chave pública, então funciona mesmo após um carregamento completo da página.

const result = await elements.resume({
  transactionId: "018f1f2e-7b43-7c9a-8d3e-1a2b3c4d5e70",
});

Opção	Obrigatório	Descrição
`transactionId`	Sim	Id da transaction a retomar.

resume() retorna o mesmo formato de resultado de submit(). Ele retoma uma ação pendente quando ainda houver uma, retorna o status terminal quando o pagamento já finalizou e retorna processing quando o desfecho ainda não chegou. Persista o id da transaction antes que o comprador possa sair da página, para tê-lo na volta.

Reinserção do cartão (auto-heal)

Um pagamento que aguardava autenticação de cartão (3DS pré-cobrança) estava vinculado à sessão de Element que capturou o cartão; um reload inicia uma nova sessão e o desafio original não pode mais rodar. resume() se auto-corrige por padrão — o element/SDK cuida de toda a recuperação, igual para checkout hospedado e integradores diretos. Sua única responsabilidade: manter um CardElement montado e chamar resume().

const card = elements.create("card");
card.mount("#card-element");

const result = await elements.resume({ transactionId }); // resultado terminal

Num desafio pré-cobrança de sessão obsoleta, resume() pede que o comprador reinsira o cartão no element montado, retokeniza sob a sessão atual, substitui o desafio obsoleto, roda o novo e resolve num status terminal. Nenhuma nova transaction é criada.

Opção	Obrigatória	Descrição
`manualReentry`	Não	Desativa o auto-heal. `resume()` retorna `status: "requires_reentry"` para você rodar sua própria UX de recoleta e chamar `resume()` de novo.
`reentryTimeoutMs`	Não	Somente auto-heal. Quanto tempo esperar o comprador reinserir o cartão. Padrão de 3 minutos.

Apenas o mesmo cartão pode substituir o pagamento — um cartão diferente é recusado. Sem card element montado, ou se o comprador não reinserir dentro do tempo limite, resume() resolve com um resultado terminal claro pedindo para iniciar uma nova tentativa. Nunca entra em loop nem trava.

Modo do token

Passe mode em submit para declarar a intenção da chamada e escolher o tipo de token gerado:

`mode`	Token	Quando usar
`payment` (padrão)	`pgct_` de uso único	Cobrança avulsa
`upsell`	`pgpm_` reutilizável	Compra inicial + upsell one-click
`subscription`	`pgct_` de uso único	Captura de cartão para iniciar uma subscription

// Fluxo de upsell — mesmo cartão cobrado duas vezes (inicial + upsell)
const result = await elements.submit({
  mode: "upsell",
  createTransaction: async (tokenData) => createPaymentWithToken(tokenData.token),
});

// Fluxo de subscription
const result = await elements.submit({
  mode: "subscription",
  createTransaction: async (tokenData) => createSubscriptionWithToken(tokenData.token),
});

Cleanup

Desmonte o campo de cartão ao sair da tela de checkout:

card.unmount();

Destrua a instância de Elements quando o fluxo de pagamento inteiro deixar de existir:

elements.destroy();

Regras de produção

Use pk_test_* apenas com Pagou.setEnvironment("sandbox").
Use pk_live_* com o ambiente padrão de produção.
Nunca envie dados brutos de cartão ao seu back-end.
Nunca registre tokens pgct_* ou pgpm_*, nem dados de cartão em logs.
Desabilite submits duplicados enquanto elements.submit(...) estiver em execução.
Persista o id da transaction para poder chamar resume(...) após um reload.
Retorne o payload da transaction do back-end sem remover id, status ou next_action.
Trate o status do navegador como provisório até webhook ou reconciliação confirmar o estado final do pagamento.

Comece com Payment Element

Construa o checkout de cartão

Lançamento e migração

Carregue o SDK

Inicialize Elements

Crie e monte o campo de cartão

Eventos do cartão

Envie um pagamento

Resultado do submit

3D Secure

Retomar após um reload

Reinserção do cartão (auto-heal)

Modo do token

Cleanup

Regras de produção

​Carregue o SDK

​Inicialize Elements

​Crie e monte o campo de cartão

​Eventos do cartão

​Envie um pagamento

​Resultado do submit

​3D Secure

​Retomar após um reload

​Reinserção do cartão (auto-heal)

​Modo do token

​Cleanup

​Regras de produção

Carregue o SDK

Inicialize Elements

Crie e monte o campo de cartão

Eventos do cartão

Envie um pagamento

Resultado do submit

3D Secure

Retomar após um reload

Reinserção do cartão (auto-heal)

Modo do token

Cleanup

Regras de produção