Pagamentos com Bizum

Este documento se aplica ao seguinte país:

Aceite pagamentos com Bizum, o principal meio de pagamento móvel da Espanha. O comprador paga usando apenas o número de celular vinculado à sua conta bancária, sem precisar informar dados de cartão. O comprador aprova o pagamento no aplicativo do banco (biometria / PIN).

Este guia orienta você na criação de um payment intent, no envio do pagamento e na confirmação do resultado por meio de uma única integração com a API Web Checkout.

Como funciona

Use o Bizum quando quiser oferecer um meio de pagamento móvel rápido e local a compradores na Espanha que pagam sem cartão. Características principais:

• Instantâneo: confirmação em segundos.
• Sem cartão: o comprador é identificado pelo número de celular.
• Autenticação pelo aplicativo do banco: a aprovação final é feita pelo comprador no aplicativo do banco (biometria / PIN).
• APM (Alternative Payment Method): sem parcelamento, sem fluxo de cartão/3DS.
• Assíncrono: a operação é iniciada e pode retornar como pendente. Sempre confirme via polling/webhook antes de liberar o pedido.

O fluxo completo envolve o comprador, seu frontend, seu backend e a API Getnet Web Checkout:

O Web Checkout separa a criação do intent do envio do pagamento. Como o Bizum é assíncrono, o resultado é obtido via webhook enviado à notification.url, ou por redirecionamento para success_url, error_url.

Antes de começar

Certifique-se de que os itens abaixo estejam prontos antes de integrar:

• Os pagamentos são em EUR e o mercado é ES.
• Gere seu token seguindo o documento de Authentication.

Número de telefone para teste

Use o seguinte número de telefone para testar transações Bizum no ambiente de teste:

Número de telefone para teste: 700 000 000

Esse número permite concluir o fluxo de pagamento Bizum no ambiente de teste sem precisar de uma conta Bizum real.

Valores para teste

Diferentes valores de transação simulam diferentes resultados de pagamento no ambiente de teste. Use a tabela abaixo para testar vários cenários:

Observação: Esses cenários de teste estão disponíveis apenas no ambiente de teste. As transações em produção são processadas normalmente, com base no status e no saldo reais da conta Bizum do cliente.

Etapa 1: Crie o payment intent

Chame a API Web Checkout para criar um payment intent. Ela retorna um payment_intent_id e uma redirect_url.

Campos obrigatórios

Campos opcionais

Regras de preenchimento dos campos:

• O campo expires_at aceita um valor de duração (por exemplo, 15m, 2h, 7d ou 1d12h30m). Essa duração é aplicada independentemente do fuso horário do estabelecimento. O timestamp de expiração retornado pela API é sempre formatado em GMT+0 (UTC). Se nenhum valor for informado, o payment intent não expira.
• Quando success_url e error_url são informados na requisição do payment intent, eles substituem o valor configurado na configuração técnica do vendedor.
• Na Espanha, o valor do campo document_type deve ser DNI, INE ou passport.

Exemplo de requisição

{
  "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": "[email protected]",
    "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"
}

Exemplo de resposta 201

{
  "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"
}

Etapa 2: Redirecione e envie o pagamento

Redirecione o comprador para a redirect_url, ou exiba a tela de checkout incorporada onde ele escolhe o Bizum.

Etapa 3: O comprador aprova no aplicativo do banco

O comprador confirma o pagamento no aplicativo do banco (biometria / PIN). Essa etapa acontece fora da sua integração.

Etapa 4: Confirme o resultado

Como o Bizum é assíncrono, a chamada não é a confirmação final. Confirme o resultado antes de liberar o pedido, usando um ou mais dos seguintes recursos:

• Webhook: enviado à notification.url.
• Redirecionamento: para success_url ou error_url.

Exemplo de resposta de webhook aprovado

{
  "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": "[email protected]",
    "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"
}

Exemplo de resposta de webhook negado

{
  "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"
}