# 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/authentication).
- 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):
- [Códigos de moeda](https://www.google.com/search?q=/en/articles%3Farticle%3Dcurrency-codes)
- [Tipos de documento](https://www.google.com/search?q=/en/articles%3Farticle%3Ddocument-types)
- [Impostos e regulamentações locais](https://www.google.com/search?q=/en/articles%3Farticle%3Dtaxes-and-regulations)
Você também pode usar [cartões de teste](https://www.google.com/search?q=/en/articles%3Farticle%3Dtest-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 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/payments-gwproxy/v2/payments) 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.
```bash
curl --request POST \
--url https://api-sbx.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
--header 'authorization: Bearer ' \
--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.
```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:
1. **Notificação Push**: Uma notificação é enviada para o dispositivo móvel do cliente (tipicamente entre 1 a 5 segundos).
2. **Aplicativo MBWay**: O cliente abre o seu aplicativo MBWay e vê os detalhes da requisição de pagamento.
3. **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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payment-record-management/get/dpm/hub-payment-info/v1/payments/info/%7Bpayment_id%7D).
## 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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Drefund-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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Freference-core-cards-and-availability).
## Leia mais
- Revise [Autenticação](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dauthentication) para gerenciamento de tokens e melhores práticas de segurança.