Mbway

O Mbway é uma solução de pagamento por carteira móvel amplamente utilizada em Portugal, criada pela SIBS. Ele permite que os clientes autorizem pagamentos diretamente de seu aplicativo bancário móvel usando seu número de telefone, fornecendo confirmação instantânea por meio de notificações push sem expor os detalhes do cartão. A API regional suporta o Mbway como método de pagamento de carteira.

Este guia fornece instruções para integrar pagamentos Mbway, incluindo exemplos de solicitações, tratamento de notificações push e processamento de webhook.

Requisitos

Antes de integrar o Mbway, você precisa:

Gere um token de acesso por meio do Authentication endpoint.
Configurar um HTTPS público callback_url que recebe atualizações de status quando os clientes aprovam ou recusam pagamentos em seu aplicativo Mbway.
Certifique-se de que os clientes tenham o aplicativo Mbway instalado e seu número de telefone registrado no Mbway.

Para habilitar o Mbway, você deve trabalhar com seu gerente de conta, que valida a elegibilidade e ativa o método de pagamento.

Casos de uso e especificidades

Ao integrar qualquer solução Getnet, os requisitos específicos do mercado se aplicam. O Mbway está disponível apenas em Portugal e apenas para a moeda EUR. Para saber mais sobre os requisitos específicos de Portugal, não deixe de conferir os recursos abaixo antes de ir ao ar:

Você também pode usar test cards para simular cenários específicos.

Características

A tabela abaixo resume o comportamento compartilhado e os requisitos para pagamentos Mbway.

Capacidade	Detalhes
Interação com o cliente	Notificação push enviada para o dispositivo móvel do cliente através do aplicativo Mbway
Credenciais necessárias	Número de telefone compatível com MBWay do cliente em formato `countryCode#phoneNumber`
Confirmação	Assíncrono: inicial `PENDING` status, então `APPROVED` ou `DECLINED` via webhook
Notificações	Webhooks para atualizações de status assíncronas quando o cliente aprova/recusa

Depois de criar a solicitação de pagamento, uma notificação push é enviada ao dispositivo do cliente. O cliente abre o aplicativo MBWay para aprovar ou recusar o pagamento. As atualizações de status são entregues por meio de webhooks para seu callback_url.

Funcionalidades disponíveis

Use a matriz abaixo para confirmar os cenários atualmente suportados pelo Mbway.

Fluxo de pagamento	Países suportados	Compras	Reembolsos	Reembolsos parciais	Vários reembolsos	Pré-autorizações
Carteira	Portugal	✅	✅	✅	✅	❌

Fluxo de pagamento

Esta seção orienta você por todo o processo de implementação de pagamentos Mbway, desde a coleta de informações do cliente até o tratamento da resposta do pagamento e das notificações de webhook. O diagrama abaixo fornece uma visão geral de um pagamento com o Mbway:

1. Crie a solicitação de pagamento

Como esse é um fluxo de pagamento direto, você deve primeiro implementar um formulário de pagamento em seu front-end para coletar as informações necessárias do cliente. Depois de coletado, ligue para o Create – Authorize endpoint com os atributos abaixo.

A tabela descreve os campos mínimos necessários para um pagamento em Mbway.

Atributo	Descrição	Valor exigido
`payment_method`	Método de pagamento da carteira	`WALLET`
`brand`	Identificador de marca Mbway	`MBWAY`
`callback_url`	Para onde as atualizações de status são enviadas	Seu endpoint HTTPS
`amount`	Valor da transação em centavos	Número inteiro (por exemplo. `5000` por €50,00)
`currency`	Código de moeda ISO	`EUR`
`order_id`	Referência do comerciante para reconciliação	Cadeia única
`customer.phone`	Número de telefone Mbway do cliente (obrigatório)	Formato: `countryCode#phoneNumber`

Formato de número de telefone: Uso countryCode#phoneNumber (por exemplo, 351#912345678). Não inclua +, espaços ou traços. Código do país: 1-4 dígitos. Número de telefone: 6 a 15 dígitos.

O exemplo de solicitação a seguir mostra como inicializar um pagamento Mbway.

bash

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
    "idempotency_key": "0de8b788-830a-4fd9-b738-63925f352614",
    "request_id": "533c7349-7c07-4e1b-bc12-6657d6b508dd",
    "order_id": "c22tsrgga7ao4ao8yhdioyoz8tbnh",
    "data": {
        "amount": 100,
        "currency": "EUR",
        "customer_id": "02587894152",
        "payment": {
            "payment_id": "b5d53566-c7d8-4591-8d7a-10bd02ef93ed",
            "payment_method": "WALLET",
            "brand": "MBWAY"
        },
        "additional_data": {
            "customer": {
                "phone_number": "55#11111111111",
                "billing_address": {
                    "district": "B",
                    "city": "City Z",
                    "state": "SP",
                    "country": "PT",
                    "postal_code": "05781000",
                    "complement": "N/A"
                },
                "shippings": {
                    "address": {
                        "street": "R a",
                        "number": "1",
                        "district": "B",
                        "city": "City Z",
                        "state": "SP",
                        "country": "PT",
                        "postal_code": "05781000",
                        "complement": "N/A"
                    }
                }
            }
        }
    }
}'

bash

curl --request POST \
  --url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'authorization: Bearer <your-token>' \
  --header 'content-type: application/json' \
  --header 'x-seller-id: 54f88e68-7764-4e87-8830-756b1e2c02f8' \
  --header 'x-transaction-channel-entry: XX' \
  --data '{
    "idempotency_key": "0de8b788-830a-4fd9-b738-63925f352614",
    "request_id": "533c7349-7c07-4e1b-bc12-6657d6b508dd",
    "order_id": "c22tsrgga7ao4ao8yhdioyoz8tbnh",
    "data": {
        "amount": 100,
        "currency": "EUR",
        "customer_id": "02587894152",
        "payment": {
            "payment_id": "b5d53566-c7d8-4591-8d7a-10bd02ef93ed",
            "payment_method": "WALLET",
            "brand": "MBWAY"
        },
        "additional_data": {
            "customer": {
                "phone_number": "55#11111111111",
                "billing_address": {
                    "district": "B",
                    "city": "City Z",
                    "state": "SP",
                    "country": "PT",
                    "postal_code": "05781000",
                    "complement": "N/A"
                },
                "shippings": {
                    "address": {
                        "street": "R a",
                        "number": "1",
                        "district": "B",
                        "city": "City Z",
                        "state": "SP",
                        "country": "PT",
                        "postal_code": "05781000",
                        "complement": "N/A"
                    }
                }
            }
        }
    }
}'

A API responde com uma carga semelhante ao exemplo abaixo.

json

{
  "idempotency_key": "be278973-35eb-4c45-8619-2800d62b33b6",
  "seller_id": "2ab3e585-3607-467e-b2e8-420fcd45f48e",
  "payment_id": "772f951479c6514b1d9c4e8fd4808fe6",
  "order_id": "ORDER-10187383",
  "amount": "5000",
  "currency": "EUR",
  "status": "PENDING",
  "payment_method": "MBWAY",
  "received_at": "2025-11-11T11:51:54.569Z",
  "transaction_id": "772f951479c6514b1d9c4e8fd4808fe6",
  "reason_code": "00",
  "reason_message": "Waiting for customer approval in MBWay app."
}

json

{
  "idempotency_key": "be278973-35eb-4c45-8619-2800d62b33b6",
  "seller_id": "2ab3e585-3607-467e-b2e8-420fcd45f48e",
  "payment_id": "772f951479c6514b1d9c4e8fd4808fe6",
  "order_id": "ORDER-10187383",
  "amount": "5000",
  "currency": "EUR",
  "status": "PENDING",
  "payment_method": "MBWAY",
  "received_at": "2025-11-11T11:51:54.569Z",
  "transaction_id": "772f951479c6514b1d9c4e8fd4808fe6",
  "reason_code": "00",
  "reason_message": "Waiting for customer approval in MBWay app."
}

2. Fluxo de aprovação do cliente

Após a chamada da API, ocorre a seguinte sequência:

Notificação push: uma notificação é enviada ao dispositivo móvel do cliente (normalmente em 1 a 5 segundos).
Mbway Aplicativo: O cliente abre o aplicativo Mbway e vê os detalhes da solicitação de pagamento.
Ação do cliente:
- Aprova o pagamento → O status se torna APPROVED (webhook enviado)
- Recusa o pagamento → O status se torna DECLINED (webhook enviado)
- Nenhuma ação (tempo limite após 5 a 10 minutos) → O status se torna DECLINED (webhook enviado)

3. Verifique o status do pagamento

Quando o cliente aprova o pagamento em seu aplicativo Mbway, uma notificação de webhook é enviada com o status de pagamento atualizado. Você também pode verificar periodicamente o status do pagamento usando o Get Transaction endpoint.

Reembolsos e cancelamentos

Os pagamentos Mbway suportam cancelamentos e reembolsos:

Cancelamentos: Disponível para transações no mesmo dia antes do horário limite diário. Somente cancelamentos completos são aceitos (sem cancelamentos parciais).
Reembolsos: Disponível para transações após a liquidação. Há suporte para reembolsos totais e parciais, e vários reembolsos são permitidos.

Para processar um reembolso ou cancelamento, siga as instruções na Refund a Payment guide.

Para obter informações detalhadas sobre prazos de reembolso, horários limite e disponibilidade específica para cada país, consulte o Core Cards reference.

Primeiros Passos

Card Present

Reference

Webhooks