Saltar al contenido principal
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:

Credenciales de API

Credenciales API válidas y token de acceso para la autenticación.

Configuración de la cuenta

Configuración adecuada de la cuenta para el país de destino y verificación de la empresa.

Lista blanca de IP

Incluye en la lista blanca las direcciones IP de tus servidores para el acceso a la API.

Endpoint del webhook

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.

Parámetros clave de la solicitud

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:
curl
Consulta todos los parámetros disponibles 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:

Campos de respuesta clave

Respuesta de error

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

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

curl

Paso 4: Hacer seguimiento del estado de las cuotas

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

Webhooks (recomendado)

Recibe notificaciones en tiempo real de cada pago de cuota y de los cambios de estado del plan.

Endpoint de la API de estado

Consulta el estado de las transacciones mediante programación. Útil para sondear o recuperar notificaciones de webhook perdidas.

Vista del Business Portal

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.
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.
Referencia completaConsulta todos los códigos de estado en nuestra documentación sobre el estado de las transacciones.

Paso 5: Gestionar el ciclo de vida de las cuotas

Flujo de pago en cuotas


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:

Reembolsar la transacción

Si es necesario, puedes reembolsar el pago al cliente. Consulta la documentación para obtener más detalles.

Revisar los detalles de la transacción

Puedes recuperar información sobre las transacciones utilizando la API de Localpayment para obtener información detallada.

Última modificación el 20 de noviembre de 2026