# Pagos con Bizum

<img height="108" width="108" alt="bizum" title="Bizum" src="https://static-devportal-ux.sensedia-eng.com/Pagonxt/production/documentations/download-1765913610450-cwuo6jz7.png" />

Este documento aplica al siguiente país:
España |
---|

Acepta pagos a través de Bizum, el método de pago móvil líder en España. El comprador paga usando solo el número de teléfono móvil vinculado a su cuenta bancaria, sin necesidad de datos de tarjeta. El comprador aprueba el pago en su aplicación bancaria (biometría / PIN).

Esta guía te muestra cómo crear un payment intent, enviar el pago y confirmar el resultado mediante una única integración de la API de Web Checkout.

## Cómo funciona

Usa Bizum cuando quieras ofrecer a los compradores en España un método de pago móvil rápido y local que no requiere tarjeta. Características clave:

- **Instantáneo**: confirmación en segundos.
- **Sin tarjeta**: el comprador se identifica mediante su número de teléfono.
- **Autenticación en la aplicación bancaria**: la aprobación final la realiza el comprador en su aplicación bancaria (biometría / PIN).
- **APM (método de pago alternativo)**: sin cuotas, sin flujo de tarjeta/3DS.
- **Asíncrono**: inicia la operación y puede devolver un estado pendiente. Confirma siempre mediante polling/webhook antes de liberar el pedido.

El flujo completo involucra al comprador, tu frontend, tu backend y la API de Getnet Web Checkout:

![](https://static-devportal-ux.sensedia-eng.com/Pagonxt/production/images/bizum-diagram-wbc-1784580755415-9ncxuqqj.png)

Web Checkout separa la **creación del payment intent** del **envío del pago**. Como Bizum es asíncrono, el resultado se obtiene mediante webhook a `notification.url`, o mediante redirección a `success_url`, `error_url`.

## Requisitos

Antes de seguir los pasos, necesitas:

- Los pagos están en **EUR** y el mercado es **ES**.
- Generar tu token siguiendo el documento de [Authentication](/es/web-checkout/first-steps-wbc/authentication-token-wbc).

### Número de teléfono de prueba

Usa el siguiente número de teléfono para probar transacciones de Bizum en el entorno de pruebas:

**Número de teléfono de prueba:** `700 000 000`

Este número te permite completar el flujo de pago de Bizum en el entorno de pruebas sin necesitar una cuenta Bizum real.

### Importes de prueba

Distintos importes de transacción simulan diferentes resultados de pago en el entorno de pruebas. Usa la siguiente tabla para probar varios escenarios:

| Importe        | Resultado          | Descripción                                                    |
| :------------- | :------------------ | :-------------------------------------------------------------- |
| Menos de €5    | Pago confirmado      | La transacción es exitosa y se aprueba de inmediato             |
| €5 a €10       | Pago confirmado      | La transacción es exitosa con procesamiento normal              |
| €10 a €500     | Pago confirmado      | La transacción es exitosa para importes estándar                |
| Más de €500    | Pago rechazado       | La transacción se rechaza para simular rechazos de alto valor   |

<Callout type="note">

Estos escenarios de prueba solo están disponibles en el entorno de pruebas. Las transacciones de producción se procesan normalmente según el estado y el saldo real de la cuenta Bizum del cliente.

</Callout>

## Paso 1: Crea el payment intent

Llama a la API de Web Checkout para crear un payment intent. Esta devuelve un `payment_intent_id` y un `redirect_url`.

Endpoint|
---|
`POST /payment-intent`|

**Campos obligatorios**
| Atributo | Tipo | Descripción | Ejemplo |
|----------------------------------|----------|--------|----------------------------------------|
| `payment.currency`                 | string   | Código de moneda.| `EUR`|
| `payment.amount`                   | integer  |Importe de la compra en formato entero, donde los últimos 2 dígitos representan los céntimos. En los países donde no se usan céntimos, completa el importe con 2 ceros a la derecha.| `5000`|
|`customer.customer_id`| String | Se recomienda usar el número de documento del cliente, solo letras y números, sin caracteres especiales, separadores ni espacios.| `12345678912`  |
|`customer.first_name`| String | Nombre del cliente.| `John`  |
|`customer.last_name`| String | Apellido del cliente.| `Doe Smith`  |
|`customer.name`| String | Nombre completo del cliente.| `John Doe Smith`  |
|`customer.email`| String | Dirección de correo electrónico del cliente.| `customer@email.com.br`  |
|`customer.document_type`| String | Tipo de documento usado para identificar al cliente. | `DNI`  |
|`customer.document_number`| String | Número de documento usado para identificar al cliente.| `12345678Z`  |
|`customer.billing_address.street`| String | Nombre de la calle.| `Calle Gran Via`  |
|`customer.billing_address.number`| String | Número que identifica la posición de un edificio en la calle.| `1000`  |
|`customer.billing_address.country`| String | Código de país.| `ES` |
|`customer.billing_address.postal_code`| String | Código postal.| `90230060`  |

**Campos opcionales**
| Atributo | Tipo | Descripción | Ejemplo |
|----------------------------------|----------|--------|----------------------------------------|
| `configurations.3ds`               | boolean  |Controla la autenticación 3D Secure. No aplica a Bizum.| `true` o `false` |
| `configurations.preauthorization`  | boolean  |Indica si el pago es una preautorización.| `true` o `false`|
| `configurations.card_verification`| boolean  |Indica si se trata de un flujo de verificación de tarjeta. No aplica a Bizum.| `true` o `false`|
| `configurations.success_url`       | string   |URL de redirección en caso de pago exitoso.|`https://www.mystore.com/checkout/success`|
| `configurations.error_url`         | string   |URL de redirección en caso de error durante el pago.|`https://www.mystore.com/checkout/error`|
| `soft_descriptor`                  | string | Descripción del pago que aparece en el recibo del cliente| `Tienda ES` |
| `expires_at`                       | string | Vencimiento del payment intent. |`3d4h15m`|

#### Reglas para completar los campos:

* El campo `expires_at` acepta un valor de duración (por ejemplo, 15m, 2h, 7d o 1d12h30m). Esta duración se aplica sin importar la zona horaria del merchant. La marca de tiempo de expiración devuelta por la API siempre tiene el formato GMT+0 (UTC). Si **no se proporciona ningún valor**, el payment intent **no expira**.
* Cuando se proporcionan `success_url` y `error_url` en la solicitud del payment intent, estos valores sobrescriben la configuración técnica del seller.
* **España**: el valor del campo `document_type` debe ser `DNI`, `INE` o `passport`.

#### Ejemplo de solicitud

```json
{
  "mode": "instant",
  "order_id": "ORDER_BIZUM_ES_0001",
  "configurations": {
    "3ds": false,
    "preauthorization": false,
    "card_verification": false,
    "success_url": "https://www.mystore.com/checkout/success",
    "error_url": "https://www.mystore.com/checkout/error"
  },
  "payment": {
    "currency": "EUR",
    "amount": 5000
  },
  "product": [
    {
      "product_type": "service",
      "title": "Plan Pro",
      "description": "Suscripcion 1 mes",
      "value": 5000,
      "quantity": 1
    }
  ],
  "customer": {
    "customer_id": "customer_es_005",
    "first_name": "Jose",
    "last_name": "Garcia",
    "name": "Jose Garcia",
    "email": "customer@email.com",
    "document_type": "DNI",
    "document_number": "12345678Z",
    "phone_number": "34600123456",
    "checked_email": true,
    "billing_address": {
      "street": "Calle Gran Via",
      "number": "28",
      "complement": "3o B",
      "district": "Centro",
      "city": "Madrid",
      "state": "Madrid",
      "country": "ES",
      "postal_code": "28013"
    }
  },
  "soft_descriptor": "Tienda ES",
  "expires_at": "1h"
}
```

#### Ejemplo de respuesta 201

```json
{
  "payment_intent_id": "ee0b7dd5-92da-4ef4-ad3b-0ba369ad0efe",
  "trade_name": "Minha Loja ES",
  "redirect_url": "https://checkout.getnet.com/es/ee0b7dd5-92da-4ef4-ad3b-0ba369ad0efe",
  "expires_at": "2026-07-02T19:30:00Z"
}
```

## Paso 2: Redirige y envía el pago

Redirige al comprador a `redirect_url`, o muestra la pantalla de checkout embebido donde elige Bizum.

## Paso 3: El comprador aprueba en la aplicación bancaria

El comprador confirma el pago en su aplicación bancaria (biometría / PIN). Este paso ocurre fuera de tu integración.

## Paso 4: Confirma el resultado

Como Bizum es asíncrono, la llamada **no** es la confirmación final. Confirma el resultado antes de liberar el pedido mediante uno o más de los siguientes métodos:

- **Webhook**: enviado a `notification.url`.
- **Redirección**: a `success_url` o `error_url`.

#### Ejemplo de respuesta de webhook aprobado

```json
{
  "payment_intent_id": "ee0b7dd5-92da-4ef4-ad3b-0ba369ad0efe",
  "checkout_id": "5ab15d1e-ea8b-4560-84d2-fb3d02179537",
  "order_id": "ORDER_BIZUM_ES_0001",
  "mode": "instant",
  "seller": {
    "id": "716d899e-9091-4577-a12f-8a77ec4d1e0b",
    "trade_name": "GetNet Shop",
    "merchant_document": "00000000000",
    "settings": { "notification_url_configured": true }
  },
  "customer": {
    "customer_id": "customer_es_005",
    "name": "Jose Garcia",
    "email": "customer@email.com",
    "document_type": "dni",
    "document_number": "12345678Z"
  },
  "payment": {
    "method": "bizum",
    "amount": 5000,
    "currency": "EUR",
    "result": {
      "payment_id": "772f951479c6514b1d9c4e8fd4808fe6",
      "status": "Authorized",
      "authorization_code": "999999",
      "transaction_datetime": "2026-07-08T12:00:00.000Z"
    }
  },
  "created_at": "2026-07-08T11:58:00.000Z",
  "updated_at": "2026-07-08T12:00:00.000Z"
}
```

#### Ejemplo de respuesta de webhook denegado

```json
{
  "payment_intent_id": "ee0b7dd5-92da-4ef4-ad3b-0ba369ad0efe",
  "checkout_id": "5ab15d1e-ea8b-4560-84d2-fb3d02179537",
  "order_id": "ORDER_BIZUM_ES_0001",
  "mode": "instant",
  "payment": {
    "method": "bizum",
    "amount": 5000,
    "currency": "EUR",
    "result": {
      "payment_id": "772f951479c6514b1d9c4e8fd4808fe6",
      "status": "Denied",
      "transaction_datetime": "2026-07-08T12:02:00.000Z",
      "return_message": "Payment not authorized by the customer's bank"
    }
  },
  "created_at": "2026-07-08T11:58:00.000Z",
  "updated_at": "2026-07-08T12:02:00.000Z"
}
```