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 solicitudPOST 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 utilizacurl:
curl
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:- 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 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.

