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.
Requisitos adicionales para el reembolso:
- Debes tener saldo suficiente en tu cuenta de Localpayment para cubrir el importe del reembolso.
- Rol de usuario con permisos de reembolso (consulta la documentación sobre roles de usuario).
- La transacción original debe estar en estado
Completed. - El
externalIdde la transacción de pago original.
Guía de implementación
Localpayment ofrece dos métodos para procesar reembolsos de cuentas virtuales: integración mediante API para el procesamiento automatizado y Business Portal para operaciones manuales.Procesamiento de reembolsos mediante API
Procesa reembolsos mediante programación a través de la API REST para flujos de trabajo automatizados e integración con tus sistemas.
Procesamiento de reembolsos del Business Portal
Gestiona manualmente los reembolsos a través del Business Portal de Localpayment, que cuenta con una interfaz fácil de usar.
Reembolsos directos para cuentas virtuales
Todos los reembolsos de cuentas virtuales se procesan como reembolsos directos, es decir, solo necesitas elexternalId de la transacción original. El sistema devuelve automáticamente los fondos a la cuenta del pagador original, sin requerir información adicional del beneficiario.
Requisitos específicos de cada país
Los reembolsos de cuentas virtuales tienen requisitos y limitaciones específicos según el país y el método de pago. A continuación, se detallan las principales consideraciones específicas de cada país:- México
- Banco Azteca: Actualmente no se ofrecen reembolsos para los pagos procesados a través de Banco Azteca en México.
- SPEI/TEF: Todos los reembolsos por pagos realizados a través de SPEI o TEF se procesan a través de la red SPEI.
Paso 1: Procesar el reembolso a través de la API.
Para reembolsar un pago de cuenta virtual mediante la API, envía una solicitudPATCH al endpoint de reembolso.
Parámetros clave de la solicitud
La solicitud requiere varios parámetros clave:Ejemplo de solicitud
A continuación se muestra un ejemplo que utilizacurl:
curl
Paso 2: Gestionar la respuesta
Respuesta exitosa
Un reembolso procesado correctamente devuelve los detalles de confirmación:Campos de respuesta clave
Respuesta de error
Cuando falla una solicitud de reembolso, recibirás información de error:Escenarios de errores comunes
Reembolsos del Business Portal
Los reembolsos de cuentas virtuales también se pueden procesar a través de la interfaz del Business Portal de Localpayment. Este método proporciona un flujo de trabajo visual para gestionar los reembolsos y es particularmente útil para:- Reembolsos ocasionales que no requieren automatización mediante API.
- Supervisión administrativa cuando se requieren flujos de trabajo de aprobación.
- Procesamiento rápido de reembolsos sin necesidad de recursos de desarrollo.
Paso 3: Seguimiento del estado del reembolso
Tras iniciar un reembolso, 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 de reembolso comunes
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:- Reembolso exitoso: Procesa un reembolso con un
externalIdválido y fondos suficientes. - Fondos insuficientes: Intentar realizar un reembolso con saldo insuficiente en la cuenta.
- Transacción no válida: Intenta reembolsar un
externalIdinexistente. - Reembolso duplicado: Intento de reembolsar una transacción que ya ha sido reembolsada.
- Validación de permisos: Realiza pruebas con usuarios que tengan diferentes niveles de permisos.
Próximos pasos
Ver estado de la transacción
Consulta el estado actual de las transacciones y los reembolsos mediante la API de
estado de transacciones.
Configurar webhooks
Configura webhooks para recibir notificaciones en tiempo real sobre los cambios de
estado de los reembolsos.
Revisar los roles de usuario
Gestiona los permisos y roles de usuario para las funciones de procesamiento de reembolsos.

