Acepta Bizum en Stripe con la app de MONEI

La app de MONEI para Stripe añade Bizum a tu propio Payment Element de Stripe como un método de pago personalizado. MONEI procesa el pago con su propia licencia de de Bizum y los fondos en tu cuenta de MONEI. Después, MONEI informa cada pago correcto y cada devolución a tu cuenta de Stripe mediante la Payment Records API. Bizum aparece junto al resto de tus pagos en Stripe.

Qué construyes

Añades Bizum al Payment Element de tu página de pago con monei.js. No necesitas código de servidor ni una clave de API de MONEI para cobrar: MONEI crea el pago y lo informa a Stripe. Tu servidor solo lee el resultado para completar el pedido. No creas un tipo de método de pago personalizado en Stripe: la app trae el de MONEI.

Cómo funciona

Antes de empezar

• Una cuenta de MONEI con Bizum activado (MONEI Dashboard → Configuración → Métodos de pago → Bizum). Bizum está disponible para clientes cuya cuenta bancaria esté en España (también AD/IE) y dada de alta en Bizum.
• Una cuenta de Stripe cuya página de pago use el Payment Element.

1. Conecta tu cuenta de Stripe

Instala la app de MONEI para Bizum en tu cuenta de Stripe. Para hacer pruebas primero, instálala en un sandbox de Stripe o en el modo test de tu cuenta de Stripe: se conecta a tu modo test de MONEI. Una instalación en modo live se conecta a tu modo live de MONEI.

Stripe te lleva a MONEI. Inicia sesión y después:

1. Elige la cuenta de MONEI que recibe los pagos de Bizum. Una instalación en modo live necesita una cuenta de MONEI aprobada. Una instalación de prueba ofrece solo las cuentas de MONEI que tienen una cuenta de prueba válida.
2. Escribe los orígenes de la tienda: los orígenes de tu página de pago y de tus páginas de retorno, por ejemplo https://shop.example.com. MONEI acepta pagos de Bizum solo desde estos orígenes y devuelve al cliente solo a ellos.
3. Opcional: escribe una URL de callback. MONEI le envía el resultado de cada pago de Bizum (consulta el paso 3).
4. Haz clic en Conectar. La página muestra el código de createStripeBizum para el paso 2 con el ID de tu cuenta de Stripe.

2. Añade Bizum al Payment Element Cliente

Incluye monei.js en tu página de pago:

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

Crea el handler de Bizum con createStripeBizum. Añade su método de pago personalizado a stripe.elements(). Cuando el cliente envía el pago y Bizum es el método elegido, llama a pay():

checkout.js

const bizum = monei.createStripeBizum({
  publishableKey: 'pk_test_...', // la misma clave que Stripe.js; pk_live_ = modo live
  stripeAccount: 'acct_...', // tu cuenta de Stripe
  sandbox: false // true cuando acct_... es un sandbox de Stripe
});

const stripe = Stripe('pk_test_...');
const elements = stripe.elements({
  mode: 'payment',
  amount: 1250,
  currency: 'eur',
  customPaymentMethods: [bizum.customPaymentMethod]
});
elements.create('payment').mount('#payment-element');

payButton.addEventListener('click', async () => {
  const {error, selectedPaymentMethod} = await elements.submit();
  if (error) return;
  if (!bizum.isSelected(selectedPaymentMethod)) {
    // Otros métodos de pago: tu flujo habitual con stripe.confirmPayment.
    return;
  }
  try {
    const payment = await bizum.pay({
      amount: 1250,
      currency: 'EUR',
      orderId: 'order_123',
      completeUrl: 'https://shop.example.com/complete',
      failUrl: 'https://shop.example.com/failed'
    });
    // payment.status: 'SUCCEEDED', 'FAILED', ...
  } catch (err) {
    // Bizum no está disponible, o el cliente cerró la ventana de Bizum.
  }
});

pay() abre la ventana de Bizum en tu página. El cliente introduce su número de teléfono y aprueba el pago en la app de su banco. Cuando el pago necesita una redirección, el cliente vuelve a completeUrl o a failUrl. La referencia da todas las opciones y los valores devueltos.

3. Completa el pedido Servidor

El resultado de pay() y la redirección vienen del navegador, y un cliente puede cambiarlos. Completa el pedido solo a partir de una de estas fuentes:

• El callback de MONEI. Si diste a MONEI una URL de callback, MONEI le envía el objeto Payment final. Antes, verifica la cabecera MONEI-Signature.
• El Payment Record de Stripe. El registro contiene el ID de tu pedido en metadata.order_id, el ID del pago de MONEI en metadata.monei_payment_id y en processor_details.custom.payment_reference, y el importe pagado.

La página fija el importe, así que completa un pedido solo cuando el importe pagado coincide con el del pedido.

4. Devoluciones

Devuelve el pago en MONEI, desde MONEI Dashboard → Pagos o con la API de devoluciones. Stripe no procesa el pago de Bizum, así que una devolución no puede empezar en Stripe. MONEI informa cada devolución total o parcial en el Payment Record del pago.

Qué informa MONEI a Stripe

Pago de MONEI	En Stripe
Correcto	Un Payment Record con el resultado guaranteed
Devuelto total o parcialmente	Una devolución en el Payment Record de ese pago
Fallido, cancelado o caducado	Nada. Solo se informan los pagos correctos.

Los pagos informados aparecen en Stripe en Transactions → Payments. Filtra por método de pago para ver solo Bizum:

Cuando desinstalas la app en Stripe, MONEI deja de informar y Bizum deja de estar disponible para esa cuenta de Stripe. Quita también bizum.customPaymentMethod de tu Payment Element.

Prueba tu integración

• Usa tu clave publicable de test de Stripe (pk_test_...). En un sandbox de Stripe, indica sandbox: true.
• Para probar la conexión antes de cambiar tu página de pago, paga en la tienda de demostración. Incluye https://docs.monei.com en los orígenes de una conexión de test.
• Usa los números de teléfono de prueba de Bizum. Un pago de prueba se completa en 1 a 3 minutos.
• Comprueba el pago en MONEI Dashboard → Pagos. Después comprueba su Payment Record en Stripe: payment_reference es el ID del pago de MONEI.

Preguntas frecuentes

¿Tengo que crear un tipo de método de pago personalizado en Stripe?

No. La app trae el tipo de Bizum de MONEI. createStripeBizum elige el tipo correcto para el modo live, el modo test y los sandboxes.

¿Qué páginas pueden cobrar con Bizum?

Solo las páginas de los orígenes de tu conexión (paso 1). Las URLs de retorno también deben estar en esos orígenes. Para cambiarlos, instala otra vez la app de MONEI para Bizum, inicia sesión en MONEI e introduce otra vez todos los orígenes y la URL de callback. Los orígenes y la URL de callback nuevos sustituyen a los anteriores.

¿Puedo conectar varias cuentas de MONEI a una cuenta de Stripe?

Una en cada modo. En cada modo (live y test) de una cuenta de Stripe, solo una cuenta de MONEI recibe los pagos de Bizum. Cuando conectas una segunda cuenta de MONEI en el mismo modo, MONEI rechaza la conexión. Para mover el pago con Bizum a otra cuenta de MONEI, contacta con support@monei.com.