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

# Guia de Integração de Campos Inteligentes

Este guia fornece um processo detalhado, passo a passo, para integrar os Campos Inteligentes ao seu sistema de pagamento. Ao final, você poderá coletar informações de pagamento com segurança diretamente em seu site, enquanto a Localpayment gerencia os dados confidenciais.

## Pré-requisitos

Certifique-se de ter estes componentes essenciais à mão:

> [card] [Chaves de API](https://docs.localpayment.com/pt-br/docs/dashboard-smart-fields-api-keys.md)
>
> Obtenha suas chaves de autenticação no ambiente de **Stage** (teste) ou de **Produção**.

> [card] [Código do cliente](https://docs.localpayment.com/pt-br/docs/dashboard-clients-information)
>
> Seu identificador exclusivo de comerciante, encontrado no Business Portal da Localpayment.

> [card] [Configuração do backend](https://docs.localpayment.com/pt-br/docs/payins-overview.md)
>
> Um endpoint do servidor pronto para receber tokens de pagamento e processar transações.

***

## Etapas de integração

### Inclua o SDK de Campos Inteligentes

Escolha o ambiente apropriado para sua integração:

> [tab] Stage (Testes)
>
> Utilize esta ferramenta para desenvolvimento e testes com pagamentos simulados:
>
> ```html theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> <script src="https://sdk.stage.localpayment.com/localpayment-sdk.min.js"></script>
> ```
>
> > [!NOTE]
> >
> > **Dica**\\
> >
> > Sempre teste sua integração minuciosamente no ambiente de teste antes de entrar em produção.

> [tab] Produção (Ao Vivo)
>
> Utilize isso em seu site ativo para processar pagamentos reais:
>
> ```html theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
> <script src="https://sdk.localpayment.com/localpayment-sdk.min.js"></script>
> ```
>
> > [!WARNING]
> >
> > **Importante**\\
> >
> > Só passe para produção após testes completos no ambiente de teste.

### Inicialize o SDK

Inicialize o SDK com suas credenciais assim que o script for carregado:

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
const localpayment = LP({
    clientCode: 'your_client_code',  // Replace with your actual client code
    apiKey: 'your_api_key'           // Replace with your actual API key
});
```

**Parâmetros de configuração:**

| Parâmetro | Tipo | Obrigatório | Descrição |
| - | - | - | - |
| `clientCode` | string | ✅ | Seu identificador de comerciante exclusivo da Localpayment |
| `apiKey` | string | ✅ | Sua chave de API secreta para autenticação |

### Criar uma sessão segura

Estabeleça uma conexão segura com os servidores da Localpayment:

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
try {
    await localpayment.createSession();
    console.log('Session created successfully');
} catch (error) {
    console.error('Failed to create session:', error);
    // Handle session creation error
}
```

> [!NOTE]
>
> **Nota de segurança**
>
> A sessão estabelece canais de comunicação criptografados para todos os dados de pagamento.

### Configurar Formulário de Pagamento

Crie a estrutura HTML para o seu formulário de pagamento:

```html theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
<form id="payment-form" class="payment-form">
    <!-- Card Number Field -->
    <div class="form-group">
        <label for="pan-container">Card Number *</label>
        <div id="pan-container" class="field-container"></div>
        <div class="error-message" id="pan-error" role="alert"></div>
    </div>

    <!-- CVV Field -->
    <div class="form-group">
        <label for="cvv-container">Security Code *</label>
        <div id="cvv-container" class="field-container"></div>
        <div class="error-message" id="cvv-error" role="alert"></div>
    </div>

    <!-- Expiration Field -->
    <div class="form-group">
        <label for="expiration-container">Expiration Date *</label>
        <div id="expiration-container" class="field-container"></div>
        <div class="error-message" id="expiration-error" role="alert"></div>
    </div>

    <!-- Cardholder Name -->
    <div class="form-group">
        <label for="cardholder-name">Cardholder Name *</label>
        <input type="text" id="cardholder-name" name="cardholderName" 
               placeholder="John Doe" required>
    </div>

    <button type="submit" id="submit-payment" disabled>
        Process Payment
    </button>
</form>
```

### Criar e configurar campos de pagamento

Inicialize os campos de pagamento seguros e integre-os ao seu formulário:

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// Create individual payment fields
const panField = localpayment.create('pan');        // Card number
const cvvField = localpayment.create('cvv');        // Security code  
const expirationField = localpayment.create('expiration'); // Expiry date

// Mount fields to their respective containers
panField.mount('#pan-container');
cvvField.mount('#cvv-container');
expirationField.mount('#expiration-container');
```

Use o método `mount()` para renderizar o iframe seguro dentro do contêiner especificado. Passe uma string de seletor CSS que identifique o elemento DOM de destino (por exemplo, `#pan-container`).

**Tipos e características dos campos:**

| Tipo de campo | Propósito | Recursos de validação |
| - | - | - |
| `pan` | Número do cartão (PAN) | Algoritmo de Luhn, detecção de marca, formatação |
| `cvv` | Código de segurança | Validação de comprimento (3 a 4 dígitos), somente numérico |
| `expiration` | Data de validade | Formato MM/AA, validação de data futura |

### Lidar com eventos de campo e validação

Ouça os eventos de cada campo para atualizar sua interface de usuário e acompanhar o status de validação:

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
// Example: Listen for changes on the card number field
panField.on('change', (state) => {
    // state contains: isValid, isEmpty, isFocused, error
    if (state.isValid) {
        // Field is valid, update UI accordingly
    } else if (state.error) {
        // Show error message to user
        console.error(state.error);
    }
});
```

### Processar Submissão de Pagamento

Recupere os dados da sessão e o ID da sessão:

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
const sessionData = localpayment.getSessionData(); // Contains sessionId, accessToken, clientCode.
console.log(sessionData.sessionId);
```

### Consolidar sessão e obter token

Crie uma requisição `POST` para o endpoint Consolidate, enviando o `sessionId` e os dados do titular do cartão:

```javascript theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
const response = await fetch('https://tokenization.api.stage.localpayment.com/api/tokenization/consolidate', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${accessToken}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    clientCode: 'your_client_code',
    sessionId: sessionData.sessionId,
    CardholderName: 'John Doe'
  })
});

const consolidationResult = await response.json();
console.log(consolidationResult);
```

> [!NOTE]
>
> **Ambientes:**
>
> * **Stage**: [https://tokenization.api.stage.localpayment.com/api/tokenization/consolidate](https://tokenization.api.stage.localpayment.com/api/tokenization/consolidate)
> * **Produção**: [https://tokenization.api.localpayment.com/api/tokenization/consolidate](https://tokenization.api.localpayment.com/api/tokenization/consolidate)

**Resposta esperada da consolidação:**

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
    "token": "lnZB3Rq1sbCB9sZnxgqtxbcPUR49G3I1tl%2BBsbt2vaM%3D",
    "bin": "424242",
    "brand": "VISA", 
    "country": "GB",
    "name": "John Doe",
    "last4": "4242",
    "expirationYear": 2029,
    "expirationMonth": 11
}
```

### Processar Pagamento

Crie um [novo Payin](https://docs.localpayment.com/pt-br/docs/payins-overview.md) e use o parâmetro token em vez das informações do titular do cartão. O token representa o método de pagamento de forma segura, sem expor dados confidenciais.

***

## Recursos e próximos passos

Maximize o sucesso da sua integração com estes recursos essenciais.

> [card] [Integração de Webhook](https://docs.localpayment.com/pt-br/docs/webhooks.md)
>
> Configure notificações em tempo real para atualizações do status das transações.

> [card] [Relatórios do Business Portal](https://docs.localpayment.com/pt-br/docs/balance-report.md)
>
> Acesse análises detalhadas, ferramentas de geração de relatórios e recursos de conciliação.

> [card] [Monitoramento de transações](https://docs.localpayment.com/pt-br/reference/transaction-status-error-codes)
>
> Aprenda a consultar o status das transações e a implementar um rastreamento abrangente.

> [card] [Referência da API](https://docs.localpayment.com/pt-br/reference/exchange-bulk.md)
>
> Documentação completa dos endpoints com exemplos interativos.

> [!NOTE]
>
> **Dica profissional**
>
> Sempre teste seu fluxo de trabalho em nosso ambiente de sandbox antes de implantá-lo em produção. Isso garante que o tratamento de erros, o processamento de webhooks e o rastreamento de status funcionem corretamente em todos os cenários.

***

> [!NOTE]
>
> **Precisa de ajuda?**
>
> Entre em contato com nossa [equipe de suporte](mailto:support@localpayment.com) caso encontre algum problema ou precise de ajuda com a integração.


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