📘

Only available to certain acquirers in Spain

Introduction

Bizum is a Spanish account-to-account payment method. It lets customers pay online using the Bizum service linked to their mobile number and a participating bank.

This guide explains how to offer Bizum through ECOM Checkout, receive the final payment outcome, and manage refunds.

Availability

Bizum is available only after Fiserv enables it for your store. Eligibility can depend on your merchant configuration, the transaction, and the customer's participating bank.

Before You Begin

Before integrating Bizum:

1. Ask your Fiserv representative to enable Bizum for each required store.
2. Submit eligible transactions in EUR.
3. Configure the Checkout success and failure return URLs.
4. Configure a server-to-server notification endpoint.
5. Make notification processing authenticated and idempotent.
6. Obtain approved sandbox credentials or test instructions before testing.

The browser return URL provides the customer journey outcome. Do not use it as the authoritative payment result. Use the server-to-server notification and, when needed, transaction inquiry to determine the final status.

Payment Flow

1. Your server creates a Checkout session using the standard sale flow.
2. Checkout displays payment methods enabled for the store.
3. The customer selects Bizum.
4. Checkout redirects the customer to the Bizum authentication experience.
5. The customer approves or declines the payment.
6. The customer returns to the success or failure URL you configured.
7. Fiserv sends the final transaction outcome to your notification endpoint.
8. Your server validates and processes the notification, then fulfils the order only after a successful final status.

Create a Checkout Session

Create the Checkout session with the standard SALE request. Include your normal merchant, order, amount, customer, locale, and redirect URL data.

{
  "transactionType": "SALE",
  "transactionAmount": {
    "total": 10.00,
    "currency": "EUR"
  },
  "checkoutSettings": {
    "locale": "es_ES",
    "redirectBackUrls": {
      "successUrl": "https://merchant.example/checkout/success",
      "failureUrl": "https://merchant.example/checkout/failure"
    }
  }
}

Use the Checkout URL returned in the session response to redirect the customer to Checkout. Refer to the Checkout session API documentation for the full request and response contract.

Preselect Bizum

By default, Checkout shows all payment methods enabled for the store. Your integration may be able to send the customer directly to Bizum by setting checkoutSettings.preSelectedPaymentMethod to 'Bizum'.

{
  "transactionType": "SALE",
  "transactionAmount": {
    "total": 10.00,
    "currency": "EUR"
  },
  "checkoutSettings": {
    "preSelectedPaymentMethod": "Bizum",
    "locale": "es_ES",
    "redirectBackUrls": {
      "successUrl": "https://merchant.example/checkout/success",
      "failureUrl": "https://merchant.example/checkout/failure"
    }
  }
}

Process the Payment Result

Your integration must support the expected transaction outcomes, including:

Handle Notifications Securely

Build your notification handler to:

1. Authenticate every notification according to the Checkout notification configuration.
2. Validate that the notification relates to the expected merchant and order.
3. Process the final transaction status before changing the order state.
4. Use the transaction identifier as an idempotency key so duplicate notifications are safe.
5. Tolerate delayed and out-of-order delivery.
6. Use transaction inquiry if the notification and customer return journey do not provide a conclusive result.

See Manage Checkout notifications for the shared notification contract and verification steps.

Refund a Bizum Payment

Submit a linked refund for a successful Bizum payment through the supported Payments API or operational channel for your account. Always reference the original transaction and use an idempotency key for each refund request.

Use secondary transactions endpoint with requestType 'ReturnTransaction' and ipgTransactionId or order with requestType 'ReturnTransaction' and orderId to initiate a linked refund.

Advanced Flows

The following capabilities require separate confirmation and enablement. Do not implement them from this page alone.

Merchant-Initiated Transactions

Merchant-initiated transactions use a reusable payment token created during an earlier customer-authorized sale.

Step 1: Create a Reusable Token

Add createToken.toBeUsedFor to the initial customer-authorized Bizum sale. The customer completes the normal redirect and authentication flow.

{
  "transactionOrigin": "ECOM",
  "transactionType": "SALE",
  "transactionAmount": {
    "total": 11.25,
    "currency": "EUR"
  },
  "paymentMethodDetails": {
    "createToken": {
      "toBeUsedFor": "UNSCHEDULED"
    }
  },
  "checkoutSettings": {
    "locale": "es_ES",
    "redirectBackUrls": {
      "successUrl": "https://httpbin.org/anything/success",
      "failureUrl": "https://httpbin.org/anything/failure"
    }
  }
}

After the initial sale is approved, retrieve the transaction by its
ipgTransactionId, or retrieve the order by orderId, and store the returned token. Store the token and approved consent metadata securely; never store customer credentials.

Step 2: Submit a Merchant-Initiated Sale

Send a new ApmSaleTransaction through the /payments endpoint. See link

SCA Exemption Requests

An SCA exemption is a request, not a guarantee that customer authentication will be skipped. Bizum, the provider, or the customer's bank may require authentication even when an exemption is requested.

The following example requests a low-value exemption during a Checkout sale:

{
  "transactionOrigin": "ECOM",
  "transactionType": "SALE",
  "transactionAmount": {
    "total": 11.25,
    "currency": "EUR"
  },
  "paymentMethodDetails": {
    "scaExemptionType": "LOW_VALUE_EXEMPTION"
  },
  "checkoutSettings": {
    "locale": "es_ES",
    "redirectBackUrls": {
      "successUrl": "https://merchant.example/checkout/success",
      "failureUrl": "https://merchant.example/checkout/failure"
    }
  }
}

If the field is omitted, Checkout follows the normal Bizum authentication flow. Only use exemption values approved for Bizum; an invalid or unsupported value must be handled as a request-validation error. Your integration must also handle a provider decision that requires customer authentication.

Split Authentication and Sale Authorization

Split authentication separates customer authentication from the later financial sale authorization. It is not a way to divide one purchase between payment methods or recipients. This feature must be enabled for your store and acquiring
agreement. The sale authorization can follow the authentication by up to 30 days.

Step 1: Authenticate the Customer

Use transactionType 'PAYER-AUTH' while creating the checkout.

{
  "transactionOrigin": "ECOM",
  "transactionType": "PAYER-AUTH",
  "transactionAmount": {
    "total": 11.25,
    "currency": "EUR"
  },
  "checkoutSettings": {
    "locale": "es_ES",
    "redirectBackUrls": {
      "successUrl": "https://httpbin.org/anything/success",
      "failureUrl": "https://httpbin.org/anything/failure?"
    }
  }
}

Store the returned payer-auth ipgTransactionId. After the browser returns, retrieve that transaction until it has both transactionResult=APPROVED and transactionState=AUTHORIZED. Do not submit the sale while authentication is
WAITING, DECLINED, or FAILED.

Step 2: Submit the Sale Authorization

Submit a new ApmSaleTransaction to /payments endpoint. Set the top-level ipgTransactionId to the approved payer-auth transaction ID. The example omitsorder.orderId, because the Gateway uses the order from the referenced
authentication transaction.

{
  "requestType": "ApmSaleTransaction",
  "transactionAmount": {
    "total": 11.25,
    "currency": "EUR"
  },
  "paymentMethod": {
    "type": "BIZUM"
  },
  "storeId": "{{storeId}}",
  "ipgTransactionId": 1234567890,
  "transactionOrigin": "ECOM"
}

Use a new Client-Request-Id, timestamp, and signature for the sale request. Use the same store that created the payer-auth transaction. No second customer redirect is expected because Bizum authentication is already complete.

The successful response creates a new sale transaction. Fulfil the order only when the sale, rather than the payer-auth transaction, reports transactionResult=APPROVED and transactionState=CAPTURED. Retain both transaction IDs for reconciliation and use the sale transaction ID for returns.