# Pagamentos com Bizum bizum Este documento se aplica ao seguinte país: Espanha | ---| 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: ![](https://static-devportal-ux.sensedia-eng.com/Pagonxt/production/images/bizum-diagram-wbc-1784580755415-9ncxuqqj.png) 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](/pt/web-checkout/first-steps-wbc/authentication-token-wbc). ### 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: | Valor | Resultado | Descrição | | :------------- | :------------------ | :----------------------------------------------------------- | | Menos de €5 | Pagamento confirmado | A transação é bem-sucedida e aprovada imediatamente | | €5 a €10 | Pagamento confirmado | A transação é bem-sucedida com processamento normal | | €10 a €500 | Pagamento confirmado | A transação é bem-sucedida para valores padrão | | Mais de €500 | Pagamento recusado | A transação é recusada para simular rejeições de alto valor | > **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`. Endpoint| ---| `POST /payment-intent`| **Campos obrigatórios** | Campo | Tipo | Descrição | Exemplo | |----------------------------------|----------|--------|----------------------------------------| | `payment.currency` | string | Código da moeda.| `EUR`| | `payment.amount` | integer |Valor da compra em formato inteiro, onde os últimos 2 dígitos representam os centavos. Para países onde não se aplicam centavos, preencha o valor com 2 zeros à direita.| `5000`| |`customer.customer_id`| String | Recomenda-se usar o número do documento do cliente, apenas letras e números, sem caracteres especiais, separadores ou espaços.| `12345678912` | |`customer.first_name`| String | Primeiro nome do cliente.| `John` | |`customer.last_name`| String | Sobrenome do cliente.| `Doe Smith` | |`customer.name`| String | Nome completo do cliente.| `John Doe Smith` | |`customer.email`| String | Endereço de e-mail do cliente.| `customer@email.com.br` | |`customer.document_type`| String | Tipo de documento usado para identificar o cliente. | `DNI` | |`customer.document_number`| String | Número do documento usado para identificar o cliente.| `12345678Z` | |`customer.billing_address.street`| String | Nome de uma rua.| `Calle Gran Via` | |`customer.billing_address.number`| String | Número que identifica a posição de um imóvel na rua.| `1000` | |`customer.billing_address.country`| String | Código do país.| `ES` | |`customer.billing_address.postal_code`| String | CEP ou código postal.| `90230060` | **Campos opcionais** | Campo | Tipo | Descrição | Exemplo | |----------------------------------|----------|--------|----------------------------------------| | `configurations.3ds` | boolean |Controla a autenticação 3D Secure. Não se aplica ao Bizum.| `true` ou `false` | | `configurations.preauthorization` | boolean |Indica se o pagamento é uma pré-autorização.| `true` ou `false`| | `configurations.card_verification`| boolean |Indica se este é um fluxo de verificação de cartão. Não se aplica ao Bizum.| `true` ou `false`| | `configurations.success_url` | string |URL de redirecionamento em caso de pagamento bem-sucedido.|`https://www.mystore.com/checkout/success`| | `configurations.error_url` | string |URL de redirecionamento em caso de erro durante o pagamento.|`https://www.mystore.com/checkout/error`| | `soft_descriptor` | string | Descrição do pagamento exibida no comprovante do cliente| `Tienda ES` | | `expires_at` | string | Expiração do payment intent. |`3d4h15m`| #### 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 ```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" } ``` #### Exemplo de resposta 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" } ``` ## 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 ```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" } ``` #### Exemplo de resposta de webhook negado ```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" } ```