# Multibanco
O Multibanco é um método de pagamento assíncrono baseado em referência amplamente utilizado em Portugal, gerenciado pela SIBS. A API gera uma referência numérica de pagamento (entidade + referência) que o cliente utiliza em caixas eletrônicos (ATMs), internet banking ou aplicativos de banco no celular para concluir o pagamento. A referência é retornada imediatamente, enquanto a confirmação final é assíncrona e entregue via webhook (ou consulta de status).
#### Métodos de Pagamento Disponíveis
Estas são as maneiras possíveis para o cliente fazer o pagamento:
1. **Caixa Eletrônico (Terminal Multibanco):** insira a entidade, referência e valor, depois confirme com o PIN.
2. **Internet Banking:** use pagamentos Multibanco, insira entidade + referência.
3. **Aplicativo de Banco no Celular:** insira/escaneie e autorize com biometria ou PIN.
## Requisitos
Antes de integrar o Multibanco, 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 após os clientes concluírem ou abandonarem o pagamento.
O Multibanco está disponível apenas em Portugal e espera a moeda EUR. Contate o seu Gerente de Contas para habilitar este método de pagamento para a sua conta de estabelecimento.
## Especificidades de Casos de Uso
Ao integrar qualquer solução Getnet, aplicam-se requisitos específicos do mercado. O Multibanco está disponível apenas em Portugal e somente 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 e os requisitos para fluxos de pagamento Multibanco.
| Capacidade | Detalhes |
| ------------------- | :------------------------------------------------------------------------------------------------------------------------- |
| Experiência do cliente | O estabelecimento exibe a referência de pagamento para o cliente, que paga de forma assíncrona usando canais bancários (Caixa eletrônico, internet, celular) |
| Confirmação | Assíncrona: status inicial `PENDING`, depois `APPROVED` ou `DECLINED` dependendo da ação do cliente |
| Notificações | Webhooks para atualizações de status assíncronas quando o cliente aprova/recusa |
## Funcionalidades disponíveis
Use a matriz abaixo para confirmar os cenários atualmente suportados para o Multibanco.
| Fluxo de pagamento | Países suportados | Compras | Reembolsos | Reembolsos parciais | Pré-autorizações |
| :----------: | :-----------------: | :-------: | :-----: | :-------------: | :----------------: |
| Direto | Portugal | ✅ | ✅ | ✅ | ❌ |
## Fluxo de pagamento
Esta seção o guia através do processo completo de implementação de pagamentos Multibanco, desde a coleta de informações do cliente até a geração da referência de pagamento e o tratamento da confirmação de pagamento assíncrona. O diagrama abaixo fornece uma visão geral do processo de pagamento Multibanco:
### 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 Multibanco.
| Atributo | Descrição | Valor obrigatório |
| :---------------------- | :---------------------------------------------------------------- | :-------------------------------- |
| `payment_method` | Método de pagamento | `CASH_PAYMENT` |
| `brand` | Identificador da marca Multibanco | `MULTIBANCO` |
| `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 (usada como referência de pagamento) | String única (máx. 32 caracteres) |
| `customer.phone_number` | Número de telefone do cliente (obrigatório) | String |
O exemplo de requisição a seguir mostra como inicializar um pagamento 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"
}
}
}
}
}
}'
```
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": "MULTIBANCO",
"received_at": "2025-11-11T11:51:54.569Z",
"transaction_id": "772f951479c6514b1d9c4e8fd4808fe6",
"reason_code": "00",
"reason_message": "Waiting for customer approval in Multibanco."
}
```
### 2\. Exibir referência de pagamento para o cliente
Após a chamada da API, você deve exibir as informações de pagamento Multibanco em seu frontend:
* **Entidade**: O código da entidade para o pagamento.
* **Referência**: O valor `order_id` que você forneceu na requisição (até 32 caracteres).
O cliente usará esses valores para concluir o pagamento através de seu canal preferido:
* **Caixa Eletrônico (Terminal Multibanco)**: O cliente insere a entidade e a referência, depois confirma o valor.
* **Internet Banking**: O cliente acessa pagamentos Multibanco e insere a entidade e a referência.
* **Aplicativo de Banco no Celular**: O cliente insere ou escaneia a entidade e a referência, depois autoriza o pagamento.
### 3\. Verificar status do pagamento
Quando o cliente conclui o pagamento, uma notificação de webhook é enviada com o status atualizado do pagamento. Você também pode verificar 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 Multibanco suportam tanto cancelamentos quanto reembolsos:
* **Cancelamentos**: Disponíveis para transações no mesmo dia antes do horário de corte diário (cutoff time). Tanto cancelamentos totais quanto parciais são suportados.
* **Reembolsos**: Disponíveis para transações após a liquidação (Settlement). Tanto reembolsos totais quanto parciais são suportados.
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%3Fdoc%3Dreference-core-cards).
## 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.