Bizum

Bizum is a payment service launched by Spanish banks in 2016 that lets users make payments from their smartphone. By accepting Bizum payments, your customers can pay securely from their phones, on your website or mobile app.

Accept Bizum payments using the Hosted Payment Page or Bizum Component. No extra configuration is needed for the Hosted Payment Page.

The Bizum Component renders a Bizum button on your payment page. When customers select Bizum, an overlay appears where they enter their registered phone number to complete the payment.

Availability

Bizum is a Spanish peer-to-peer (P2P) payment app that customers connect to their Spanish bank account () to send money to contacts or complete online purchases. Bizum is therefore available to customers whose bank account is held in Spain and is enrolled in Bizum.

Activation

Bizum is activated automatically once your account is approved — you do not need to request it. Activation typically takes 48–72 hours on working days.

To complete activation, your website must be live and publicly accessible — our team verifies that a product can be added to the shopping cart. If your site is password-protected, provide the credentials during onboarding or by opening a Support Team request, otherwise Bizum will not be activated.

Once activated, Bizum appears in MONEI Dashboard → Settings → Payment methods. It then becomes available in the Hosted Payment Page, and you can also render the Bizum Component directly on your site. The Bizum button appears when customers reach your payment page.

Payment methods page in the MONEI Dashboard settings, with Bizum listed as enabled

If Bizum has not been activated 7 days after your account was approved and your website is publicly available, contact our Support Team.

Fees

Bizum is charged a flat 1.29% + €0.25 MONEI fee per successful transaction, plus a €0.17 acquiring fee. For current pricing, see MONEI fees.

Payouts

Bizum transactions are settled to the IBAN on your MONEI account.

Refunds

Bizum transactions can be refunded within 180 days after the initial transaction has been processed. Refunds may fail if:

• The customer has disconnected their Bizum account.
• The customer has changed the link between their phone number and IBAN.
• The issuing bank is experiencing internal issues with Bizum notifications.

MONEI doesn't charge to issue a refund. If you refund within the same weekly billing cycle as the sale, the sale and refund cancel out and you pay no fees on it. The €0.17 acquiring fee from the original payment isn't returned by the network, so a refund in a later cycle leaves it deducted from your settlements. See MONEI fees.

Limits

Online Bizum transactions have no maximum amount limit. If a transaction fails, it may be because the issuing bank imposes its own limit or because the customer lacks sufficient funds. Unlike Bizum's peer-to-peer (P2P) limits between individuals, there is no monthly cap on the number of online purchases a customer can make with Bizum.

Bizum has its own limits for peer-to-peer (P2P) transactions between individuals. Learn more about Bizum limits for businesses.

Send payouts to customers

You can also use Bizum to send money to a customer's phone number with a payout. Payouts are a gated feature: they must be enabled for your account by MONEI's risk team and are paid from a prefunded account balance. See Send payouts to customers for how it works.

Test your integration

• Use your test mode Account ID and API Key.
• Use the test phone numbers.
• You can check the status of a test payment in your MONEI Dashboard → Payments (in test mode).

Integration

1. Create a Payment Server-side

Create a Payment on your server with an amount and currency. Always decide how much to charge on the server side, a trusted environment, as opposed to the client. This prevents malicious customers from being able to choose their own prices.

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"
}'

(Replace YOUR_API_KEY with your actual MONEI API key)

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

The following parameters are required:

• amount positive integer - Amount intended to be collected by this payment. A positive integer representing how much to charge in the (e.g., 100 cents to charge 1.00 USD)
• currency string - Three-letter ISO currency code, in uppercase. Must be a supported currency.
• orderId string - An order ID from your system. A unique identifier that can be used to the payment with your internal system.
• callbackUrl string - The URL to which a payment result should be sent asynchronously.

Check all available request parameters.

Included in the returned Payment object is a payment id, which is used on the client side to securely complete the payment process instead of passing the entire Payment object.

2. Add Bizum to your payment page Client-side

Include monei.js on your checkout page by adding the script tag to the head of your HTML file.

checkout.html

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

Add MONEI Bizum Component to your payment page. Create empty DOM node (container) with unique ID in your payment form.

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>

Initialize Bizum Component

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');

note

Bizum Component is also available as a React, Vue, Angular, and Svelte component.

Check the MONEI JS Reference for more options.

3. Confirm the payment Client-side

To complete the payment you need to confirm it using monei.js confirmPayment function.

You need to provide a paymentId (obtained in step 1) and paymentToken generated with Bizum Component. You can also provide additional parameters like customer.email. Check all available parameters.

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);
  }
}

note

As an alternative process you can submit generated paymentToken to your server and then confirm payment on the server-side.

4. Process Webhook Notification Server-side

After the client-side interaction and any necessary background processing, MONEI sends the final, authoritative payment status via an asynchronous HTTP POST request to the callbackUrl you provided in Step 1.

The request body contains the full Payment object in JSON format.

This webhook is the only reliable way to confirm the definitive payment outcome.

Crucially, you must:

1. Verify the MONEI-Signature header included in the request. This confirms the webhook genuinely came from MONEI. See the Verify Signatures guide for implementation details.
2. Return a 200 OK HTTP status code immediately upon receiving the webhook to acknowledge receipt. Any other status code tells MONEI the notification failed.

If MONEI doesn't receive a 200 OK, it will retry sending the webhook.

Once the signature is verified, inspect the status field in the Payment object (SUCCEEDED, FAILED, CANCELED, etc.) to determine whether to fulfill the order or handle the failure.

Before you go live

• Make sure that you are using live (production) mode Account ID and API Key.
• Make sure that you have connected your Bizum business account in MONEI Dashboard.

Additional information

Payment status monitoring

MONEI actively monitors Bizum transaction status to ensure consistency between the payment gateway and processor, preventing discrepancies that could affect merchants or consumers.

Pre-authentications

Bizum supports pre-authentications (transactionType: AUTH) to verify the Bizum number belongs to the account holder without holding funds. After successful authentication, you have up to 30 days to the payment. Both full and partial captures are supported. If insufficient funds are available at capture time, the transaction will not proceed. No additional is required during capture.

Pre-authentications are available only if the customer's bank supports the RTP (Request to Pay) flow.

Subscriptions

You can use Bizum for subscriptions or , similar to card-based subscriptions. Set Bizum as the payment method when creating a subscription through the MONEI API.

Key considerations:

• Bank coverage is still being deployed, with 90%+ user coverage targeted. If the customer's bank does not support Bizum subscriptions, the subscription will not work. Confirm this directly with your customer.
• The customer authorizes only the first payment. Subsequent payments are processed automatically via the MONEI subscriptions engine, or you can manage them manually using the recurring payments API.
• Only one recurring payment per month can be made through Bizum, and the subscription amount cannot be changed after the first payment.

Payment Request

You can send a payment request directly to the customer's phone. If the phone number is registered with Bizum, the customer receives a push notification to confirm the payment in their banking app. If not, they receive a payment link via WhatsApp. This feature works independently of the UI Component.

Example of a Bizum push notification:

Common questions

Do Bizum payments support pre-authorizations (SALE vs AUTH)?

Bizum has two transaction types:

• SALE is the automatic-capture transaction type, where the payment is captured immediately. It generally happens without friction.
• AUTH is the pre-authentication transaction type. It verifies that the Bizum number belongs to the account holder without holding funds — the amount is not blocked and the customer's balance is not verified, so success at capture is not guaranteed.

For AUTH, you have up to 30 days after a successful authentication to capture the payment (full or partial captures are supported), and no additional SCA is required during capture. See Pre-authentications for details. Pre-authentications are available only if the customer's bank supports the RTP (Request to Pay) flow.

When will Bizum be activated?

Bizum is activated automatically once your account is approved — you do not need to request it. Activation typically takes 48–72 hours on working days.

To complete activation, your website must be live and publicly accessible — our team verifies that a product can be added to the shopping cart. If your site is password-protected, provide the credentials during onboarding or by opening a Support Team request.

Once activated, Bizum appears in MONEI Dashboard → Settings → Payment methods and becomes available on your payment page. See Activation for the full details. If Bizum has not been activated 7 days after your account was approved and your website is publicly available, contact our Support Team.