Bizum API Rest

Bizum API Rest is a fully transparent, backend-to-backend integration that processes payments without redirecting the customer to an external gateway. Getnet provides no hosted payment page, so you build the checkout interface your customer sees. The customer gets a push notification in the Bizum app and approves the transaction there. The Global API supports Bizum API Rest across four flows:

• Single-step flow – authorize and capture the payment in one request using INSTANT_TRANSFER_REST.
• Two-step flow – validate the customer's Bizum account using INSTANT_TRANSFER_PREAUTH_REST. Then capture the payment later (within 30 days), when you are ready to fulfill the order.
• Recurring flow – charge the customer again without asking them to approve each payment. The customer approves only the first payment in the Bizum app.
• Payout flow – send funds to a customer using only their Bizum-registered phone number.

Important: Purchase flows are asynchronous, so the first API response returns WAITING. This is expected, not an error: the status changes to AUTHORIZED only after the customer approves in the Bizum app.

Available features

Use the matrix below to confirm the scenarios currently supported for Bizum API Rest.

Shared characteristics

The table below summarizes the shared behavior and requirements across all Bizum API Rest flows.

Requirements

Before you integrate Bizum API Rest:

• Generate an access token through the Authentication endpoint. Payment requests and Bizum Check use the same credentials and token.
• Collect the customer's Bizum-registered phone number before you start the payment or run Bizum Check.
• Register webhook events through the Webhooks API to receive asynchronous status updates for purchase flows.
• Review the market requirements before going live: Currency codes, Document types, and Local taxes and regulations.

Bizum transactions are capped at €15,000. The customer's bank can enforce a lower limit, so the bank may still refuse a transaction below €15,000.

Bizum Check (pre-payment query)

Bizum Check is a REST query that tells you which Bizum payment options a customer has before you create the payment. You send the customer's phone number, and Getnet asks Bizum for that customer's capabilities. Use the result to pick the right payment flow and avoid payment attempts that can't succeed.

Bizum Check works for any seller with Bizum enabled. It uses the same credentials as your payment requests and needs no extra activation. It supports three queries:

• RTP eligibility – check whether the customer has Bizum and whether their account supports RTP.
• Recurring identifier validation – check whether a cof_transaction_id from an initial recurring payment is still valid. See Validate a recurring identifier.
• SCA exemptions query – get the SCA exemptions that the customer's account supports.

Important: Bizum Check is not an authorization. It creates no payment, charge, or settlement, and it doesn't appear in your reports. A positive result tells you which flow to use. It doesn't guarantee payment approval.

How Bizum Check works

The table below summarizes the behavior shared by all Bizum Check queries.

Bizum Check fits between the customer's choice of Bizum and the payment request:

1. The customer selects Bizum at checkout and enters their phone number.
2. You send a Bizum Check with the customer's phone number.
3. You read the result and pick a flow: Bizum API Rest, Bizum Redirect, or another payment method.
4. You create the payment in the flow you picked.
5. Getnet notifies you of the payment result.

You can also run a check outside checkout. For example, validate a recurring identifier before a subsequent payment. Another use is to re-check a stored phone number and see whether it still supports RTP.

Bizum Check request fields

All Bizum Check queries use the same endpoint and body structure. Add the conditional fields to run the recurring identifier validation or the SCA exemptions query.

Bizum Check response fields

All Bizum Check queries return the same response structure. The response leaves out fields with no value.

Send the RTP check

Run this query at checkout. It shows whether you can charge the customer with Bizum API Rest, Bizum Redirect, or neither. Call the Bizum Check endpoint with the required fields only.

For a customer with Bizum and RTP, the API returns the following response:

Pick the payment flow

Validate a recurring identifier

Query SCA exemptions

Handle Bizum Check errors

For the full list of error codes, see the Errors reference.

Bizum Check best practices

Follow these recommendations when you implement Bizum Check:

• Run the check after the customer selects Bizum and before you create the payment.
• Read both status and message. The two negative results share the KO status.
• Validate a stored cof_transaction_id before each subsequent recurring payment.
• Use a new idempotency_key for every check.
• Don't treat an OK result as a payment approval. Always confirm the payment result through webhooks or the Get Transaction endpoint.

Request structure

All Bizum API Rest purchase requests share the same top-level body structure and the same endpoint. The table below documents the common fields. Each flow section describes its flow-specific fields.

Billing address fields

Single-step flow (immediate capture)

Use this flow when you can fulfill the order immediately. A single request authorizes and captures the payment. The customer receives a push notification in the Bizum app to approve the transaction.

1. Create the payment request

2. Handle the asynchronous status

3. Verify the status

Two-step flow (validation + capture)

Choose this flow when you need to validate the customer's Bizum account first and capture the payment after fulfillment. This flow validates the account in one step and lets you capture within 30 days.

Important: An authorization does not "hold" funds in Bizum. If the customer's balance drops before you capture the payment, the transaction fails due to insufficient funds.

1. Validate the payment

2. Capture the validated payment

To complete the sale, call the Capture endpoint. You can capture the payment within 30 days of validation.

A successful capture returns the following response:

3. Confirm settlement

Recurring flow

Use this flow to charge a customer again without asking them to approve each payment in the Bizum app. The customer approves only the first payment. You then send its recurring transaction identifier with every later payment.

A recurring sequence starts with an initial payment that the customer approves. You then create subsequent payments on your own schedule:

1. The customer selects Bizum at checkout.
2. You create the initial payment. Getnet sends a push notification to the customer's Bizum app.
3. The customer approves the payment and the recurrence in the app.
4. Getnet notifies you of the result.
5. You query the payment records to get the recurring transaction identifier, cof_transaction_id.
6. Optionally, you validate the identifier with Bizum Check before a subsequent payment. See Validate a recurring identifier.
7. You create each subsequent payment with that identifier. Getnet charges the customer with no action from them.

Recurring request fields

1. Create the initial payment

2. Confirm the initial payment

The initial payment uses the same webhook events and statuses as a single-step payment. See Webhooks and Status Reference.

If you do not receive a webhook, poll the Get Transaction endpoint as a fallback.

3. Get the recurring transaction identifier

Before a subsequent payment, you can confirm that the identifier is still valid with Bizum Check. See Validate a recurring identifier.

4. Create subsequent payments

For each later charge, call the Create – Authorize endpoint with these values:

• credentials_on_file_type set to RECURRING_PAYMENT
• transaction_id set to the cof_transaction_id you stored in Step 3
• amount equal to the initial payment amount

You don't need to send the customer's phone number on subsequent payments. The request below shows the minimum body.

Handle recurring errors

Recurring best practices

Follow these recommendations when you implement Bizum recurring payments:

• Wait for the initial payment to reach AUTHORIZED before you query the cof_transaction_id.
• Store the cof_transaction_id securely and link it to the customer's account.
• Validate a stored cof_transaction_id with Bizum Check before a subsequent payment, so you don't send a charge that will fail. See Validate a recurring identifier.
• Send the same amount on every subsequent payment. To charge a different amount, create a new initial payment.
• Use a new idempotency_key, payment_id, and order_id for every subsequent payment.
• Use webhooks in production and status polling only as a fallback.

For refunds of initial or subsequent payments, see the Refund a Payment guide.

Payout flow

1. Create the payout request

Webhooks

To receive asynchronous status updates for Bizum API Rest transactions, register webhook events through the Webhooks API. Bizum API Rest webhook events differ from card payment webhooks. Register each event below to cover the full transaction lifecycle.

Status reference

The table below describes the full status lifecycle for Bizum API Rest transactions.

Test Bizum API Rest payments

When you test Bizum API Rest payments in the sandbox environment, use the following credentials and amounts to simulate different scenarios.

Test phone number

Use the following phone number to test Bizum API Rest transactions in the sandbox environment:

Test amounts

Different transaction amounts simulate different payment outcomes in the sandbox environment. Use the table below to test various scenarios:

These test scenarios are only available in the sandbox environment. In production, the outcome depends on the customer's actual Bizum account status and balance.

Test recurring payments

Use the test phone number on the initial payment. The sandbox approves it automatically, so you do not need a real device. Test the following scenarios before going live:

Next steps

Use the resources below to continue your integration.

• Refund a Payment guide
• Bizum Redirect
• Bizum official website