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:

Caixa Eletrônico (Terminal Multibanco): insira a entidade, referência e valor, depois confirme com o PIN.
Internet Banking: use pagamentos Multibanco, insira entidade + referência.
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.
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):

Você também pode usar cartões de teste 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 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.

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"
          }
        }
      }
    }
  }
}'

A API responde com um payload semelhante ao exemplo abaixo.

{
  "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.

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.

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.