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. Unlike redirect-based solutions, the merchant is responsible for building the interface presented to the end customer, as Getnet provides no hosted payment page. Instead of an HTML redirect form, the customer receives a push notification directly in the Bizum mobile 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.
• Payout flow – send funds to a customer using only their Bizum-registered phone number, with no card data required.

Requirements

Before integrating Bizum API Rest:

• Generate an access token through the Authentication endpoint.
• Collect the customer’s Bizum-registered phone number before initiating the payment.
• Register webhook events via the Webhooks API to receive asynchronous status updates for purchase flows.

Bizum API Rest is only available in Spain (EUR). Contact your Account Manager to enable this payment method for your seller account.

Maximum amount: Bizum transactions are capped at €15,000. The customer’s bank can enforce a lower limit, so a transaction below €15,000 may still be refused.

Use Cases Specifics

When integrating any Getnet solution, market-specific requirements apply. Bizum API Rest is only available in Spain and only for EUR currency. Review the resources below before going live:

• Currency codes
• Document types
• Local taxes and regulations

Testing Bizum API Rest Payments

When testing 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 for testing Bizum API Rest transactions in the sandbox environment:

Test Phone Number: 34700000000

In the sandbox (UAT) environment, this phone number automatically bypasses the Bizum app OTP and authentication step, allowing the transaction to transition from WAITING to AUTHORIZED without requiring a real device. In production, customers must approve the transaction manually through the Bizum banking app.

The sandbox auto-approval behavior is UAT-only. Always implement webhook event handling or polling for production purchase flows.

Test Amounts

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

These amounts apply only to INSTANT_TRANSFER_REST and INSTANT_TRANSFER_PREAUTH_REST flows. Payout transactions (PAYOUT) are always approved in the sandbox regardless of the amount.

These test scenarios are only available in the sandbox environment. Production transactions are processed based on the customer’s actual Bizum account status and balance.

Shared Characteristics

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

Unlike the Redirect flow, Bizum API Rest responses do not include _links, merchant_data, signature, or signature_version in additional_data. There is no HTML form to build and no gateway URL to redirect the customer to.

Available Features

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

To enable Bizum API Rest, work with your Account Manager, who validates eligibility and activates the payment method.

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; flow-specific fields are described in each section.

Billing Address Fields

Single-step Flow (Immediate Capture)

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

1. Create the Payment Request

To create the payment, call the Create – Authorize endpoint and set payment_method to INSTANT_TRANSFER_REST.

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "idempotency_key": "{{$guid}}",
  "request_id": "{{$guid}}",
  "order_id": "ORDER-10187385",
  "data": {
    "amount": 400,
    "currency": "EUR",
    "payment": {
      "payment_id": "pay-001",
      "payment_method": "INSTANT_TRANSFER_REST",
      "brand": "BIZUM",
      "soft_descriptor": "BIZUM STORE"
    },
    "additional_data": {
      "customer": {
        "email": "customer@example.com",
        "document_number": "50506468",
        "document_type": "dni",
        "name": "Jose da Silva",
        "phone_number": "34700000000",
        "billing_address": {
          "street": "Calle Mayor",
          "number": "10",
          "complement": "2A",
          "district": "Centro",
          "city": "Madrid",
          "state": "MD",
          "country": "ES",
          "postal_code": "28001"
        }
      }
    }
  }
}'

The API immediately returns a WAITING status. This is the expected synchronous response, and the transaction is not complete until the customer approves it in the Bizum app.

{
  "idempotency_key": "63c7f8ee-51a6-470d-bb76-ef762b62bfb9",
  "seller_id": "2ab3e585-3607-467e-b2e8-420fcd45f48e",
  "payment_id": "882a062580d7625c2e0d5f9ge5919gf7",
  "order_id": "ORDER-10187385",
  "amount": "400",
  "currency": "EUR",
  "status": "WAITING",
  "received_at": "2025-11-03T14:18:59.991Z",
  "reason_code": "00",
  "reason_message": "Waiting payment flow."
}

2. Handle the Asynchronous Status

After the request is created, the customer receives a push notification in the Bizum app. Once they approve the transaction, the platform delivers a status update via the Webhooks API. The status transitions from WAITING to AUTHORIZED, then immediately to CAPTURED for single-step payments.

3. Verify Status

To verify the final status, poll the Get Transaction endpoint as a fallback and check for the CAPTURED status. Prefer webhooks over polling for production implementations.

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 allows you to capture within 30 days.

1. Validate the Payment

To validate the payment, call the Create – Authorize endpoint and set payment_method to INSTANT_TRANSFER_PREAUTH_REST.

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "idempotency_key": "{{$guid}}",
  "request_id": "{{$guid}}",
  "order_id": "ORDER-10187386",
  "data": {
    "amount": 400,
    "currency": "EUR",
    "payment": {
      "payment_id": "pay-001",
      "payment_method": "INSTANT_TRANSFER_PREAUTH_REST",
      "brand": "BIZUM",
      "soft_descriptor": "BIZUM STORE"
    },
    "additional_data": {
      "customer": {
        "email": "customer@example.com",
        "document_number": "50506468",
        "document_type": "dni",
        "name": "Jose da Silva",
        "phone_number": "34700000000",
        "billing_address": {
          "street": "Calle Mayor",
          "number": "10",
          "complement": "2A",
          "district": "Centro",
          "city": "Madrid",
          "state": "MD",
          "country": "ES",
          "postal_code": "28001"
        }
      }
    }
  }
}'

The API returns a WAITING status immediately. After the customer approves in the Bizum app, the platform delivers a status update via the Webhooks API and the status transitions to AUTHORIZED.

{
  "idempotency_key": "73d8g9ff-62b7-581e-cc87-fg873c73cgc0",
  "seller_id": "2ab3e585-3607-467e-b2e8-420fcd45f48e",
  "payment_id": "777f851479c64541bd9c4e8fd4808fe9",
  "order_id": "ORDER-10187386",
  "amount": "400",
  "currency": "EUR",
  "status": "WAITING",
  "received_at": "2025-11-03T14:18:59.991Z",
  "reason_code": "00",
  "reason_message": "Waiting payment flow."
}

Once the customer approves in the Bizum app, the Webhooks API delivers an update with "status": "AUTHORIZED". Use the payment_id from the initial response to call the Capture endpoint.

2. Capture the Validated Payment

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

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments/capture \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "idempotency_key": "{{$guid}}",
  "payment_id": "777f851479c64541bd9c4e8fd4808fe9",
  "payment_method": "INSTANT_TRANSFER_PREAUTH_REST",
  "amount": 400
}'

A successful capture returns the following response:

{
  "seller_id": "54f88e68-7764-4e87-8830-756b1e2c02f8",
  "payment_id": "777f851479c64541bd9c4e8fd4808fe9",
  "idempotency_key": "11c7f8ee-51a6-470d-bb76-ef762b62bfb1",
  "order_id": "ORDER-10187386",
  "amount": 400,
  "currency": "EUR",
  "status": "CAPTURED",
  "reason_code": "00",
  "reason_message": "Captured successfully",
  "captured_at": "2025-11-03T15:20:30.456Z"
}

3. Confirm Settlement

Check the transaction status or rely on webhook events to confirm the payment has transitioned from AUTHORIZED to CAPTURED.

For detailed information about the refund process, full and partial refunds, timing considerations, and best practices, see the Refund a Payment guide.

Payout Flow

The Payout flow transfers funds directly to a customer’s Bizum-registered phone number. Unlike purchase flows, Payout does not require card data, you need only the recipient’s phone number, passed as additional_data.customer.phone_number. Use this flow for disbursements, marketplace payouts, or any scenario where you need to push money to a customer.

1. Create the Payout Request

To create the payout, set payment_method to PAYOUT and include the recipient’s details in the additional_data.customer object. The payout is processed synchronously, and the final APPROVED status is returned directly in the API response.

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "idempotency_key": "{{$guid}}",
  "request_id": "{{$guid}}",
  "order_id": "PAYOUT-10187387",
  "data": {
    "amount": 400,
    "currency": "EUR",
    "payment": {
      "payment_id": "pyt-001",
      "payment_method": "PAYOUT",
      "brand": "BIZUM",
      "soft_descriptor": "BIZUM STORE"
    },
    "additional_data": {
      "customer": {
        "email": "recipient@example.com",
        "document_number": "50506468",
        "document_type": "dni",
        "name": "Jose da Silva",
        "phone_number": "34700000000",
        "billing_address": {
          "street": "Calle Mayor",
          "number": "10",
          "complement": "2A",
          "district": "Centro",
          "city": "Madrid",
          "state": "MD",
          "country": "ES",
          "postal_code": "28001"
        }
      }
    }
  }
}'

A successful Payout returns APPROVED synchronously:

{
  "idempotency_key": "d6ac5037-c299-460f-ae21-4a93f785424e",
  "seller_id": "2ab3e585-3607-467e-b2e8-420fcd45f48e",
  "payment_id": "6x5ct0ct85h5",
  "order_id": "6x5ct0ct85h5",
  "amount": 400,
  "currency": "EUR",
  "status": "APPROVED",
  "received_at": "2026-04-07T12:40:10.633Z",
  "reason_code": "00",
  "reason_message": "Operation completed successfully."
}

Webhooks

To receive asynchronous status updates for Bizum API Rest transactions, register webhook events via the Webhooks API. Bizum API Rest webhook events work differently from card payment webhooks — you must register the specific events below to cover all transaction lifecycle transitions.

Status Reference

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