Aparência e eventos

Use esta página para estilizar o campo hospedado e reagir a mudanças de estado sem ser dono dos dados brutos do cartão.

Exemplo de aparência

const card = elements.create("card", {
  theme: "default",
  style: {
    base: {
      color: "#111827",
      fontFamily: "Inter, system-ui, sans-serif",
      fontSize: "16px",
      borderRadius: "8px",
      backgroundColor: "#ffffff",
    },
    focus: {
      borderColor: "#2563eb",
    },
    invalid: {
      color: "#dc2626",
    },
    placeholder: {
      color: "#9ca3af",
    },
  },
});

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

Os temas suportados são default, night e flat. Use o objeto style para cores e tipografia da marca em vez de colocar inputs brutos de cartão no seu próprio DOM.

Padrão de eventos suportados

let cardState = {
  valid: false,
  brand: null,
  errors: {},
};

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

card.on("change", (event) => {
  cardState = event;

  submitButton.disabled = !event.valid;
  brandEl.textContent = event.brand ? event.brand.toUpperCase() : "";
  messageEl.textContent = Object.values(event.errors ?? {})[0] ?? "";
});

card.on("error", (event) => {
  messageEl.textContent = event.message ?? "Unable to initialize the card field.";
});

Chame card.off("change", handler) no unmount do componente se o seu framework mantiver a mesma instância do cartão entre renders.

Payloads dos eventos

ready dispara quando o iframe hospedado carregou. Isso não significa que os dados do cartão são válidos. change dispara sempre que a entrada do cartão muda:

{
  "valid": false,
  "brand": "visa",
  "errors": {
    "number": "Card number is invalid"
  }
}

Quando a bandeira não for identificada, brand será null. Quando o estado atual for válido, errors estará vazio e valid será true. error dispara quando o campo hospedado falha ao carregar ou recebe uma falha de pagamento fora de uma tentativa ativa de tokenização:

{
  "code": "mount_timeout_no_load",
  "message": "Unable to initialize the card field."
}

Códigos de erro conhecidos incluem card_error, iframe_load_failed, mount_timeout_no_load e mount_timeout_no_handshake.

Estados inválidos

Use change.valid como a única trava de submit. Não deduza validade apenas pela bandeira do cartão.

card.on("change", ({ valid, brand, errors }) => {
  submitButton.disabled = !valid;
  cardBrandEl.textContent = brand ?? "";

  const firstError = Object.values(errors ?? {})[0];
  errorEl.textContent = firstError ?? "";
});

O objeto errors é indexado pelo campo hospedado que precisa de atenção. As chaves exatas são controladas pelo campo hospedado, então renderize as mensagens em vez de fixar todas as chaves possíveis. Como corrigir: confirme a versão do script, o ambiente e a publicKey. Handlers de evento devem atualizar apenas o estado da interface; o estado final do pagamento continua vindo do back-end e dos webhooks.

Comece com Payment Element

Construa o checkout de cartão

Lançamento e migração

Exemplo de aparência

Padrão de eventos suportados

Payloads dos eventos

Estados inválidos

​Exemplo de aparência

​Padrão de eventos suportados

​Payloads dos eventos

​Estados inválidos

Exemplo de aparência

Padrão de eventos suportados

Payloads dos eventos

Estados inválidos