Saltar al contenido principal
Localpayment permite a los comerciantes procesar pagos instantáneos a través del sistema de pago QR Fri de Guatemala, la plataforma de pago QR interoperable y estandarizada del país, regulada por el Banco de Guatemala. Fri (anteriormente conocida como Soyfri) es una billetera digital y plataforma de pagos que facilita transacciones rápidas y seguras, permitiendo a los usuarios vincular sus cuentas bancarias o cooperativas para realizar operaciones financieras directamente desde sus dispositivos móviles. Esta guía describe el proceso para iniciar pagos con QR Fri 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 para una integración perfecta con la red de pagos unificada de Guatemala. QR Fri permite a los comercios generar códigos QR dinámicos mediante la API, que los clientes escanean con la aplicación Fri, facilitando pagos en tiempo real directamente desde sus cuentas bancarias vinculadas a través de la infraestructura de intermediación de pagos de Fri.
Los pagos con QR Fri en Guatemala están disponibles a través de las billeteras Fri y Micoope para personas físicas, jurídicas y usuarios extranjeros con números de teléfono guatemaltecos. Entre los bancos compatibles se incluyen GyT, Banrural, Promerica y cooperativas como Micoope, mientras que Banco Industrial y BAC están excluidos por el momento. Consulta el sitio web oficial de Fri para obtener la lista completa de instituciones compatibles.

Antes de comenzar

Asegúrate de tener:

Paso 1. Crear pago con código QR

Para generar un código QR para la recaudación de pagos, envía una solicitud POST al endpoint Crear Payin con parámetros específicos para códigos QR.

Parámetros clave de la solicitud

La solicitud requiere varios objetos clave específicos para los pagos mediante código QR: Consulta todos los parámetros disponibles en la solicitud.

Ejemplo de solicitud

A continuación se muestra un ejemplo que utiliza curl:
curl

Paso 2. Gestionar la respuesta

Respuesta exitosa

La creación exitosa de un pago mediante código QR incluye los datos del código QR y los detalles del pago:

Campos de respuesta clave

Respuesta de error

Si falla la generación del código QR, recibirás información detallada sobre el error:

Paso 3. Mostrar el código QR y procesar el pago

  1. Visualización de código QR: Presenta el código QR al cliente a través del canal elegido.
  2. Escaneo mediante la aplicación bancaria: El cliente escanea el código QR con la aplicación móvil de su banco.
  3. Autorización de pago: El cliente confirma el pago en su entorno bancario.
  4. Confirmación en tiempo real: Localpayment recibe una notificación de pago instantánea.
  5. Actualización de estado: Tu sistema recibe un webhook con la confirmación del pago.

Mejores prácticas para la visualización de códigos QR

Los códigos QR Fri son válidos durante 5 minutos a partir de su generación. Si el código QR caduca antes de que el cliente lo escanee, deberás crear una nueva solicitud de pago para generar un nuevo código.
  • Tamaño mínimo de pantalla: 250x250 píxeles para escaneo móvil.
  • Mantén una relación de aspecto de 1:1 sin distorsión.
  • Asegúrate de que haya un alto contraste (fondo oscuro sobre fondo claro).
  • Agrega una zona de silencio (borde blanco) alrededor del código QR.
  • Incluye texto alternativo (por ejemplo, “Pago mediante código QR”).
  • Muestra instrucciones de pago claras.
  • Mostrar un temporizador de cuenta regresiva basado en qr.expirationDate (ventana de 5 minutos) y notificar al cliente si el código QR caduca.

Paso 4. Seguimiento del estado de la transacción

Supervisa el progreso del pago mediante código QR a través de 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.
Referencia completaConsulta todos los códigos de estado en nuestra documentación sobre el estado de las transacciones.

Probando tu integración

Entorno de pruebas

Utiliza el entorno de prueba para realizar las pruebas:

Escenarios de prueba de QR

Verifica que tu integración gestione estos escenarios:
  1. Pago exitoso: Completa el escaneo del código QR y el proceso de pago.
  2. Caducidad de los códigos QR: Gestiona correctamente los códigos QR caducados.
  3. Múltiples intentos de pago: Se escaneó el mismo código QR varias veces.
  4. Actualizaciones de estado: Gestión de webhooks y sondeo de estado.

Próximos pasos

Tras implementar los pagos mediante código QR, ten en cuenta estas funcionalidades adicionales:

Reembolsar la transacción

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

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 10 de noviembre de 2026