Multibanco

Multibanco is an asynchronous reference-based payment method in Portugal, managed by SIBS. The API creates a payment reference composed of an entity and a reference number. The customer uses this information to complete the payment through an ATM, online banking, or mobile banking app.

Unlike redirect-based payment methods, Multibanco does not redirect the customer to an external checkout page. You display the payment instructions that the API returns.

Important: Multibanco is asynchronous. The initial API response returns WAITING with the payment entity and reference. This means the reference was created successfully, but the payment has not been completed yet. By default, the reference expires in D+7. You receive the final payment status through a webhook or by polling the Get Transaction endpoint.

Payment methods available

Customers can complete a Multibanco payment through the following channels:

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

Requirements

Before you integrate Multibanco:

Generate an access token through the Authentication endpoint.
Make sure your seller account is enabled for Multibanco.
Implement webhook event handling or status polling to receive asynchronous payment updates.
Display the payment information returned by the API to the customer.

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

Use case specifics

When integrating any Getnet solution, market-specific requirements apply. Multibanco is only available in Portugal and only for EUR currency. Review the resources below before going live:

Shared characteristics

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

Capability	Details
Integration type	Reference-based payment method with no customer redirect.
Customer experience	You display the payment `entity`, `reference`, and `amount` returned by the API. The customer pays asynchronously using ATM, online banking, or mobile banking.
Initial status	The initial response returns `WAITING` after the payment reference is created.
Confirmation	Asynchronous. The payment is completed only after the customer pays using one of the supported Multibanco channels.
Expiration time	By default, the Multibanco payment reference expires in D+7, meaning seven calendar days after the reference is created.
Notifications	Use webhooks or status polling to track asynchronous status updates.
Currency	`EUR` only.
Country availability	Portugal only.

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	✅	✅	✅	❌

Request structure

All Multibanco payment requests use the same top-level body structure and the same endpoint. The table below documents the minimum fields required to create a Multibanco payment reference.

Field	Type	Required	Description
`idempotency_key`	String UUID	Yes	Unique identifier to ensure the request is processed only once.
`request_id`	String UUID	Yes	Unique identifier for tracking the request across systems.
`order_id`	String	Yes	Merchant order reference used for reconciliation. Must be unique and have a maximum of 35 characters.
`data.amount`	Integer	Yes	Transaction amount in cents. For example, `200` represents €2.00.
`data.currency`	String	Yes	ISO 4217 currency code. Must be `EUR`.
`data.payment.payment_id`	String UUID	Yes	Merchant-defined payment identifier.
`data.payment.payment_method`	String	Yes	Must be `CASH_PAYMENT`.
`data.payment.brand`	String	Yes	Must be `MULTIBANCO`.
`data.additional_data.customer`	Object	No	Optional customer data object. You can send it to provide additional customer information, or when risk, compliance, or local configuration requires it.

Note: The order_id must be unique and must not exceed 35 characters.

Note: Customer data is optional for Multibanco. You can send the additional_data.customer object when needed, but the minimum payment request doesn't require it.

Optional customer fields

The additional_data.customer object accepts the following optional fields.

Field	Type	Required	Description
`data.additional_data.customer.email`	String	No	Customer's email address.
`data.additional_data.customer.document_number`	String	No	Customer's identification document number.
`data.additional_data.customer.document_type`	String	No	Customer's document type. For Portugal, use the applicable document type such as `nif`, when required.
`data.additional_data.customer.name`	String	No	Customer's full name.
`data.additional_data.customer.phone_number`	String	No	Customer's phone number.
`data.additional_data.customer.billing_address`	Object	No	Customer's billing address.
`data.additional_data.customer.shippings.address`	Object	No	Customer's shipping address.

Billing address fields

The billing_address object accepts the following fields.

Field	Type	Description
`street`	String	Street name.
`number`	String	Building number.
`complement`	String	Additional address details, such as apartment or suite.
`district`	String	Neighborhood or district.
`city`	String	City name.
`state`	String	State, region, or province.
`country`	String	ISO 3166-1 alpha-2 country code. For Portugal, use `PT`.
`postal_code`	String	Postal or ZIP code.

Payment flow

The lifecycle of a Multibanco payment begins when you create a payment request and receive a payment reference. The customer then uses the returned payment information to complete the payment through a supported banking channel.

Flow description

The following steps describe each stage of the payment flow.

The customer selects Multibanco as the payment method at checkout.
You create a Multibanco payment request through the API.
Getnet returns a WAITING response with the Multibanco entity and reference.
You display the payment instructions to the customer.
The customer pays using ATM, online banking, or mobile banking.
Getnet receives the payment confirmation.
Getnet updates the payment status and sends a webhook notification, or you check the status using the Get Transaction endpoint.
You fulfill the order after confirming the final approved status.

Create a Multibanco payment

To create a Multibanco payment, call the Create - Authorize endpoint and set:

payment_method to CASH_PAYMENT
brand to MULTIBANCO
currency to EUR

Minimum request

The following example shows the minimum request to create a Multibanco payment reference.

bash

curl --request POST \
  --url https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "idempotency_key": "{{$randomUUID}}",
  "request_id": "{{$guid}}",
  "order_id": "weyibwej",
  "data": {
    "amount": 200,
    "currency": "EUR",
    "payment": {
      "payment_id": "{{$guid}}",
      "payment_method": "CASH_PAYMENT",
      "brand": "MULTIBANCO"
    }
  }
}'

bash

curl --request POST \
  --url https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "idempotency_key": "{{$randomUUID}}",
  "request_id": "{{$guid}}",
  "order_id": "weyibwej",
  "data": {
    "amount": 200,
    "currency": "EUR",
    "payment": {
      "payment_id": "{{$guid}}",
      "payment_method": "CASH_PAYMENT",
      "brand": "MULTIBANCO"
    }
  }
}'

Request with optional customer data

Customer data is optional for Multibanco. You can include the additional_data.customer object to send additional customer information.

bash

curl --request POST \
  --url https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "idempotency_key": "{{$randomUUID}}",
  "request_id": "{{$guid}}",
  "order_id": "weyibwej",
  "data": {
    "amount": 200,
    "currency": "EUR",
    "payment": {
      "payment_id": "{{$guid}}",
      "payment_method": "CASH_PAYMENT",
      "brand": "MULTIBANCO"
    },
    "additional_data": {
      "customer": {
        "email": "customer@example.com",
        "document_number": "123456789",
        "document_type": "nif",
        "name": "Jose da Silva",
        "phone_number": "351912345678",
        "billing_address": {
          "street": "Avenida da Liberdade",
          "number": "10",
          "complement": "2A",
          "district": "Santo Antonio",
          "city": "Lisbon",
          "state": "Lisbon",
          "country": "PT",
          "postal_code": "1250-096"
        },
        "shippings": {
          "address": {
            "street": "Avenida da Liberdade",
            "number": "10",
            "complement": "2A",
            "district": "Santo Antonio",
            "city": "Lisbon",
            "state": "Lisbon",
            "country": "PT",
            "postal_code": "1250-096"
          }
        }
      }
    }
  }
}'

bash

curl --request POST \
  --url https://api.pre.globalgetnet.com/dpm/payments-gwproxy/v2/payments \
  --header 'Authorization: Bearer <your-token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "idempotency_key": "{{$randomUUID}}",
  "request_id": "{{$guid}}",
  "order_id": "weyibwej",
  "data": {
    "amount": 200,
    "currency": "EUR",
    "payment": {
      "payment_id": "{{$guid}}",
      "payment_method": "CASH_PAYMENT",
      "brand": "MULTIBANCO"
    },
    "additional_data": {
      "customer": {
        "email": "customer@example.com",
        "document_number": "123456789",
        "document_type": "nif",
        "name": "Jose da Silva",
        "phone_number": "351912345678",
        "billing_address": {
          "street": "Avenida da Liberdade",
          "number": "10",
          "complement": "2A",
          "district": "Santo Antonio",
          "city": "Lisbon",
          "state": "Lisbon",
          "country": "PT",
          "postal_code": "1250-096"
        },
        "shippings": {
          "address": {
            "street": "Avenida da Liberdade",
            "number": "10",
            "complement": "2A",
            "district": "Santo Antonio",
            "city": "Lisbon",
            "state": "Lisbon",
            "country": "PT",
            "postal_code": "1250-096"
          }
        }
      }
    }
  }
}'

Response

The API returns a WAITING status and the Multibanco payment information in additional_data.

json

{
  "idempotency_key": "9aea3042-42db-4b24-958d-e59ff17cbff9",
  "seller_id": "6f42ca7f-be26-42b7-b25e-f8ccd496a05b",
  "payment_id": "3b4129f9-43c3-4eed-baaf-7364ccb0a8c5",
  "order_id": "weyibwej",
  "amount": "200",
  "currency": "EUR",
  "status": "WAITING",
  "received_at": "2026-07-10T15:49:31.286Z",
  "reason_code": "00",
  "reason_message": "Pending",
  "acquirer_transaction_id": "775882357",
  "additional_data": {
    "reference": "775882357",
    "entity": "53492"
  }
}

json

{
  "idempotency_key": "9aea3042-42db-4b24-958d-e59ff17cbff9",
  "seller_id": "6f42ca7f-be26-42b7-b25e-f8ccd496a05b",
  "payment_id": "3b4129f9-43c3-4eed-baaf-7364ccb0a8c5",
  "order_id": "weyibwej",
  "amount": "200",
  "currency": "EUR",
  "status": "WAITING",
  "received_at": "2026-07-10T15:49:31.286Z",
  "reason_code": "00",
  "reason_message": "Pending",
  "acquirer_transaction_id": "775882357",
  "additional_data": {
    "reference": "775882357",
    "entity": "53492"
  }
}

Response fields

The following table describes the main fields in the response.

Field	Description
`payment_id`	Payment identifier used to query the payment status.
`order_id`	Merchant order reference used for reconciliation. Maximum of 35 characters.
`amount`	Transaction amount in cents.
`currency`	Transaction currency. For Multibanco, this must be `EUR`.
`status`	Initial payment status. For a successfully created Multibanco reference, this returns `WAITING`.
`acquirer_transaction_id`	Acquirer transaction identifier.
`additional_data.entity`	Multibanco entity code that you must display to the customer.
`additional_data.reference`	Multibanco payment reference that you must display to the customer.

Display the payment reference

After creating the payment request, display the Multibanco payment information returned by the API response.

Field	Source
Entity	`additional_data.entity`
Reference	`additional_data.reference`
Amount	`amount`

Example:

text

Entity: 53492
Reference: 775882357
Amount: €2.00

text

Entity: 53492
Reference: 775882357
Amount: €2.00

Important: Do not generate, alter, truncate, or reformat the Multibanco entity or reference. Always display the values exactly as returned by the API.

Expiration time

By default, the Multibanco payment reference expires in D+7, meaning seven calendar days after the reference is created.

The customer must complete the payment before the expiration date. If the customer doesn't pay within this period, the reference is no longer valid. In that case, ask the customer to create a new payment.

Handle the asynchronous status

The initial WAITING status means the payment reference was created successfully and is waiting for the customer to complete the payment.

The payment is not completed until the customer pays through ATM, online banking, or mobile banking. After the customer pays, Getnet updates the payment status asynchronously.

Use one of the following options to track the payment result:

Webhooks: recommended for production integrations.
Status polling: use the Get Transaction endpoint as a fallback.

Do not fulfill the order based only on the initial WAITING response. Fulfill the order only after receiving the final approved status.

Verify the payment status

To verify the payment status, use the Get Transaction endpoint.

Use the payment_id returned in the initial response.

bash

curl --request GET \
  --url https://api.pre.globalgetnet.com/dpm/hub-payment-info/v1/payments/info/{payment_id} \
  --header 'Authorization: Bearer <your-token>'

bash

curl --request GET \
  --url https://api.pre.globalgetnet.com/dpm/hub-payment-info/v1/payments/info/{payment_id} \
  --header 'Authorization: Bearer <your-token>'

A successful payment status response returns the final payment status. Use this endpoint as a fallback if webhook delivery is delayed or unavailable.

Webhooks

Use webhooks to receive asynchronous status updates for Multibanco payments. Webhooks are recommended for production integrations. Use status polling only as a fallback.

To learn how to configure and receive webhook notifications, see the Webhooks guide.

Event	Description
`PENDING_TRANSACTIONS`	Sent when the payment reference is created and waiting for customer payment.
`APPROVED_TRANSACTIONS`	Sent when the customer completes the Multibanco payment successfully.
`CANCELLED_TRANSACTIONS`	Sent when the payment is cancelled.

Status reference

The table below describes the expected status lifecycle for Multibanco payments.

Status	Description	Next action
`WAITING`	Payment reference created successfully. The customer has not completed the payment yet.	Display `entity`, `reference`, and `amount`; await webhook event or poll the Get Transaction endpoint.
`APPROVED`	Customer completed the payment through ATM, online banking, or mobile banking.	Fulfill the order and record the payment for reconciliation.
`CANCELLED`	Payment was cancelled before completion.	Record the cancellation and stop fulfillment.

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, see the Core Cards reference.

Best practices

Follow these recommendations when implementing Multibanco:

Use a unique order_id with a maximum of 35 characters.
Display the entity, reference, and amount exactly as returned by the API.
Inform the customer that the Multibanco reference expires in D+7 by default.
Do not fulfill the order while the payment status is WAITING.
Use webhooks in production and status polling only as a fallback.
Store payment_id, order_id, entity, reference, and amount for reconciliation.

Review Authentication for token management and security best practices.
Review the Get Transaction endpoint to check payment status.
Review the Refund a Payment guide for refund and cancellation instructions.

On this page

Multibanco

Ecommerce

Card Present

Reference

Webhooks

Multibanco

Payment methods available

Requirements

Use case specifics

Shared characteristics

Available features

Request structure

Optional customer fields

Billing address fields

Payment flow

Flow description

Create a Multibanco payment

Minimum request

Request with optional customer data

Response

Response fields

Display the payment reference

Expiration time

Handle the asynchronous status

Verify the payment status

Webhooks

Status reference

Refunds and cancellations

Best practices

Read more