Saltar al contenido principal
La preautorización es un proceso de dos pasos que permite a los comercios verificar el método de pago del cliente antes de completar la transacción. Este proceso retiene temporalmente el importe de la transacción en la cuenta del cliente sin realizar el cargo. En el primer paso, se realiza la solicitud de preautorización, reservando el importe especificado. Esto garantiza que el cliente dispone de fondos suficientes y que el método de pago es válido. Sin embargo, los fondos no se transfieren al comercio en esta etapa. En el segundo paso, se ejecuta la solicitud de captura para finalizar el pago. El importe preautorizado se debita de la cuenta del cliente y se abona al comercio.

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 solicitud POST 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 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 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 solicitud PATCH 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 solicitud PATCH 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:
  1. Transacción exitosa: Flujo de pago estándar
  2. Errores de validación: Cuenta bancaria no válida, campos faltantes
  3. Retrasos en el procesamiento: Transacciones que requieren tiempo para procesarse.
  4. Transacciones fallidas: Fondos insuficientes, beneficiarios bloqueados
  5. 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.

Última modificación el 20 de noviembre de 2026