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

# Guía de integración de Smart Fields

Esta guía ofrece un proceso detallado paso a paso para integrar Smart Fields en tu proceso de pago. Al finalizar, podrás recopilar de forma segura los datos de pago directamente en tu sitio web, mientras que Localpayment se encarga de la información confidencial.

## Requisitos previos

Asegúrate de tener listos estos componentes esenciales:

> [card] [Claves API](https://docs.localpayment.com/es/docs/dashboard-smart-fields-api-keys.md)
>
> Obtén tus claves de autenticación desde el entorno de pruebas (**Stage**) o el de **producción**.

> [card] [Código de cliente](https://docs.localpayment.com/es/docs/dashboard-clients-information)
>
> Tu identificador único de comerciante que se encuentra en el Business Portal de Localpayment.

> [card] [Configuración del backend](https://docs.localpayment.com/es/docs/payins-overview.md)
>
> Un endpoint de servidor listo para recibir tokens de pago y procesar transacciones.

***

## Pasos de integración

### Incluir el SDK de Smart Fields

Elige el entorno adecuado para tu integración:

> [tab] Stage (Pruebas)
>
> Utiliza esto para el desarrollo y las pruebas con pagos 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]
> >
> > **Consejo**\\
> >
> > Siempre prueba tu integración a fondo en el entorno de pruebas antes de tu lanzamiento oficial.

> [tab] Producción (en vivo)
>
> Utiliza esto para tu sitio web en funcionamiento para procesar pagos reales:
>
> ```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**\\
> >
> > Solo cambia a producción después de realizar pruebas completas en el entorno de pruebas.

### Inicializar el SDK

Inicializa el SDK con tus credenciales una vez que se cargue el script:

```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 configuración:**

| Parámetro | Tipo | Requerido | Descripción |
| - | - | - | - |
| `clientCode` | string | ✅ | Tu identificador único de comerciante de Localpayment |
| `apiKey` | string | ✅ | Tu clave API secreta para autenticación |

### Crear una sesión segura

Establece una conexión segura con los servidores de 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 seguridad**
>
> La sesión establece canales de comunicación cifrados para todos los datos de pago.

### Configurar formulario de pago

Crea la estructura HTML para tu formulario de pago:

```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>
```

### Crear y montar campos de pago

Inicializa los campos de pago seguro e incorpóralos a tu formulario:

```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');
```

Utiliza el método `mount()` para renderizar el iframe seguro dentro del contenedor especificado. Pasa una cadena de selector CSS que identifique el elemento DOM de destino (por ejemplo, `#pan-container`).

**Tipos y características de los campos:**

| Tipo de campo | Objetivo | Características de validación |
| - | - | - |
| `pan` | Número de tarjeta (PAN) | Algoritmo de Luhn, detección de marca, formato |
| `cvv` | Código de seguridad | Validación de longitud (3-4 dígitos), solo numérico |
| `expiration` | Fecha de caducidad | Formato MM/AA, validación de fecha futura |

### Gestionar eventos de campo y validación

Escucha los eventos de cada campo para actualizar tu interfaz de usuario y realizar un seguimiento de su estado de validación:

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

### Procesar el envío del pago

Recuperar los datos de la sesión y el ID de sesión:

```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 sesión y obtener token

Crea una solicitud `POST` al endpoint Consolidate, enviando el `sessionId` y los datos del titular de la tarjeta:

```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]
>
> **Entornos:**
>
> * **Stage**: [https://tokenization.api.stage.localpayment.com/api/tokenization/consolidate](https://tokenization.api.stage.localpayment.com/api/tokenization/consolidate)
> * **Producción**: [https://tokenization.api.localpayment.com/api/tokenization/consolidate](https://tokenization.api.localpayment.com/api/tokenization/consolidate)

**Respuesta de consolidación prevista:**

```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
}
```

### Procesar el pago

Crea un [nuevo Payin](https://docs.localpayment.com/es/docs/payins-overview.md) y usa el parámetro token en lugar de la información del titular de la tarjeta. El token representa de forma segura el método de pago sin exponer datos confidenciales.

***

## Recursos y próximos pasos

Maximiza el éxito de tu integración con estos recursos esenciales.

> [card] [Integración de webhooks](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Configura notificaciones en tiempo real para las actualizaciones del estado de las transacciones.

> [card] [Portal de informes empresariales](https://docs.localpayment.com/es/docs/balance-report.md)
>
> Accede a análisis detallados, herramientas de generación de informes y funciones de conciliación.

> [card] [Monitoreo de transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes)
>
> Aprende a consultar el estado de las transacciones e implementar un seguimiento exhaustivo.

> [card] [Referencia de la API](https://docs.localpayment.com/es/reference/exchange-bulk.md)
>
> Documentación completa del endpoint con ejemplos interactivos.

> [!NOTE]
>
> **Consejo profesional**
>
> Siempre prueba tu flujo de trabajo en nuestro entorno de pruebas antes de implementarlo en producción. Esto garantiza que el manejo de errores, el procesamiento de webhooks y el seguimiento del estado funcionen correctamente en todos los escenarios.

***

> [!NOTE]
>
> **¿Necesitas ayuda?**
>
> Ponte en contacto con nuestro [equipo de soporte](mailto:support@localpayment.com) si experimentas algún problema o necesitas ayuda con la integración.


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