Saltar al contenido principal
​Localpayment permite a los comercios procesar pagos únicos mediante tarjetas de crédito y débito, en múltiples países y divisas. Esta guía describe el proceso para iniciar un pago único con tarjeta a través de la API de Localpayment, detallando los parámetros necesarios, el manejo de las respuestas y la interpretación de los códigos de estado.

Antes de comenzar

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 un pago con tarjeta

Para iniciar un pago único con tarjeta, deberás enviar una solicitud POST al endpoint Crear Payin.

Parámetros clave de la solicitud

La solicitud requiere varios objetos clave: El paymentMethod.code depende del país, la marca de la tarjeta y el 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.

Pago con tarjeta tokenizada

Si ya has tokenizado la tarjeta de un cliente, puedes usar el token en lugar de enviar los datos completos de la tarjeta para procesar un pago único. Esto mejora la seguridad y simplifica el proceso de pago al eliminar la necesidad de solicitar la información de la tarjeta nuevamente. Para obtener información detallada sobre la tokenización de tarjetas, consulta la documentación sobre tokenización.

Pago con 3D Secure

Si el titular de la tarjeta requiere autenticación adicional, el proceso se realizará mediante 3D Secure. En este caso, Localpayment devuelve la URL de desafío del emisor en la respuesta de la API, y es responsabilidad del comercio redirigir al cliente o mostrar el desafío durante el proceso de pago. Esto permite al titular de la tarjeta completar la verificación requerida. La experiencia exacta con 3D Secure puede variar según el emisor y el país del cliente. Para obtener información detallada sobre los pagos 3D Secure, consulta la documentación de 3D Secure.

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: Seguimiento del estado de la transacción

Tras iniciar un pago único, 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.
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. 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 procesado un pago único, es posible que debas realizar acciones adicionales, tales como:

Reembolsar la transacción

Si es necesario, puedes reembolsar el pago al cliente. Consulta la documentación para obtener más detalles.

Gestionar las devoluciones de cargo

En caso de disputa, es posible que debas gestionar las devoluciones de cargo. Consulta la documentación para obtener información sobre este proceso.

Revisar los detalles de la transacción

Puedes recuperar información sobre las transacciones utilizando la API de Localpayment para obtener información detallada.
Última modificación el 20 de noviembre de 2026