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 solicitudPOST 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 utilizacurl:
curl
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:- Cuota exitosa: Flujo completo de pago en cuotas
- Varias opciones de plan: Presenta diferentes plazos de cuotas (2, 3, 6 meses)
- Caducidad del token: Gestiona un installmentsToken caducado (ventana de 10 minutos)
- 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.

