Bizum
Bizum is a Spanish instant mobile payment solution. Accept Bizum payments to let your customers make secure payments from the convenience of their smartphones.
You can start accepting Bizum payments on the Web using Hosted Payment Page or Bizum Component. No additional configuration is required to use Bizum in Hosted Payment Page.
Our Bizum Component renders a Bizum button to your payment page. When a customer selects Bizum, the component presents a Bizum overlay, where a customer can enter his phone number registered in Bizum to complete the payment process.
Bizum transactions can be as high as 1.500 EUR. Any transaction exceeding this amount is rejected.
With Bizum, you can authorize and capture payments separately. After the payment is authorized, you have up to 30 days to capture it. Payment authorizations available only if RTP (Request to Pay) flow is supported by the customer's bank.
Bizum transactions can be refunded within 365 days after the initial transaction has been processed.
note
You can send payment request directly to the customer's phone. If Bizum payment method is available and the phone number is registered in Bizum, the customer will get a push notification to confirm the payment directly in the banking app, otherwise, he will receive a link to pay via WhatsApp. This feature does not require UI Component.
Before you begin
This page explains how to add Bizum to your payment page. To accept Bizum payments please contact our Support Team to configure Bizum.
Before you start, you need to make sure that you have Bizum enabled in MONEI Dashboard → Settings → Payment Methods.
To 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
- Node.js
- PHP
curl --request POST 'https://api.monei.com/v1/payments' \
--header 'Authorization: pk_test_3c140607778e1217f56ccb8b50540e00' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": 110,
"currency": "EUR",
"orderId": "14379133960355",
"description": "Test Shop - #14379133960355",
"customer": {
"email": "john.doe@microapps.com"
},
"callbackUrl": "https://example.com/checkout/callback"
}'
const {Monei} = require('@monei-js/node-sdk');
const monei = new Monei('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');
monei.payments.create({
amount: 110,
currency: 'EUR',
orderId: '14379133960355',
description: 'Test Shop - #14379133960355',
customer: {
email: 'john.doe@microapps.com'
},
callbackUrl: 'https://example.com/checkout/callback'
});
$monei = new Monei\MoneiClient('pk_test_36cf3e8a15eff3f5be983562ea6b13ec');
$monei->payments->create([
'amount' => 110,
'currency' => 'EUR',
'orderId' => '14379133960355',
'description' => 'Test Shop - #14379133960355',
'customer' => [
'email' => 'john.doe@microapps.com'
],
'callbackUrl' => 'https://example.com/checkout/callback'
]);
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 smallest currency unit (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 reconcile 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.
<head>
<title>Checkout</title>
<script src="https://js.monei.com/v2/monei.js"></script>
</head>
Add MONEI Bizun Component to your payment page. Create empty DOM node (container) with unique ID in your payment form.
<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
// Create an instance of the Bizum component.
var bizum = monei.Bizum({
paymentId: '{{payment_id}}',
onSubmit(result) {
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 and Vue component. Check out our examples.
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 PayPal Component. You can also provide additional parameters like customer.email
. Check all available parameters.
// Confirm the payment
function moneiTokenHandler(token) {
return monei
.confirmPayment({paymentId: "{{payment_id}}", paymentToken: token})
.then(function (result) {
// IMPORTANT: some banks do not support new RTP (Request to Pay) flow
// and require a redirect to the hosted page to complete the payment
// You should check if mustRedirect is true and redirect the customer
if (result.nextAction && result.nextAction.mustRedirect) {
window.location.assign(result.nextAction.redirectUrl);
}
// 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(function (error) {
console.log(error);
});
}
note
As an alternative process you can submit generated paymentToken
to your sever and then confirm payment on the server-side.
caution
Bizum is migrating to the new payment request flow with the push notification to the banking app that will allow confirming the payment without the redirect. This is what's known as RTP (Request to Pay). This flow is not fully supported by all the banks yet. It is important to check the mustRedirect
flag in the response to determine if the redirect is required.
4. An asynchronous request is sent to your server.
MONEI will notify you about the payment status by sending an HTTP POST request to the callbackUrl
. The request body will contain full payment object in JSON format.
This ensures that you get the payment status even when customer closed the browser window or lost internet connection.
The request also contains a MONEI-Signature
header. Verify this signature to confirm that received request is sent from MONEI.
To acknowledge receipt of the request, your endpoint must return a 200
HTTP status code to MONEI. All other response codes, including 3xx
codes, indicate to MONEI that you did not receive the event.
If MONEI does not receive a 200
HTTP status code, the notification attempt is repeated. After multiple failures to send the notification over multiple days, MONEI marks the request as failed and stops trying to send it to your endpoint.
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.