Multibanco

Multibanco es un método de pago asíncrono basado en referencias ampliamente utilizado en Portugal y gestionado por SIBS. La API genera una referencia de pago numérica (entidad + referencia) que el cliente utiliza en cajeros automáticos (ATM), banca online o aplicaciones de banca móvil para completar el pago. La referencia se devuelve inmediatamente, mientras que la confirmación final es asíncrona y se entrega mediante webhook (o consulta de estado).

Métodos de Pago Disponibles

Estas son las formas posibles en que el cliente puede realizar el pago:

Cajero Automático (Terminal Multibanco): introduzca entidad, referencia e importe, luego confirme con PIN.
Banca Online: utilice pagos Multibanco, introduzca entidad + referencia.
Aplicación de Banca Móvil: introduzca/escanee y autorice con biometría o PIN.

Requisitos

Antes de integrar Multibanco 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 después de que los clientes completen o abandonen el pago.

Multibanco solo está disponible en Portugal y espera la moneda EUR. Contacte con su Account Manager para habilitar este método de pago en su cuenta de comercio.

Especificidades de Casos de Uso

Al integrar cualquier solución de Getnet, se aplican requisitos específicos del mercado. Multibanco 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 y los requisitos para los flujos de pago con Multibanco.

Capacidad	Detalles
Experiencia del cliente	El comercio muestra la referencia de pago al cliente, quien paga de forma asíncrona utilizando canales bancarios (Cajero automático, online, móvil)
Confirmación	Asíncrona: estado inicial `PENDING`, luego `APPROVED` o `DECLINED` dependiendo de la acción del cliente
Notificaciones	Webhooks para actualizaciones de estado asíncronas cuando el cliente aprueba/rechaza

Funcionalidades disponibles

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

Flujo de pago	Países soportados	Compras	Reembolsos	Reembolsos parciales	Preautorizaciones
Directo	Portugal	✅	✅	✅	❌

Flujo de pago

Esta sección le guía a través del proceso completo de implementación de pagos con Multibanco, desde la recopilación de la información del cliente hasta la generación de la referencia de pago y la gestión de la confirmación asíncrona del pago. El siguiente diagrama ofrece una visión general del proceso de pago con Multibanco:

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 Multibanco.

Atributo	Descripción	Valor obligatorio
`payment_method`	Método de pago	`CASH_PAYMENT`
`brand`	Identificador de marca Multibanco	`MULTIBANCO`
`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 (utilizada como referencia de pago)	Cadena única (máx. 32 caracteres)
`customer.phone_number`	Número de teléfono del cliente (obligatorio)	Cadena

El siguiente ejemplo de petición muestra cómo inicializar un pago con Multibanco.

curl --location --request POST 'https://gms-dpm-payments-v2-gwproxy-ms.app.dev.gms.corp/v2/payments' \
--header 'Content-Type: application/json' \
--header 'x-seller-id: 2ee453aa-3ab6-447b-becf-d9d4360051eb' \
--header 'country: PT' \
--header 'tenant: santander' \
--data-raw '{
  "idempotency_key": "7e2aca20-ad89-4226-a8bb-6ee5ca42ffd7",
  "request_id": "052d6f4d-4281-4004-9a90-faf2277c0825",
  "order_id": "cnybj35ky4iobq9nyof2u93rbf1lw",
  "data": {
    "amount": 200,
    "currency": "EUR",
    "customer_id": "02587894152",
    "payment": {
      "payment_id": "4991161d-c347-455a-99b3-0103ee807580",
      "payment_method": "CASH_PAYMENT",
      "brand": "MULTIBANCO"
    },
    "additional_data": {
      "customer": {
        "phone_number": "55#16997261419",
        "email": "[email protected]",
        "document_number": "50506468",
        "document_type": "uyci",
        "name": "Jose da Silva",
        "billing_address": {
          "street": "R a",
          "number": "1",
          "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": "MULTIBANCO",
  "received_at": "2025-11-11T11:51:54.569Z",
  "transaction_id": "772f951479c6514b1d9c4e8fd4808fe6",
  "reason_code": "00",
  "reason_message": "Waiting for customer approval in Multibanco."
}

2. Mostrar la referencia de pago al cliente

Después de la llamada a la API, debe mostrar la información de pago de Multibanco en su frontend:

Entidad: El código de entidad para el pago.
Referencia: El valor order_id que proporcionó en la petición (hasta 32 caracteres).

El cliente utilizará estos valores para completar el pago a través de su canal preferido:

Cajero Automático (Terminal Multibanco): El cliente introduce la entidad y la referencia, y luego confirma el importe.
Banca Online: El cliente accede a los pagos de Multibanco e introduce la entidad y la referencia.
Aplicación de Banca Móvil: El cliente introduce o escanea la entidad y la referencia, y luego autoriza el pago.

3. Verificar el estado del pago

Cuando el cliente completa el pago, se envía una notificación de webhook con el estado actualizado del pago. También puede comprobar el estado del pago utilizando el endpoint Get Transaction.

Reembolsos y cancelaciones

Los pagos con Multibanco soportan tanto cancelaciones como reembolsos:

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

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.