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

# O objeto Fields

Explore o objeto Fields para criar formulários de pagamento. Esta referência detalha os métodos fields.create(), field.mount() e o tratamento de eventos.

Depois de criar um campo com `localpayment.create()`, você pode usar os seguintes métodos no objeto retornado.

| Método | Descrição | Exemplo |
| - | - | - |
| `mount(selector)` | Monta o iframe do campo no contêiner DOM especificado. | `panField.mount('#card-number-container');` |
| `unmount()` | Remove o iframe do campo do DOM. | `panField.unmount();` |
| `clear()` | Limpa o valor atual do campo. | `panField.clear();` |
| `focus()` | Define o foco no campo. | `panField.focus();` |
| `blur()` | Desvia o foco do campo. | `panField.blur();` |
| `on(event, callback)` | Registra uma função de retorno de chamada para um evento específico neste campo. | `panField.on('change', (state) => { … });` |

### Tipos de Campo

Os seguintes tipos de campo estão disponíveis para criação usando o método `create()`.

| Tipo de campo | Parâmetro de `create()` | Descrição | Exemplo de saída |
| - | - | - | - |
| Número do cartão | `'pan'` | Insira o número da conta principal (PAN). Formata e espaça o número automaticamente. | `4111 1111 1111 1111` |
| Código de segurança | `'cvv'` | Insira o valor de verificação do cartão (CVV/CVC). | `123` |
| Data de validade | `'expiration'` | Campo para inserir a data de validade do cartão. Utiliza o formato MM-AAAA. | `12-2028` |

***

## Eventos

Escute eventos em uma instância de campo usando o método `.on()` para reagir a mudanças de estado.

### Evento `'change'`

Acionado quando o valor do campo ou o estado de validação é alterado.

O callback recebe: `state` (Object)

* `state.isEmpty` (`Boolean`): `true` se o campo não tiver valor.
* `state.isValid` (`Boolean`): `true` se o valor atual for válido.
* `state.isFocused` (`Boolean`): `true` se o campo estiver com foco no momento.
* `state.error` (`String` | `undefined`): Uma string descrevendo o erro de validação, se houver.

**Exemplo:**

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
panField.on('change', (state) => {
  if (state.isValid) {
    // Update UI to show valid state
    console.log('Card number is valid');
  } else if (state.error) {
    // Update UI to show error message
    console.error('Validation error:', state.error);
  }
});
```

### Evento `'tokenized'`

Acionado quando o valor do campo é tokenizado com sucesso pelo backend da Localpayment. Isso geralmente ocorre após a inserção de um valor válido e o campo perder o foco.

**Exemplo:**

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
panField.on('tokenized', (token) => {
  console.log('PAN tokenized with token:', token);
  // You can track that this field is ready for consolidation
});
```

### Evento `'error'`

Acionado quando ocorre um erro irrecuperável, como uma falha de tokenização.

O callback recebe: `error` (Object)

* `error.error` (`String`): Uma mensagem de erro genérica.
* `error.metadata` (`Object` | `undefined`): Metadados adicionais sobre o erro.

**Exemplo:**

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
panField.on('error', (error) => {
  console.error('An error occurred:', error.error);
  if (error.metadata) {
    console.error('Error details:', error.metadata);
  }
});

```

***

## Tratamento de erros

O SDK fornece erros por meio do evento `error` e de promises rejeitadas. Os cenários de erro comuns incluem:

* **Erros de rede**: `createSession()` falhará se não for possível fazer uma requisição de rede.
* **Credenciais inválidas**: `createSession()` falhará se o `clientCode` ou a `apiKey` estiver incorreto.
* **Erros de tokenização**: O \`error event será acionado se o valor de um campo não puder ser tokenizado (por exemplo, um número de cartão inválido que passa na validação básica, mas é rejeitado pelo processador).
* **Expiração da sessão**: as operações falharão se a sessão expirar. Você deve detectar esse problema e, normalmente, recriar a sessão.

**Exemplo de tratamento de erros abrangente:**

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// Handle field errors
panField.on('error', (error) => {
  showUserError(`Card number error: ${error.error}`);
});
// Handle session creation errors
try {
  await localpayment.createSession();
} catch (error) {
  console.error('Session creation failed. Please check your credentials.', error);
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.