Multibanco

Multibanco is a widely used asynchronous reference-based payment method in Portugal managed by SIBS. The API generates a numeric payment reference (entity + reference) that the customer uses at ATMs, online banking or mobile banking apps to complete the payment. The reference is returned immediately, while the final confirmation is asynchronous and delivered via webhook (or status polling).

Payment Methods Available

These are the possible ways for the customer to make the payment:

ATM (Multibanco Terminal): enter entity, reference and amount, then confirm with PIN.
Online Banking: use Multibanco payments, enter entity + reference.
Mobile Banking App: enter/scan and authorize with biometrics or PIN

Requirements

Before integrating Multibanco you need to:

Generate an access token through the Authentication endpoint.
Configure a public HTTPS callback_url that receives status updates after customers complete or abandon the payment.

Multibanco is only available in Portugal and expects EUR currency. Contact your Account Manager to enable this payment method for your seller account.

Use Cases Specifics

When integrating any Getnet solution, market-specific requirements apply. Multibanco is only available in Portugal and only for EUR currency. To know more about the specific requirements of Portugal, be sure to review the resources below before you go live:

You can also use test cards to simulate specific scenarios.

Characteristics

The table below summarizes the behavior and requirements for Multibanco payment flows.

Capability	Details
Customer experience	Merchant displays the payment reference to the customer, who pays asynchronously using bank channels (ATM, online, mobile)
Confirmation	Asynchronous: initial `PENDING` status, then `APPROVED` or `DECLINED` depending on the customer's action
Notifications	Webhooks for asynchronous status updates when customer approves/declines

Available features

Use the matrix below to confirm the scenarios currently supported for Multibanco.

Payment flow	Supported countries	Purchases	Refunds	Partial refunds	Pre-authorizations
Direct	Portugal	✅	✅	✅	❌

Payment flow

This section guides you through the complete process of implementing Multibanco payments, from collecting customer information to generating the payment reference and handling the asynchronous payment confirmation. The diagram below provides an overview of the Multibanco payment process:

1. Create the payment request

As this is a direct payment flow, you must first implement a payment form on your frontend to collect the necessary customer information. Once collected, call the Create - Authorize endpoint with the attributes below.

The table outlines the minimum fields required for a Multibanco payment.

Attribute	Description	Required value
`payment_method`	Payment method	`CASH_PAYMENT`
`brand`	Multibanco brand identifier	`MULTIBANCO`
`callback_url`	Where status updates are sent	Your HTTPS endpoint
`amount`	Transaction amount in cents	Integer (e.g. `5000` for €50.00)
`currency`	ISO currency code	`EUR`
`order_id`	Merchant reference for reconciliation (used as payment reference)	Unique string (max 32 characters)
`customer.phone_number`	Customer's phone number (mandatory)	String

The following sample request shows how to initialize a Multibanco payment.

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

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

The API responds with a payload similar to the example below.

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

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. Display payment reference to customer

After the API call, you must display the Multibanco payment information on your frontend:

Entity: The entity code for the payment.
Reference: The order_id value you provided in the request (up to 32 characters).

The customer will use these values to complete payment through their preferred channel:

ATM (Multibanco Terminal): Customer enters the entity and reference, then confirms the amount.
Online Banking: Customer accesses Multibanco payments and enters the entity and reference.
Mobile Banking App: Customer enters or scans the entity and reference, then authorizes the payment.

3. Verify payment status

When the customer completes the payment, a webhook notification is sent with the updated payment status. You can also check the payment status using the Get Transaction endpoint.

Refunds and cancellations

Multibanco payments support both cancellations and refunds:

Cancellations: Available for same-day transactions before the daily cutoff time. Both full and partial cancellations are supported.
Refunds: Available for transactions after settlement. Both full and partial refunds are supported.

To process a refund or cancellation, follow the instructions in the Refund a Payment guide.

For detailed information about refund timing, cutoff times, and country-specific availability, refer to the Core Cards reference.