# Usar pagos con código QR Acepta pagos sin contacto en tienda con códigos QR. Elige entre la app MONEI Pay, los Puntos de venta del panel o la API de pagos. ## Códigos QR permanentes frente a de un solo uso[​](#códigos-qr-permanentes-frente-a-de-un-solo-uso "Enlace directo al Códigos QR permanentes frente a de un solo uso") | | Permanente | De un solo uso | | ---------------- | ---------------------------------------------- | --------------------------------------------------- | | **Creado desde** | Puntos de venta del panel | App MONEI Pay / API de pagos | | **Formato URL** | `https://secure.monei.com/codes/{code_id}` | `https://secure.monei.com/payments/{payment_id}/qr` | | **Reutilizable** | Sí, el mismo QR para varias transacciones | No, un pago por QR | | **Importe** | El cliente lo introduce (manual) o fijo | Predefinido por pago | | **Expiración** | Nunca (se puede deshabilitar) | 5 minutos (o `expireAt` personalizado mediante API) | | **Ideal para** | Displays estáticos, materiales impresos, mesas | Checkout dinámico, facturas, TPV móvil | ## Antes de empezar[​](#antes-de-empezar "Enlace directo al Antes de empezar") * Necesitarás una cuenta MONEI. Encuentra tus claves de API en [MONEI Dashboard → Ajustes → API](https://dashboard.monei.com/settings/api). * Usa las [claves en modo de prueba](https://docs.monei.com/es/es/testing/.md) para las pruebas de integración. * Asegúrate de que los métodos de pago relevantes estén habilitados en los ajustes de tu cuenta. * Monitoriza los pagos de prueba en [Panel → Pagos](https://dashboard.monei.com/payments) (activa el interruptor de Modo de prueba). - MONEI Pay & Dashboard - Payments API ## App MONEI Pay[​](#app-monei-pay "Enlace directo al App MONEI Pay") MONEI Pay ofrece la forma más sencilla de aceptar pagos en tienda mediante una app dedicada. [YouTube video player](https://www.youtube.com/embed/ZVmXRUFWqno) Inicia sesión en [pay.monei.com](https://pay.monei.com/) o descarga la app **MONEI Pay** usando tus credenciales del MONEI Dashboard para empezar a crear códigos de pago QR. [![App Store](/img/app-store-icon.svg)](https://apps.apple.com/es/app/monei-pay/id1624647668)[![Google Play](/img/google-play-icon.svg)](https://play.google.com/store/apps/details?id=com.monei.moneibusiness) Pagos NFC MONEI Pay también admite **pagos NFC por aproximación** para pagos sin contacto con tarjeta. Si tienes tu propia app de comercio, puedes integrar los pagos NFC usando los [SDKs de integración App-to-App](https://docs.monei.com/es/es/monei-pay/app-integration/getting-started/.md). ## Puntos de venta del panel[​](#puntos-de-venta-del-panel "Enlace directo al Puntos de venta del panel") Crea y gestiona Puntos de venta basados en QR directamente en tu MONEI Dashboard. ### Crear un Punto de venta[​](#crear-un-punto-de-venta "Enlace directo al Crear un Punto de venta") 1. Ve a [Panel → Ajustes → Puntos de venta](https://dashboard.monei.com/settings/points-of-sale) 2. Haz clic en **Crear Punto de venta** 3. Selecciona **Código QR** como tipo 4. Configura los ajustes de tu TPV (consulta las opciones a continuación) ### Opciones de configuración[​](#opciones-de-configuración "Enlace directo al Opciones de configuración") | Opción | Descripción | | ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------- | | **Nombre** | Identificador de este TPV (p. ej., "Entrada de tienda", "Mesa 5") | | **Tienda** | Asociar con una tienda para el seguimiento en varias ubicaciones | | **Flujo de pago** | **Importe manual**: El cliente introduce el importe cada vez. **Importe fijo**: El mismo importe para todas las transacciones | | **Importe fijo / Moneda** | Importe predefinido al usar el flujo de importe fijo | | **Métodos de pago permitidos** | Restringe qué métodos de pago aparecen (Tarjeta, Bizum, PayPal, etc.) | | **Captura manual** | Reserva fondos (solo autorización), captura después. Compatible con Tarjeta, PayPal y Bizum | | **Requerir email** | Obliga a los clientes a introducir su email antes de pagar | | **Requerir NIF/CIF** | Solicita el NIF/CIF para fines de facturación | | **URL de callback** | URL de webhook para las notificaciones de pago | | **Incluir QR en el email** | Añade un código QR con el ID de pedido al email de confirmación (útil para entradas/eventos) | | **Texto del código QR** | Texto personalizado mostrado junto al QR en el email de confirmación | | **Descripción** | Descripción asociada a todos los pagos desde este TPV | ### Gestionar códigos QR[​](#gestionar-códigos-qr "Enlace directo al Gestionar códigos QR") Cada TPV puede tener varios códigos QR. Desde la página de detalles del TPV: * **Genera nuevos códigos** para diferentes ubicaciones o displays * **Descarga los códigos QR** en formato SVG o PNG (300 px, 500 px o 1000 px) * **Habilita o deshabilita códigos** sin eliminarlos * **Copia el enlace permanente** para insertarlo: `https://secure.monei.com/codes/{code_id}` ### Casos de uso[​](#casos-de-uso "Enlace directo al Casos de uso") * **Retail**: Flujo de importe manual, habilita varios métodos de pago * **Eventos/Entradas**: Importe fijo, requerir email, activar "QR en el email de confirmación" * **Servicio en mesa**: Crea varios TPV por tienda para el seguimiento * **Kiosco**: Importe fijo, restringir solo a tarjeta ### Control de acceso de usuarios y agrupación de pagos[​](#control-de-acceso-de-usuarios-y-agrupación-de-pagos "Enlace directo al Control de acceso de usuarios y agrupación de pagos") Las tiendas y los Puntos de venta permiten el control de acceso de usuarios y la agrupación de pagos: * **Asigna usuarios a tiendas/TPV**: En [Panel → Ajustes → Usuarios](https://dashboard.monei.com/settings/users), vincula usuarios (p. ej., camareros, cajeros) a una tienda o TPV * **Visibilidad restringida**: Los usuarios vinculados solo ven los pagos de su tienda/TPV asignado * **Herencia automática**: Cuando un usuario vinculado crea un pago desde el panel o MONEI Pay, hereda el ID de su tienda/TPV * **Agrupación por API**: Pasa `storeId` o `pointOfSaleId` al crear pagos mediante la API para agruparlos en los informes * **Trazabilidad**: Los administradores pueden filtrar y rastrear pagos por tienda o TPV de origen ## Crear pagos QR de forma programática[​](#crear-pagos-qr-de-forma-programática "Enlace directo al Crear pagos QR de forma programática") Genera códigos de pago QR usando la MONEI API para integraciones personalizadas. ![QR](/img/qr.png)![Demo de QR](/img/qr-demo.png) ### 1. Crear el pago (lado del servidor)[​](#1-crear-el-pago-lado-del-servidor "Enlace directo al 1. Crear el pago (lado del servidor)") Crea un [Pago](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md) en tu servidor con un importe y una moneda. * cURL * Node.js * PHP * Python POST https\://api.monei.com/v1/payments ``` curl --request POST 'https://api.monei.com/v1/payments' \ --header 'Authorization: YOUR_API_KEY' \ --header 'Content-Type: application/json' \ --data-raw '{ "amount": 110, "currency": "EUR", "orderId": "14379133960355", "callbackUrl": "https://example.com/checkout/callback" }' ``` (Reemplaza `YOUR_API_KEY` con tu clave de API de MONEI real) server.js ``` import {Monei} from '@monei-js/node-sdk'; // Replace YOUR_API_KEY with your actual MONEI API key const monei = new Monei('YOUR_API_KEY'); const payment = await monei.payments.create({ amount: 110, currency: 'EUR', orderId: '14379133960355', callbackUrl: 'https://example.com/checkout/callback' }); // You will need the paymentId from the response to generate the QR code URL const paymentId = payment.id; // Construct the QR code URL const qrCodeUrl = `https://secure.monei.com/payments/${paymentId}/qr`; ``` server.php ``` payments->create( new CreatePaymentRequest([ 'amount' => 110, 'currency' => 'EUR', 'order_id' => '14379133960355', 'callback_url' => 'https://example.com/checkout/callback' ]) ); // You will need the paymentId from the response to generate the QR code URL $paymentId = $payment->getId(); // Construct the QR code URL $qrCodeUrl = "https://secure.monei.com/payments/{$paymentId}/qr"; ?> ``` server.py ``` import Monei from Monei import CreatePaymentRequest # Replace YOUR_API_KEY with your actual MONEI API key monei = Monei.MoneiClient(api_key="YOUR_API_KEY") payment = monei.payments.create( CreatePaymentRequest( amount=110, currency="EUR", order_id="14379133960355", callback_url="https://example.com/checkout/callback" ) ) # You will need the paymentId from the response to generate the QR code URL payment_id = payment.id # Construct the QR code URL qr_code_url = f"https://secure.monei.com/payments/{payment_id}/qr" ``` **Parámetros obligatorios:** * **amount** `positive integer`: Importe en la unidad monetaria más pequeña (p. ej., 110 para €1,10). * **currency** `string`: [Código de moneda ISO](https://en.wikipedia.org/wiki/ISO_4217) de tres letras (p. ej., `EUR`). * **orderId** `string`: Tu identificador de pedido único. * **callbackUrl** `string`: La URL de tu endpoint de servidor para las notificaciones de webhook asíncronas. **Parámetros opcionales:** * **allowedPaymentMethods** `array`: Restringe los métodos de pago disponibles (p. ej., `["card", "bizum"]`) * **description** `string`: Descripción del pago mostrada en la página de pago * **customer** `object`: Rellena previamente los datos del cliente (`email`, `name`, `phone`) * **metadata** `object`: Pares clave-valor personalizados para el seguimiento y la conciliación * **storeId** `string`: Asocia el pago con una tienda (para agrupación y control de acceso de usuarios) * **pointOfSaleId** `string`: Vincula el pago a un TPV (para agrupación y control de acceso de usuarios) * **expireAt** `integer`: Marca de tiempo Unix para la expiración personalizada (por defecto: 5 minutos desde la creación) Consulta todos los [parámetros de la solicitud](https://docs.monei.com/es/es/apis/rest/payments-create/.md) disponibles. La respuesta de la API incluye el `payment.id`, que usarás en el siguiente paso. ### 2. Mostrar el código QR y gestionar la interacción (cliente/físico)[​](#2-mostrar-el-código-qr-y-gestionar-la-interacción-clientefísico "Enlace directo al 2. Mostrar el código QR y gestionar la interacción (cliente/físico)") Usa el `payment.id` del Paso 1 para presentar el código QR a tu cliente. **Opción 1: Insertar la imagen QR directamente** Construye la URL de la imagen del código QR: `https://secure.monei.com/payments/{payment_id}/qr` Puedes renderizarla directamente en una página web o un display: ``` Escanear para pagar ``` * Reemplaza `{{payment_id}}` con el ID real. * Usa `?format=svg` para SVG (por defecto es `png`). * Usa `?size=400` para especificar el tamaño (mín: 100, máx: 1000, por defecto: 300). ![Ejemplo de QR](https://secure.monei.com/codes/RYGJ0ZFK/qr?format=svg\&size=300) **Opción 2: Redirigir a la página alojada con QR** El [objeto Payment](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md) devuelto en el Paso 1 también contiene `payment.nextAction.redirectUrl`. Añade `?qr=1` a esta URL para obtener un enlace a una página alojada por MONEI que muestra el código QR. Ejemplo: `https://secure.monei.com/payments/{payment_id}?qr=1` ![Página de pago alojada con QR](/es/assets/images/qr-demo-2-b5f9696c05e4207feb175d4824de5b0a.png) **Interacción del cliente:** El cliente escanea el código QR con su teléfono y completa el pago en la página de pago de MONEI usando su método preferido. Importante El enlace de pago del código QR es válido durante **5 minutos**. Tras ese tiempo, debes crear una nueva solicitud de pago. ### 3. Procesar la notificación de webhook (lado del servidor)[​](#3-procesar-la-notificación-de-webhook-lado-del-servidor "Enlace directo al 3. Procesar la notificación de webhook (lado del servidor)") MONEI envía el estado final y autoritativo del pago mediante una solicitud HTTP POST asíncrona a la `callbackUrl` que proporcionaste en el Paso 1. El cuerpo de la solicitud contiene el [objeto Payment](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md) completo en formato JSON. Este webhook garantiza que recibas el estado definitivo incluso si el cliente cierra el navegador o pierde la conexión tras escanear. **Es imprescindible que:** 1. **Verifiques la cabecera `MONEI-Signature`** incluida en la solicitud. Esto confirma que el webhook proviene realmente de MONEI. Consulta la [guía de verificación de firmas](https://docs.monei.com/es/es/guides/verify-signature/.md) para los detalles de implementación. 2. **Devuelvas un código de estado HTTP `200 OK`** inmediatamente al recibir el webhook para confirmar la recepción. Cualquier otro código de estado indica a MONEI que la notificación ha fallado. Si MONEI no recibe un `200 OK`, reintentará el envío del webhook. Una vez verificada la firma, inspecciona el campo `status` en el objeto Payment para confirmar el éxito del pago (`SUCCEEDED`) y completar el pedido, o gestionar los fallos. ### Alternativa: Consultar el estado del pago[​](#alternativa-consultar-el-estado-del-pago "Enlace directo al Alternativa: Consultar el estado del pago") Para escenarios de kiosco o display en los que necesitas actualizaciones de estado en tiempo real, consulta el estado del pago en lugar de (o además de) los webhooks. * cURL * Node.js * PHP * Python GET https\://api.monei.com/v1/payments/{payment\_id} ``` curl --request GET 'https://api.monei.com/v1/payments/{payment_id}' \ --header 'Authorization: YOUR_API_KEY' ``` server.js ``` const payment = await monei.payments.get(paymentId); console.log(payment.status); ``` server.php ``` payments->get($paymentId); echo $payment->getStatus(); ?> ``` server.py ``` payment = monei.payments.get(payment_id) print(payment.status) ``` **Valores de estado:** `PENDING`, `PENDING_PROCESSING`, `SUCCEEDED`, `FAILED`, `CANCELED`, `EXPIRED` Buenas prácticas de consulta Consulta cada 2-3 segundos. Detente cuando el estado ya no sea `PENDING`/`PENDING_PROCESSING` o cuando el QR expire. ## Personalización[​](#personalización "Enlace directo al Personalización") Puedes personalizar la apariencia del código QR (color, icono) y la página de pago alojada en tu [MONEI Dashboard → Ajustes → Marca](https://dashboard.monei.com/settings/branding). ## Pruebas[​](#pruebas "Enlace directo al Pruebas") * Usa tus [claves de API en modo de prueba](https://docs.monei.com/es/es/testing/.md) para el desarrollo * Activa el **Modo de prueba** en tu [Panel](https://dashboard.monei.com/payments) para ver los pagos de prueba * Usa [números de tarjeta de prueba](https://docs.monei.com/es/es/testing/.md#test-card-numbers) para simular diferentes escenarios * Verifica la entrega de webhooks en Panel → Desarrolladores → Webhooks ## Solución de problemas[​](#solución-de-problemas "Enlace directo al Solución de problemas") **Código QR expirado** Los códigos QR son válidos durante 5 minutos. Crea un nuevo pago si el código expira. **El método de pago no aparece** Comprueba que el método esté habilitado en tu cuenta y que no esté filtrado por `allowedPaymentMethods`. **Webhook no recibido** Verifica que tu `callbackUrl` sea accesible públicamente, devuelva `200 OK` y consulta los registros de webhooks en el panel.