Skip to main content

Accept Bizum in Stripe with the MONEI app

The MONEI app for Stripe adds Bizum to your own Stripe Payment Element as a custom payment method. MONEI processes the payment under its own Bizum license and the funds to your MONEI account. Then MONEI reports each successful payment and each refund to your Stripe account through the Payment Records API. Bizum shows next to your other payments in Stripe.

What you build

You add Bizum to the Payment Element of your checkout page with monei.js. You do not need server code or a MONEI API key to take the payment: MONEI creates it and reports it to Stripe. Your server only reads the result to fulfil the order. You do not create a custom payment method type in Stripe: the app brings MONEI's.

How it works​

Before you begin​

1. Connect your Stripe account​

While the app is in pilot, write to support@monei.com to join the pilot. MONEI support sends you the install link. Open it, install the app in Stripe, sign in to MONEI, pick the account and enter the shop origins:

  • To test first, install the app in a Stripe sandbox or in the test mode of your Stripe account. A test install offers only the MONEI accounts that have a valid test account.
  • A live install needs an approved MONEI account.
  • The shop origins are the origins of your checkout page and of your return pages, for example https://shop.example.com. MONEI accepts Bizum payments only from these origins, and returns the customer only to them.
  • Optional: a callback URL. MONEI sends the result of each Bizum payment to it (see step 3).

Click Connect. The page shows the connection and the createStripeBizum code for step 2 with your Stripe account ID.

Your MONEI test mode connects to a Stripe sandbox or to the test mode of your Stripe account. Your MONEI live mode connects to the live mode of your Stripe account.

2. Add Bizum to the Payment Element Client-side​

Include monei.js on your checkout page:

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

Create the Bizum handler with createStripeBizum. Add its custom payment method to stripe.elements(). When the customer submits and Bizum is the selected method, call pay():

checkout.js
const bizum = monei.createStripeBizum({
  publishableKey: 'pk_test_...', // the same key as Stripe.js; pk_live_ = live mode
  stripeAccount: 'acct_...', // your Stripe account
  sandbox: false // true when acct_... is a Stripe sandbox
});

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)) {
    // Other payment methods: your usual stripe.confirmPayment flow.
    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 checkout is not available, or the customer closed the Bizum window.
  }
});

pay() opens the Bizum window on your page. The customer enters the phone number and approves the payment in their banking app. When the payment needs a redirect, the customer returns to completeUrl or failUrl. The reference gives all options and the return values.

3. Fulfil the order Server-side​

The result of pay() and the redirect come from the browser, and a customer can change them. Fulfil the order only from one of these sources:

  • The MONEI callback. When you gave MONEI a callback URL, MONEI posts the final Payment object to it. Verify the MONEI-Signature header first.
  • The Stripe Payment Record. The record holds your order ID in metadata.order_id, the MONEI payment ID in metadata.monei_payment_id and in processor_details.custom.payment_reference, and the paid amount.

The page sets the amount, so fulfil an order only when the paid amount matches the order.

4. Refunds​

Refund the payment in MONEI, from MONEI Dashboard → Payments or with the refund API. Stripe does not process the Bizum payment, so a refund cannot start in Stripe. MONEI reports each full or partial refund to the Payment Record of the payment.

What MONEI reports to Stripe​

MONEI paymentIn Stripe
SucceededA Payment Record with the outcome guaranteed
Refunded or partially refundedA refund on the Payment Record of that payment
Failed, canceled or expiredNothing. Only successful payments are reported.

Reported payments appear in Stripe under Transactions → Payments. Filter by payment method to see only Bizum:

When you uninstall the app in Stripe, MONEI stops the reports, and Bizum checkout stops for that Stripe account. Remove bizum.customPaymentMethod from your Payment Element too.

Test your integration​

  • Use your Stripe test publishable key (pk_test_...). In a Stripe sandbox, set sandbox: true.
  • To test the connection before you change your checkout page, pay on the demo shop. Include https://docs.monei.com in the origins of a test connection.
  • Use the test Bizum phone numbers. A test payment completes after 1 to 3 minutes.
  • Check the payment in MONEI Dashboard → Payments. Then check its Payment Record in Stripe: payment_reference is the MONEI payment ID.

Common questions​

Do I create a custom payment method type in Stripe?​

No. The app brings MONEI's Bizum type. createStripeBizum selects the right type for live mode, test mode and sandboxes.

Which pages can take a Bizum payment?​

Only pages on the origins of your connection (step 1). The return URLs must be on these origins too. To change them, open the install link again: click Open the install link on the page that MONEI shows after you click Connect, or write to support@monei.com for the link. Sign in to MONEI and enter all the origins and the callback URL again. The new origins and callback URL replace the old ones.

Can I connect several MONEI accounts to one Stripe account?​

One in each mode. In each mode (live and test) of a Stripe account, only one MONEI account takes the Bizum payments. When you connect a second MONEI account in the same mode, MONEI refuses the connection. To move Bizum checkout to another MONEI account, contact support@monei.com.

Tags:
Last updated on