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: Solicitar una preautorización
Para iniciar una preautorización, deberás enviar una solicitudPOST al endpoint Crear Payin y establecer el encabezado x-capture en true.
Parámetros clave de la solicitud
La solicitud requiere varios objetos clave:
El valor de
paymentMethod.code depende del país, de la marca de la tarjeta y del producto (crédito o débito). En Perú también depende de la moneda. Consulta los códigos de métodos de pago con tarjeta para ver la lista completa.
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 transacción e identificadores de seguimiento.Campos de respuesta clave
Respuesta de error
Cuando una solicitud falla, recibirás información detallada sobre el error:Paso 3: Capturar los fondos
Tras preautorizar una transacción, debes capturar los fondos para debitar la cuenta del cliente. Asegúrate de que la solicitud de captura sea por el importe total de la preautorización. La retención de fondos por preautorización caducará a los 7 días. Si no capturas los fondos dentro de este plazo, se devolverán automáticamente a la tarjeta del cliente. Para capturar una preautorización, envía una solicitudPATCH al endpoint Capturar Payin autorizado.
Ejemplo de solicitud
curl
Respuesta exitosa
Liberar fondos no utilizados
Para garantizar una experiencia positiva para el cliente, se recomienda liberar los fondos preautorizados que no se vayan a utilizar. Al iniciar la liberación mediante una solicitud API, puedes evitar que tus clientes tengan que esperar los 7 días completos para la liberación automática. Para liberar los fondos no utilizados, envía una solicitudPATCH al endpoint Cancelar autorización de Payin.
Ejemplo de solicitud
curl
Respuesta exitosa
Paso 4: Seguimiento del estado de la transacción
Tras iniciar un pago preautorizado, supervisa su progreso 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 progreso y el resultado del pago en la respuesta.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.
Para consultar la referencia completa de códigos de estado, consulta la documentación sobre el estado de las transacciones.
Probando tu integración
Escenarios de prueba
Verifica que tu integración gestione estos escenarios:- Transacción exitosa: Flujo de pago estándar
- Errores de validación: Cuenta bancaria no válida, campos faltantes
- Retrasos en el procesamiento: Transacciones que requieren tiempo para procesarse.
- Transacciones fallidas: Fondos insuficientes, beneficiarios bloqueados
- Actualizaciones de estado: Gestión de webhooks y sondeo de estado
Próximos pasos
Una vez procesada la preautorización, es posible que debas realizar acciones adicionales, como las siguientes:Reembolsar la transacción
Si es necesario, puedes reembolsar el pago al cliente. Consulta la documentación sobre reembolsos para obtener más información.
Gestionar las devoluciones de cargo
En caso de disputa, es posible que debas gestionar las devoluciones de cargo. Consulta la documentación sobre devoluciones de cargo para obtener información sobre este proceso.
Revisar los detalles de la transacción
Obtén información sobre las transacciones mediante la API de Localpayment. Consulta la documentación sobre información de transacciones para obtener más detalles.

