Pagamentos MBWay

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

Este guia fornece instruções para integrar pagamentos MBWay, incluindo exemplos de requisição, tratamento de notificação push e processamento de webhook.

Requisitos

Antes de integrar o MBWay, você precisa:

Gerar um token de acesso através do endpoint de Autenticação.
Configurar uma callback_url HTTPS pública que recebe atualizações de status quando os clientes aprovam ou recusam pagamentos em seu aplicativo MBWay.
Garantir 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 Contas, que valida a elegibilidade e ativa o método de pagamento.

Especificidades de Casos de Uso

Ao integrar qualquer solução Getnet, aplicam-se requisitos específicos do mercado. O MBWay está disponível apenas em Portugal e apenas para a moeda EUR. Para saber mais sobre os requisitos específicos de Portugal, certifique-se de revisar os recursos abaixo antes de entrar em produção (go live):

Você também pode usar cartões de teste 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 exigidas	Número de telefone do cliente habilitado para MBWay no formato `countryCode#phoneNumber`
Confirmação	Assíncrona: status inicial `PENDING`, depois `APPROVED` ou `DECLINED` via webhook
Notificações	Webhooks para atualizações de status assíncronas quando o cliente aprova/recusa

Após você criar a requisição de pagamento, uma notificação push é enviada para o dispositivo do cliente. O cliente abre o seu aplicativo MBWay para aprovar ou recusar o pagamento. As atualizações de status são entregues via webhooks para a sua callback_url.

Funcionalidades disponíveis

Use a matriz abaixo para confirmar os cenários atualmente suportados para o MBWay.

Fluxo de pagamento	Países suportados	Compras	Reembolsos	Reembolsos parciais	Reembolsos múltiplos	Pré-autorizações
Wallet	Portugal	✅	✅	✅	✅	❌

Fluxo de pagamento

Esta seção o guia através do processo completo de implementação de pagamentos MBWay, desde a coleta de informações do cliente até o tratamento da resposta de pagamento e notificações de webhook. O diagrama abaixo fornece uma visão geral de um pagamento com MBWay:

1. Criar a requisição de pagamento

Como este é um fluxo de pagamento direto, você deve primeiro implementar um formulário de pagamento em seu frontend para coletar as informações necessárias do cliente. Uma vez coletadas, chame o endpoint Create – Authorize com os atributos abaixo.

A tabela descreve os campos mínimos obrigatórios para um pagamento MBWay.

Atributo	Descrição	Valor obrigatório
`payment_method`	Método de pagamento Wallet	`WALLET`
`brand`	Identificador da 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	Inteiro (ex.: `5000` para €50.00)
`currency`	Código de moeda ISO	`EUR`
`order_id`	Referência do estabelecimento para conciliação	String única
`customer.phone`	Número de telefone MBWay do cliente (obrigatório)	Formato: `countryCode#phoneNumber`

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

O exemplo de requisição a seguir mostra como inicializar um pagamento MBWay.

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 um payload semelhante ao exemplo abaixo.

{
  "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 para o dispositivo móvel do cliente (tipicamente entre 1 a 5 segundos).
Aplicativo MBWay: O cliente abre o seu aplicativo MBWay e vê os detalhes da requisição de pagamento.
Ação do Cliente:
- Aprova o pagamento → O status muda para APPROVED (webhook enviado)
- Recusa o pagamento → O status muda para DECLINED (webhook enviado)
- Nenhuma ação (timeout após 5 a 10 minutos) → O status muda para DECLINED (webhook enviado)

3. Verificar status do pagamento

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

Reembolsos e cancelamentos

Pagamentos MBWay suportam tanto cancelamentos quanto reembolsos:

Cancelamentos: Disponíveis para transações no mesmo dia antes do horário de corte diário (cutoff time). Apenas cancelamentos totais são suportados (sem cancelamentos parciais).
Reembolsos: Disponíveis para transações após a liquidação (Settlement). Tanto reembolsos totais quanto parciais são suportados, e reembolsos múltiplos são permitidos.

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

Para obter informações detalhadas sobre o tempo de reembolso, horários de corte e disponibilidade específica de cada país, consulte a referência Core Cards.