Referência do SDK v3 - Pagou Developer Docs

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 interno.

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 e continua o 3DS quando a resposta da transaction inclui next_action.

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": "tr_2001",
    "status": "pending"
  }
}

Valores possíveis de status incluem:

Status	Significado
Status da transaction	Se não houver `next_action`, o SDK retorna o status da transaction vindo do seu back-end.
`completed`	Fallback quando a resposta do back-end não tem `status`.
`requires_action`	Existe `next_action` e o modal automático de 3DS está desabilitado para a sessão do Element.
`succeeded`	Challenge 3DS concluído com sucesso.
`failed`	Challenge 3DS ou pagamento falhou.
`canceled`	Comprador fechou o modal de 3DS.
`timed_out`	Challenge 3DS 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

Quando seu back-end retorna uma transaction com next_action, o SDK pode abrir o modal de challenge automaticamente.

{
  "id": "tr_2001",
  "status": "three_ds_required",
  "next_action": {
    "type": "three_ds_challenge",
    "challenge_session_id": "3ds_1001",
    "client_secret": "sec_1001",
    "expires_at": "2026-03-16T14:20:00.000Z"
  }
}

Se você já criou a transaction server-side e só precisa continuar uma ação existente, chame:

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,
});

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 pgct_*, pgpm_*, client_secret ou dados de cartão em logs.
Desabilite submits duplicados enquanto elements.submit(...) estiver em execução.
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.

​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

​Modo do token

​Cleanup

​Regras de produção