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: Crea una suscripción
Para crear una nueva suscripción, deberás enviar una solicitudPOST al endpoint Crear una suscripción.
Parámetros clave de la solicitud
La solicitud requiere varios parámetros clave, según si estás creando una suscripción de plan fijo o una suscripción personalizada:Tipos de suscripción
- Suscripción de plan fijo: Úsala cuando tengas planes de suscripción predefinidos creados mediante el endpoint Crear un plan de suscripción.
- Suscripción personalizada: Úsala para escenarios de facturación variable en los que cada pago puede diferir en importe o fecha.
Códigos de métodos de pago
En todos los países,paymentMethod.code identifica el país, la marca de la tarjeta y el producto (crédito o débito), por lo que debes enviar el código que corresponda a la tarjeta y al country de la suscripción. En Perú, donde las tarjetas se aceptan en dos monedas, el código también debe coincidir con currency: por ejemplo, una tarjeta de crédito Visa usa 6000 con PEN y 6004 con USD. Consulta Códigos de métodos de pago con tarjeta para ver los códigos de todos los países.
Ejemplo de solicitud
A continuación se muestra un ejemplo que utilizacurl:
curl
Paso 2: Gestionar la respuesta
Respuesta exitosa
Una respuesta exitosa incluye información detallada de la suscripción e identificadores:Campos de respuesta clave
Respuesta de error
Cuando una solicitud falla, recibirás información detallada sobre el error:Paso 3: Seguimiento del estado de la transacción
Tras crear una suscripción, supervisa su ciclo de vida mediante estos métodos:Webhooks (recomendado)
Recibe notificaciones en tiempo real cuando cambie el estado de la transacción. Más eficiente para entornos de producción.
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 el seguimiento de transacciones. Ideal para la supervisión manual y el análisis detallado de las transacciones.
Códigos de estado comunes
La API de Localpayment proporciona varios códigos de estado para indicar el estado de la suscripción.Referencia completaConsulta todos los códigos de estado en nuestra documentación sobre el estado de las transacciones.
Probando tu integración
Escenarios de prueba
Verifica que tu integración gestione estos escenarios:- Creación exitosa de la suscripción: Flujo estándar de suscripción con una tarjeta válida.
- Suscripción de plan fijo: Suscripción con un plan predefinido.
- Suscripción personalizada: Suscripción con parámetros de facturación personalizados.
- Errores de validación: Tarjeta no válida, faltan campos obligatorios
- Actualizaciones de estado: Gestión de webhooks y sondeo de estado
Próximos pasos
Una vez creada una suscripción, es posible que debas realizar acciones adicionales, como las siguientes:Actualizar suscripción
Modifica los detalles de una suscripción existente, incluido el importe de facturación, la frecuencia o
la información del cliente.
Cancelar suscripción
Finaliza suscripciones activas conservando el historial de transacciones y
los registros de facturación.
Gestionar webhooks de suscripción
Configura webhooks para recibir notificaciones en tiempo real sobre los eventos de la suscripción
y los cambios en el estado de los pagos.

