Payment-method icon

Bizum for API only

Add Bizum to your API-only integration.

You can add Bizum to your existing integration. The following instructions show only what you must add to your integration specifically for Bizum.

If an instruction on this page corresponds with a step in the main integration guide, it includes a link to corresponding step of the main integration guide.

Requirements

Requirement Description
Integration type Make sure that you have an existing API-only integration.
Redirect handling Make sure that your existing integration is set up to handle the redirect.
action.type: redirect.
Setup steps Before you begin:

How it works

  1. The shopper selects Bizum as the payment method.
  2. The shopper enters their details in the payment form that you build.
  3. When you make the payment request, you include additional information about the items that the shopper intends to purchase.
  4. Your existing integration setup will handle the redirect.

Build your payment form

Include Bizum in the list of available payment methods. There are no additional fields that you have to include in your form.

You can download the logo for Bizum to use in your form.

Get Bizum as an available payment method

When you make the /paymentMethods to get available payment methods, specify the following so that Bizum is included in the response.

Parameter Values
countryCode ES
amount.currency EUR

Add additional parameters to your /payments request

When you make a payment, add the following parameters:

Parameter Required Description
reference -white_check_mark- Your unique reference for the payment.
Your reference can include upper and lower case alphanumeric characters and must be between 4 and 125 characters long, matching the following regular expression: ^[a-zA-Z0-9]{4,125}$)

The response includes action.type: redirect.

Handle the redirect

  1. To complete the payment, make a POST request with the following elements:

    • Redirect the shopper to the action.url returned in the /payments response.
    • Use content type x-www-form-urlencoded to include the parameters from the data object as key-value pairs.
      Bizum requires the x-www-form-urlencoded content type.

  2. After the shopper is redirected back to your website, check the payment result by making a POST /payments/details request, specifying:

    • details: Object that contains the URL-decoded redirectResult returned when the shopper was redirected back to your site.

    You receive a /payments/details response containing:

    • resultCode: Use this to present the result to your shopper.
    • pspReference: Our unique identifier for the transaction.

Show the payment result

Use the resultCode that you received in the /payments/details response to present the payment result to your shopper.

You can receive the following resultCode values for Bizum:

resultCode Description Action to take
Authorised The shopper completed their payment, and it has been sent to the bank for processing. In most cases, this means that you will receive the funds. If you are using manual capture, you also need to capture the payment. Inform the shopper that the payment has been successful.
Cancelled The shopper cancelled the payment while on their bank's website. Ask the shopper whether they want to continue with the order, or ask them to select a different payment method.
Pending or
Received		 The shopper has completed the payment but the final result is not yet known. Inform the shopper that you have received their order, and are waiting for the payment to be completed.
You will receive the final result of the payment in an AUTHORISATION webhook.
Refused The payment was refused by the shopper's bank. Ask the shopper to try the payment again using a different payment method.

You also receive the outcome of the payment asynchronously in a webhook. If the shopper failed to return to your website or app, wait for notification webhooks to know the outcome of the payment. You can receive the following webhooks for Bizum:

eventCode success field Description Action to take
AUTHORISATION false The transaction failed. Cancel the order and inform the shopper that the payment failed.
AUTHORISATION true The shopper successfully completed the payment. Inform the shopper that the payment has been successful and proceed with the order.

Test and go live

To test Bizum payments:

  • Use telephoneNumber: 700 000 000.

  • Note that the payments amount value determines the outcome:

    Amount Outcome
    Less than 15 Payment is authorized
    From 15 to 50 Payment is refused
    From 50 to 1000 Payment is authorized
    More than 1000 Payment is refused

  • Check the status of Bizum test payments in your Customer Area > Transactions > Payments.

See also