# Bizum
Acepta pagos con [Bizum](https://bizum.es/) en tu sitio web o aplicación móvil usando la [Página de pago alojada](https://docs.monei.com/es/es/integrations/use-prebuilt-payment-page/.md) o el [Componente Bizum](https://docs.monei.com/es/es/monei-js/reference/.md#componente-bizum). No se necesita ninguna configuración adicional para la Página de pago alojada.
El [Componente Bizum](https://docs.monei.com/es/es/monei-js/reference/.md#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[](#antes-de-empezar "Enlace directo al 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](https://support.monei.com/hc/requests/new) 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](https://support.monei.com/hc/requests/new); de lo contrario, Bizum no se activará.
Una vez activado, Bizum aparece en [MONEI Dashboard → Ajustes → Métodos de pago](https://dashboard.monei.com/settings/payment-methods).
Para probar tu integración:
* Usa tu Account ID y clave de API del [modo de prueba](https://docs.monei.com/es/es/testing/.md).
* Usa los [números de teléfono](https://docs.monei.com/es/es/testing/.md#n%C3%BAmeros-de-tel%C3%A9fono-de-prueba-para-bizum) de prueba.
* Puedes comprobar el estado de un pago de prueba en tu [MONEI Dashboard → Pagos](https://dashboard.monei.com/payments) (en modo de prueba).
## Integración[](#integración "Enlace directo al Integración")
### 1. Crear un pago `Servidor`[](#1-crear-un-pago-servidor "Enlace directo al 1-crear-un-pago-servidor")
Crea un [Pago](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md) 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
* 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",
"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)
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;
```
server.php
```
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();
?>
```
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](https://en.wikipedia.org/wiki/ISO_4217) 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](https://docs.monei.com/es/es/apis/rest/payments-create/.md) 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`[](#2-añadir-bizum-a-tu-página-de-pago-cliente "Enlace directo al 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
```
Checkout
```
Añade el [Componente Bizum](https://docs.monei.com/es/es/monei-js/reference/.md#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
```
```
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` .
bizum.render('#bizum_container');
```
nota
El Componente Bizum también está disponible como componente de [React](https://docs.monei.com/es/es/monei-js/react/.md), [Vue](https://docs.monei.com/es/es/monei-js/vue/.md), [Angular](https://docs.monei.com/es/es/monei-js/angular/.md) y [Svelte](https://docs.monei.com/es/es/monei-js/svelte/.md).
Consulta la [Referencia de MONEI JS](https://docs.monei.com/es/es/monei-js/reference/.md#componente-bizum) para ver más opciones.
### 3. Confirmar el pago `Cliente`[](#3-confirmar-el-pago-cliente "Enlace directo al 3-confirmar-el-pago-cliente")
Para completar el pago necesitas confirmarlo usando la función [confirmPayment](https://docs.monei.com/es/es/monei-js/reference/.md#funci%C3%B3n-confirmpayment) de monei.js.
Debes proporcionar un `paymentId` (obtenido en el [paso 1](#1-crear-un-pago-servidor)) y el `paymentToken` generado con el Componente Bizum. También puedes proporcionar parámetros adicionales como `customer.email`. Consulta todos los [parámetros](https://docs.monei.com/es/es/apis/rest/payments-confirm/.md) 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](https://docs.monei.com/es/es/apis/rest/payments-confirm/.md) en el lado del servidor.
### 4. Procesar la notificación webhook `Servidor`[](#4-procesar-la-notificación-webhook-servidor "Enlace directo al 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](https://docs.monei.com/es/es/apis/rest/schemas/payment/.md) 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](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` del objeto Pago (`SUCCEEDED`, `FAILED`, `CANCELED`, etc.) para determinar si debes completar el pedido o gestionar el error.
## Antes de pasar a producción[](#antes-de-pasar-a-producción "Enlace directo al 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)](https://docs.monei.com/es/es/testing/.md).
* Asegúrate de que has conectado tu cuenta de negocio de Bizum en el [MONEI Dashboard](https://dashboard.monei.com/settings/payment-methods).
## Información adicional[](#información-adicional "Enlace directo al Información adicional")
### Monitorización del estado del pago[](#monitorización-del-estado-del-pago "Enlace directo al 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[](#límites-de-importe "Enlace directo al 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[](#pre-autenticaciones "Enlace directo al 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[](#reembolsos "Enlace directo al 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[](#suscripciones "Enlace directo al 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[](#solicitud-de-pago "Enlace directo al Solicitud de pago")
Puedes [enviar una solicitud de pago](https://docs.monei.com/es/es/apis/rest/payments-send-request/.md) 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:
