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

# Cuotas

Atrae a más clientes permitiéndoles dividir sus compras en pagos mensuales. Aprende a implementar y gestionar fácilmente planes de cuotas para aumentar la conversión y el valor medio de los pedidos.

Localpayment permite a los comerciantes ofrecer planes de cuotas, de modo que los clientes puedan dividir sus compras en varios pagos mensuales. Esta guía describe el proceso para crear planes de cuotas a través de la API de Localpayment, detallando los parámetros obligatorios, el manejo de las respuestas y la gestión de todo el ciclo de vida de las cuotas.

## Antes de comenzar

Asegúrate de tener:

> [card] [Credenciales de API](https://docs.localpayment.com/es/docs/api-keys-and-environments.md)
>
> Credenciales API válidas y token de acceso para la autenticación.

> [card] [Configuración de la cuenta](https://docs.localpayment.com/es/docs/make-your-first-test-payment.md)
>
> Configuración adecuada de la cuenta para el país de destino y verificación de la empresa.

> [card] [Lista blanca de IP](https://docs.localpayment.com/es/docs/dashboard-whitelist-your-ips.md)
>
> Incluye en la lista blanca las direcciones IP de tus servidores para el acceso a la API.

> [card] [Endpoint del webhook](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Configura una URL de webhook para recibir notificaciones de pago.

***

## Paso 1: Crear la cotización del plan de cuotas

Antes de procesar un pago en cuotas, debes generar una cotización del plan de cuotas para presentar las opciones de pago al cliente.

Para cotizar un plan de cuotas, deberás enviar una solicitud `POST` al endpoint [Generar cotización de plan de pagos](https://docs.localpayment.com/es/reference/installments.md).

### Parámetros clave de la solicitud

| Objeto | Descripción | Requerido |
| - | - | - |
| `paymentMethod.code` | Código del método de pago. Solo se admiten los métodos `CreditCard`. | ✅ |
| `amount` | Importe total de la transacción | ✅ |
| `currency` | Código de moneda de la transacción | ✅ |
| `country` | País donde se procesará el pago | ✅ |

> [!NOTE]
>
> Las cuotas solo están disponibles en moneda local. En Perú, puedes ofrecer cuotas en pagos en PEN, pero no en pagos en USD.

### Ejemplo de solicitud

A continuación se muestra un ejemplo que utiliza `curl`:

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
     --url https://api.stage.localpayment.com/api/installments-plans \
     --header 'Authorization: Bearer <your_access_token>' \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --data '
{
  "paymentMethod": {
    "code": "1600"
  },
  "country": "MEX",
  "currency": "MXN",
  "amount": 1000,
  "accountNumber": "{{accountNumber}}"
}
'
```

Consulta todos los [parámetros disponibles](https://docs.localpayment.com/es/reference/payins.md) en la solicitud.

***

## Paso 2: Gestionar la respuesta de la cotización

### Respuesta exitosa

Una cotización de cuotas exitosa incluye información detallada del plan de pago:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "installmentsToken": "bc1a1923-fadc-427b-b014-e43eb4462e81",
  "creationDate": "2025-01-29T23:53:52.7150456+00:00",
  "expirationDate": "2025-01-30T00:03:52.71509+00:00",
  "currency": "MXN",
  "amount": 1000,
  "installments": [
        {
            "installments": 3,
            "installmentAmount": 448.98,
            "totalPaymentAmount": 1346.95,
            "financingFee": 346.95
        },
        {
            "installments": 6,
            "installmentAmount": 275.68, 
            "totalPaymentAmount": 1654.12, 
            "financingFee": 654.12
        }
    ]
}
```

### Campos de respuesta clave

| Parámetro | Descripción | Caso de uso |
| - | - | - |
| `installmentsToken` | Token único que identifica la cotización de cuotas | Necesario para procesar el plan de cuotas seleccionado. |
| `creationDate` | Marca de tiempo de cuando se generó la cotización. | Seguir la vigencia y el momento de la cotización. |
| `expirationDate` | Marca de tiempo de cuando vence la cotización. | Asegurar que el cliente seleccione un plan antes del vencimiento. |
| `currency` | Moneda de la transacción. | Mostrar al cliente el símbolo de moneda correcto. |
| `installments` | Arreglo de opciones de cuotas disponibles. | Presentar al cliente varios planes de pago. |
| `installments.installments` | Número de pagos mensuales. | Mostrar la duración del plazo de pago. |
| `installments.installmentAmount` | Importe del pago mensual. | Mostrar al cliente el costo mensual. |
| `installments.totalPaymentAmount` | Importe total, incluidas las comisiones. | Mostrar el costo total del financiamiento. |
| `installments.financingFee` | Costo total del financiamiento. | Mostrar por separado las comisiones y los intereses. |

### Respuesta de error

Cuando falla la generación de la cotización de cuotas:

```json theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
{
  "status": {
    "code": "300",
    "detail": "Instalment Payment Plan is only for types of Credit Card methods"
  }
}
```

### Buenas prácticas para la presentación de cuotas

* Muestra todos los costos con claridad (comisiones de financiamiento, importe total)
* Muestra de forma destacada los importes de los pagos mensuales
* Incluye una comparación entre las diferentes opciones de cuotas
* Explica el proceso de pago automático de las cuotas futuras
* Incluye la información de atención al cliente
* Gestiona correctamente la caducidad del token (**ventana de 10 minutos**)

***

## Paso 3: Procesar el pago en cuotas

Una vez que el cliente selecciona un plan de cuotas, procesa el pago utilizando el token de cuotas.

### Ejemplo de solicitud

```bash curl theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
curl --request POST \
  --url https://api.stage.localpayment.com/api/payin/ \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <your_access_token>' \
  --header 'Content-Type: application/json' \
  --data '{
    "paymentMethod": {
        "type": "CreditCard",
        "code": "1600",
        "flow": "DIRECT"
    },
    "externalId": "dffbd2a6-6e65-469b-8bbe-dac269882220",
    "country": "MEX",
    "currency": "MXN",
    "amount": 1000,
    "accountNumber": "{{accountNumber}}",
    "conceptCode": "0001",
    "merchant": {
        "type": "COMPANY",
        "name": "Company",
        "document": {
            "type": "RFC",
            "id": "XXX840510XX1"
        },
        "email": "mail@company.com"
    },
    "payer": {
        "type": "INDIVIDUAL",
        "name": "John",
        "lastname": "Doe",
        "document": {
            "type": "RFC",
            "id": "YYY180222YY6"
        },
        "email": "john.doe@example.com"
    },
    "card": {
        "number": "4000000000000002",
        "cvv": "123",
        "expirationMonth": "12",
        "expirationYear": "2029",
        "installments": 3,
        "installmentsToken": "bc1a1923-fadc-427b-b014-e43eb4462e81"
    }
}'
```

***

## Paso 4: Hacer seguimiento del estado de las cuotas

Supervisa el progreso del plan de cuotas mediante estos métodos:

> [card] [Webhooks (recomendado)](https://docs.localpayment.com/es/docs/webhooks.md)
>
> Recibe notificaciones en tiempo real de cada pago de cuota y de los cambios de estado del plan.

> [card] [Endpoint de la API de estado](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Consulta el estado de las transacciones mediante programación. Útil para sondear o recuperar notificaciones de webhook perdidas.

> [card] [Vista del Business Portal](https://docs.localpayment.com/es/docs/dashboard-overview.md)
>
> Interfaz visual para supervisar los planes de cuotas y el rendimiento de los pagos.

### Códigos de estado comunes

La API de Localpayment ofrece diversos códigos de estado para los planes de cuotas y los pagos.

| Código | Estado | Descripción |
| :- | :- | :- |
| `103` | `APPROVED` | El payin se confirmó, pero aún no se ha abonado. |
| `200` | `Completed` | El payin se ha completado. |
| `811` | `Rejected` | La cantidad solicitada es mayor o menor que los valores máximos/mínimos permitidos. |

> [!NOTE]
>
> **APPROVED no es el estado final.** Significa que el pago con tarjeta se confirmó, pero los fondos aún no se abonaron a tu saldo. Puedes ver el pago, pero no puedes retirar los fondos hasta que el estado cambie a Completed. Esto suele tardar de 1 a 2 días, según el proveedor.

> [!NOTE]
>
> **Referencia completa**
>
> Consulta todos los códigos de estado en nuestra [documentación sobre el estado de las transacciones](https://docs.localpayment.com/es/reference/transaction-status-error-codes).

***

## Paso 5: Gestionar el ciclo de vida de las cuotas

### Flujo de pago en cuotas

```mermaid theme={"theme":{"light":"github-light-high-contrast","dark":"github-dark-high-contrast"}}
%%{init: {'theme': 'base', 'themeVariables': {'primaryColor': '#31467c', 'primaryTextColor': '#ffffff', 'primaryBorderColor': '#0c1a29', 'actorBkg': '#31467c', 'actorBorder': '#0c1a29', 'actorTextColor': '#ffffff', 'actorLineColor': '#0c1a29', 'signalColor': '#0c1a29', 'signalTextColor': '#0c1a29', 'labelBoxBkgColor': '#31467c', 'labelBoxBorderColor': '#0c1a29', 'labelTextColor': '#ffffff', 'loopTextColor': '#0c1a29', 'noteBkgColor': '#ffffff', 'noteBorderColor': '#31467c', 'noteTextColor': '#0c1a29'}}}%%
sequenceDiagram
    participant C as Cliente
    participant M as Comercio
    participant LP as Localpayment
    participant B as Banco
    
    C->>M: Iniciar el pago con opción de cuotas
    M->>LP: Solicitar cotización de cuotas
    LP->>M: Devolver installmentsToken y opciones
    M->>C: Presentar los planes de cuotas
    C->>M: Seleccionar el plan preferido
    M->>LP: Procesar el pago con installmentsToken
    LP->>B: Autorizar la primera cuota
    B->>LP: Autorización confirmada
    LP->>M: Confirmación del pago
    M->>C: Mostrar el resultado del pago (aprobado/rechazado)
    Note over C: El cliente recibe el estado de la transacción y los detalles del plan de pago
    Note over LP: Las cuotas mensuales se procesan automáticamente
    LP->>M: Webhook por cada cuota
```

***

## Probando tu integración

### Escenarios de prueba

Verifica que tu integración gestione estos escenarios:

1. **Cuota exitosa**: Flujo completo de pago en cuotas
2. **Varias opciones de plan**: Presenta diferentes plazos de cuotas (2, 3, 6 meses)
3. **Caducidad del token**: Gestiona un installmentsToken caducado (ventana de 10 minutos)
4. **Actualizaciones de estado**: Gestión de webhooks y sondeo de estado.

***

## Próximos pasos

Tras implementar las cuotas, ten en cuenta estas funcionalidades adicionales:

> [card] [Reembolsar la transacción](https://docs.localpayment.com/es/docs/refund-card-payment)
>
> Si es necesario, puedes reembolsar el pago al cliente. Consulta la documentación para obtener más detalles.

> [card] [Revisar los detalles de la transacción](https://docs.localpayment.com/es/reference/get-transaction-status.md)
>
> Puedes recuperar información sobre las transacciones utilizando la API de Localpayment para obtener información detallada.


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