> ## Documentation Index
> Fetch the complete documentation index at: https://developer.pagou.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Aparência e eventos

> Personalize o campo de cartão do Payment Element e reaja ao ciclo de vida dele com os eventos suportados.

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

```js theme={null}
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

```js theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```js theme={null}
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.