Pagos con MBWay

MBWay es una solución de pago con wallet móvil ampliamente utilizada en Portugal, creada por SIBS. Permite a los clientes autorizar pagos directamente desde su aplicación de banca móvil utilizando su número de teléfono, proporcionando confirmación instantánea a través de notificaciones push sin exponer los datos de la tarjeta. La Global API soporta MBWay como método de pago Wallet.

Esta guía proporciona instrucciones para integrar pagos con MBWay, incluyendo ejemplos de peticiones, gestión de notificaciones push y procesamiento de webhooks.

Requisitos

Antes de integrar MBWay debe:

Generar un token de acceso a través del endpoint de Autenticación.
Configurar una callback_url HTTPS pública que reciba actualizaciones de estado cuando los clientes aprueben o rechacen pagos en su aplicación MBWay.
Asegurarse de que los clientes tengan la aplicación MBWay instalada y su número de teléfono registrado en MBWay.

Para habilitar MBWay, debe trabajar con su Account Manager, quien validará la elegibilidad y activará el método de pago.

Especificidades de Casos de Uso

Al integrar cualquier solución de Getnet, se aplican requisitos específicos del mercado. MBWay solo está disponible en Portugal y exclusivamente para la moneda EUR. Para obtener más información sobre los requisitos específicos de Portugal, asegúrese de revisar los siguientes recursos antes de pasar a producción (go live):

También puede utilizar tarjetas de prueba para simular escenarios específicos.

Características

La siguiente tabla resume el comportamiento compartido y los requisitos para los pagos con MBWay.

Capacidad	Detalles
Interacción con el cliente	Notificación push enviada al dispositivo móvil del cliente a través de la aplicación MBWay
Credenciales requeridas	Número de teléfono del cliente habilitado en MBWay con el formato `countryCode#phoneNumber`
Confirmación	Asíncrona: estado inicial `PENDING`, luego `APPROVED` o `DECLINED` mediante webhook
Notificaciones	Webhooks para actualizaciones de estado asíncronas cuando el cliente aprueba/rechaza

Tras crear la petición de pago, se enviará una notificación push al dispositivo del cliente. El cliente abre su aplicación MBWay para aprobar o rechazar el pago. Las actualizaciones de estado se entregan mediante webhooks a su callback_url.

Funcionalidades disponibles

Utilice la siguiente matriz para confirmar los escenarios actualmente soportados para MBWay.

Flujo de pago	Países soportados	Compras	Reembolsos	Reembolsos parciales	Reembolsos múltiples	Preautorizaciones
Wallet	Portugal	✅	✅	✅	✅	❌

Flujo de pago

Esta sección le guía a través del proceso completo de implementación de pagos con MBWay, desde la recopilación de la información del cliente hasta la gestión de la respuesta de pago y las notificaciones de webhook. El siguiente diagrama ofrece una visión general de un pago con MBWay:

1. Crear la petición de pago

Al tratarse de un flujo de pago directo, primero debe implementar un formulario de pago en su frontend para recopilar la información necesaria del cliente. Una vez recopilada, llame al endpoint Create – Authorize con los atributos que se indican a continuación.

La tabla resume los campos mínimos requeridos para un pago con MBWay.

Atributo	Descripción	Valor obligatorio
`payment_method`	Método de pago Wallet	`WALLET`
`brand`	Identificador de marca MBWay	`MBWAY`
`callback_url`	Dónde se envían las actualizaciones de estado	Su endpoint HTTPS
`amount`	Importe de la transacción en céntimos	Entero (ej. `5000` para 50,00 €)
`currency`	Código de moneda ISO	`EUR`
`order_id`	Referencia del comercio para conciliación	Cadena única
`customer.phone`	Número de teléfono MBWay del cliente (obligatorio)	Formato: `countryCode#phoneNumber`

Formato del número de teléfono: Utilice countryCode#phoneNumber (ej., 351#912345678). No incluya +, espacios ni guiones. Código de país: 1 a 4 dígitos. Número de teléfono: 6 a 15 dígitos.

El siguiente ejemplo de petición muestra cómo inicializar un pago con 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"
          }
        }
      }
    }
  }
}'

La API responde con un payload similar al ejemplo a continuación.

{
  "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. Flujo de aprobación del cliente

Después de la llamada a la API, se produce la siguiente secuencia:

Notificación Push: Se envía una notificación al dispositivo móvil del cliente (normalmente en un plazo de 1 a 5 segundos).
Aplicación MBWay: El cliente abre su aplicación MBWay y ve los detalles de la petición de pago.
Acción del cliente:
- Aprueba el pago → El estado cambia a APPROVED (webhook enviado)
- Rechaza el pago → El estado cambia a DECLINED (webhook enviado)
- Sin acción (timeout después de 5 a 10 minutos) → El estado cambia a DECLINED (webhook enviado)

3. Verificar el estado del pago

Cuando el cliente aprueba el pago en su aplicación MBWay, se envía una notificación de webhook con el estado actualizado del pago. También puede comprobar periódicamente el estado del pago utilizando el endpoint Get Transaction.

Reembolsos y cancelaciones

Los pagos con MBWay soportan tanto cancelaciones como reembolsos:

Cancelaciones: Disponibles para transacciones del mismo día antes de la hora de corte diaria (cutoff time). Solo se soportan cancelaciones totales (no cancelaciones parciales).
Reembolsos: Disponibles para transacciones después de la liquidación (Settlement). Se soportan tanto reembolsos totales como parciales, y se permiten múltiples reembolsos.

Para procesar un reembolso o una cancelación, siga las instrucciones de la guía Refund a Payment.

Para obtener información detallada sobre los plazos de reembolso, las horas de corte y la disponibilidad específica de cada país, consulte la referencia Core Cards.

Más información

Revise Autenticación para la gestión de tokens y las mejores prácticas de seguridad.