Bizum

Acepta pagos con Bizum en tu sitio web o aplicación móvil usando la Página de pago alojada o el Componente Bizum. No se necesita ninguna configuración adicional para la Página de pago alojada.

El Componente Bizum muestra un botón de Bizum en tu página de pago. Cuando los clientes seleccionan Bizum, aparece una superposición donde introducen su número de teléfono registrado para completar el pago.

Antes de empezar

Bizum se activa automáticamente — no necesitas hacer nada. Una vez que tu cuenta esté completamente aprobada, Bizum se habilitará en un promedio de 2–3 días laborables. Por favor, contacta con nuestro equipo de soporte si no se ha activado después de 7 días.

Para que la activación automática funcione, tu sitio web debe ser accesible públicamente. Si está protegido con contraseña, proporciona las credenciales durante el proceso de incorporación o envíalas abriendo una solicitud al equipo de soporte; de lo contrario, Bizum no se activará.

Una vez activado, Bizum aparece en MONEI Dashboard → Ajustes → Métodos de pago.

Para probar tu integración:

• Usa tu Account ID y clave de API del modo de prueba.
• Usa los números de teléfono de prueba.
• Puedes comprobar el estado de un pago de prueba en tu MONEI Dashboard → Pagos (en modo de prueba).

Integración

1. Crear un pago Servidor

Crea un Pago en tu servidor con un importe y una moneda. Decide siempre cuánto cobrar en el lado del servidor, un entorno de confianza, y no en el cliente. Esto evita que clientes malintencionados puedan elegir sus propios precios.

cURL

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",
  "description": "Test Shop - #14379133960355",
  "customer": {
    "email": "email@example.com"
   },
  "callbackUrl": "https://example.com/checkout/callback"
}'

(Sustituye YOUR_API_KEY por tu clave de API de MONEI real)

Node.js

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',
  description: 'Test Shop - #14379133960355',
  customer: {
    email: 'email@example.com'
  },
  callbackUrl: 'https://example.com/checkout/callback'
});

// Pass payment.id to your client-side
const paymentId = payment.id;

PHP

server.php

<?php
require_once 'vendor/autoload.php';

use Monei\Model\CreatePaymentRequest;
use Monei\Model\PaymentCustomer;
use Monei\MoneiClient;

// Replace YOUR_API_KEY with your actual MONEI API key
$monei = new MoneiClient('YOUR_API_KEY');

$payment = $monei->payments->create(
  new CreatePaymentRequest([
    'amount' => 110,
    'currency' => 'EUR',
    'order_id' => '14379133960355',
    'description' => 'Test Shop - #14379133960355',
    'customer' => new PaymentCustomer([
      'email' => 'email@example.com'
    ]),
    'callback_url' => 'https://example.com/checkout/callback'
  ])
);

// Pass payment ID to your client-side
$paymentId = $payment->getId();
?>

Python

server.py

import Monei
from Monei import CreatePaymentRequest, PaymentCustomer

# 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",
        description="Test Shop - #14379133960355",
        customer=PaymentCustomer(
          email="email@example.com"
        ),
        callback_url="https://example.com/checkout/callback"
    )
)

# Pass payment ID to your client-side
payment_id = payment.id

Los siguientes parámetros son obligatorios:

• amount entero positivo - Importe que se pretende cobrar con este pago. Un entero positivo que representa cuánto cobrar en la unidad de moneda más pequeña (p. ej., 100 céntimos para cobrar 1,00 USD)
• currency cadena - Código de moneda ISO de tres letras, en mayúsculas. Debe ser una moneda compatible.
• orderId cadena - Un ID de pedido de tu sistema. Un identificador único que puede usarse para conciliar el pago con tu sistema interno.
• callbackUrl cadena - La URL a la que se enviará de forma asíncrona el resultado del pago.

Consulta todos los parámetros de solicitud disponibles.

El objeto Pago devuelto incluye un id de pago, que se usa en el lado del cliente para completar de forma segura el proceso de pago en lugar de pasar el objeto Pago completo.

2. Añadir Bizum a tu página de pago Cliente

Incluye monei.js en tu página de checkout añadiendo la etiqueta script al head de tu archivo HTML.

checkout.html

<head>
  <title>Checkout</title>
  <script src="https://js.monei.com/v3/monei.js"></script>
</head>

Añade el Componente Bizum de MONEI a tu página de pago. Crea un nodo DOM vacío (contenedor) con un ID único en tu formulario de pago.

checkout.html

<form
  action="https://secure.monei.com/payments/{{payment_id}}/confirm"
  method="post"
  id="payment-form"
>
  <div id="bizum_container">
    <!-- A MONEI Bizum Component will be inserted here. -->
  </div>
</form>

Inicializar el Componente Bizum

client.js

// Create an instance of the Bizum component.
const bizum = monei.Bizum({
  paymentId: '{{payment_id}}',
  onSubmit(result) {
    // result.paymentMethod === 'bizum'
    moneiTokenHandler(result.token);
  },
  onError(error) {
    console.log(error);
  }
});

// Render an instance of the Bizum component into the `bizum_container` <div>.
bizum.render('#bizum_container');

nota

El Componente Bizum también está disponible como componente de React, Vue, Angular y Svelte.

Consulta la Referencia de MONEI JS para ver más opciones.

3. Confirmar el pago Cliente

Para completar el pago necesitas confirmarlo usando la función confirmPayment de monei.js.

Debes proporcionar un paymentId (obtenido en el paso 1) y el paymentToken generado con el Componente Bizum. También puedes proporcionar parámetros adicionales como customer.email. Consulta todos los parámetros disponibles.

client.js

// Confirm the payment
async function moneiTokenHandler(token) {
  try {
    const result = await monei.confirmPayment({
      paymentId: '{{payment_id}}',
      paymentToken: token
    });
    // At this moment you can show a customer the payment result
    // But you should always rely on the result passed to the callback endpoint
    // on your server to update the order status
    console.log(result);
  } catch (error) {
    console.error(error);
  }
}

nota

Como proceso alternativo, puedes enviar el paymentToken generado a tu servidor y luego confirmar el pago en el lado del servidor.

4. Procesar la notificación webhook Servidor

Tras la interacción en el lado del cliente y cualquier procesamiento en segundo plano necesario, MONEI envía el estado de pago final y autoritativo mediante una solicitud HTTP POST asíncrona a la callbackUrl que proporcionaste en el Paso 1.

El cuerpo de la solicitud contiene el objeto Pago completo en formato JSON.

Este webhook es la única forma fiable de confirmar el resultado definitivo del pago.

Es imprescindible que:

1. Verifiques el encabezado MONEI-Signature incluido en la solicitud. Esto confirma que el webhook proviene genuinamente de MONEI. Consulta la guía de verificación de firmas 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 del objeto Pago (SUCCEEDED, FAILED, CANCELED, etc.) para determinar si debes completar el pedido o gestionar el error.

Antes de pasar a producción

• Asegúrate de que estás usando el Account ID y la clave de API del modo de producción (live).
• Asegúrate de que has conectado tu cuenta de negocio de Bizum en el MONEI Dashboard.

Información adicional

Monitorización del estado del pago

MONEI supervisa activamente el estado de las transacciones de Bizum para garantizar la coherencia entre la pasarela de pago y el procesador, evitando discrepancias que podrían afectar a comercios o consumidores.

Límites de importe

Las transacciones de Bizum online no tienen límite máximo de importe. Si una transacción falla, puede deberse a que el banco emisor impone su propio límite o a que no hay fondos suficientes. A diferencia de los límites entre particulares (P2P), no existe un límite mensual para las compras online.

Pre-autenticaciones

Bizum admite pre-autenticaciones (transactionType: AUTH) para verificar que el número de Bizum pertenece al titular de la cuenta sin bloquear fondos. Tras una autenticación exitosa, dispones de hasta 30 días para capturar el pago. Se admiten capturas totales y parciales. Si no hay fondos suficientes en el momento de la captura, la transacción no se procesará. No se requiere SCA adicional durante la captura.

Las pre-autenticaciones solo están disponibles si el banco del cliente admite el flujo RTP (Request to Pay).

Reembolsos

Las transacciones de Bizum pueden reembolsarse en un plazo de 180 días. Los reembolsos pueden fallar si:

• El cliente ha desconectado su cuenta de Bizum.
• El cliente ha cambiado el vínculo entre su número de teléfono y el IBAN.
• El banco emisor está experimentando problemas internos con las notificaciones de Bizum.

Suscripciones

Puedes usar Bizum para suscripciones o pagos recurrentes, de forma similar a las suscripciones basadas en tarjeta. Establece Bizum como método de pago al crear una suscripción a través de la API de MONEI.

Consideraciones clave:

• La cobertura bancaria todavía se está desplegando, con un objetivo de cobertura de usuarios superior al 90%. Si el banco del cliente no admite suscripciones de Bizum, la suscripción no funcionará. Confírmalo directamente con tu cliente.
• El cliente autoriza únicamente el primer pago. Los pagos posteriores se procesan automáticamente a través del motor de suscripciones de MONEI, o puedes gestionarlos manualmente usando la API de pagos recurrentes.
• Solo se puede realizar un pago recurrente al mes a través de Bizum, y el importe de la suscripción no puede modificarse tras el primer pago.

Solicitud de pago

Puedes enviar una solicitud de pago directamente al teléfono del cliente. Si el número de teléfono está registrado en Bizum, el cliente recibe una notificación push para confirmar el pago en su aplicación bancaria. Si no lo está, recibe un enlace de pago por WhatsApp. Esta funcionalidad funciona de forma independiente al Componente UI.

Ejemplo de notificación push de Bizum: