Saltar al contenido principal
Localpayment permite a los comerciantes configurar suscripciones de pago recurrente con tarjetas de crédito y débito, con soporte tanto para planes fijos como para escenarios de facturación personalizados en varios países. Esta guía describe el proceso para crear una suscripción mediante la API de Localpayment, detallando los parámetros requeridos, el manejo de las respuestas y la interpretación de los códigos de estado.

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 solicitud POST 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 utiliza curl:
curl
Consulta todos los parámetros disponibles en la solicitud.

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:
  1. Creación exitosa de la suscripción: Flujo estándar de suscripción con una tarjeta válida.
  2. Suscripción de plan fijo: Suscripción con un plan predefinido.
  3. Suscripción personalizada: Suscripción con parámetros de facturación personalizados.
  4. Errores de validación: Tarjeta no válida, faltan campos obligatorios
  5. 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.
Última modificación el 10 de noviembre de 2026