# 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:
1. **Cajero Automático (Terminal Multibanco):** introduzca entidad, referencia e importe, luego confirme con PIN.
2. **Banca Online:** utilice pagos Multibanco, introduzca entidad + referencia.
3. **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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/authentication).
* 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):
* [Códigos de moneda](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)
* [Impuestos y normativas locales](https://www.google.com/search?q=/en/articles%3Farticle%3Dtaxes-and-regulations)
También puede utilizar [tarjetas de prueba](https://www.google.com/search?q=/en/articles%3Farticle%3Dtest-cards) 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](https://www.google.com/search?q=/en/products/online-payments/regional-api/swagger%23tag/payments/post/dpm/payments-gwproxy/v2/payments) 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.
```bash
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": "stevan.viapiana@getnet.net",
"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.
```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": "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](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 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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Drefund-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](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dreference-core-cards).
## Más información
* Revise [Autenticación](https://www.google.com/search?q=/en/products/online-payments/regional-api%3Fdoc%3Dauthentication) para la gestión de tokens y las mejores prácticas de seguridad.