Multibanco payments

Accept payments through Multibanco, Europe's most widespread reference-based payment method. Your integration generates an entity, reference, and amount. The buyer pays them later at an ATM or through home banking, with no online card and no 3DS.

This guide shows you how to create a payment intent and submit the Multibanco payment. It also covers how to present the reference to the buyer and resolve the final status asynchronously.

This document applies to the following country:

Europe

How it works

Use Multibanco to offer the most widespread reference-based payment method in Europe. It suits buyers who pay without an online card. Its key characteristics are:

  • Reference-based — the backend generates an entity, reference, amount, and expiry_date. The buyer pays that reference whenever they want, at an ATM or through home banking.
  • Reusable reference — you can show the reference data on screen, send it by email (event MULTIBANCO-REFERENCE-EMAIL), or both.
  • Asynchronous / deferred processing — submitting the payment does not confirm it. The payment stays in PENDING until the buyer pays the reference, then resolves to paid (or expired / denied). You get the final status through a webhook.

The end-to-end flow involves the buyer, your frontend, your backend, and the Getnet Web Checkout API:

Before you start

Make sure the following are in place before you integrate:

  • The seller (x-seller-id) has Multibanco enabled (multibanco.enabled).
  • You have generated your token as described in the Authentication document.

Step 1: Create the payment intent

Call the Web Checkout API to create a payment intent. It returns a payment_intent_id and a redirect_url.

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

CapabilityDetails
Customer experienceYou display the payment reference to the customer, who pays asynchronously using bank channels (ATM, online, mobile)
ConfirmationAsynchronous: initial PENDING status, then APPROVED or DECLINED depending on the customer's action
NotificationsWebhooks for asynchronous status updates when the customer approves or declines
Endpoint
POST /payment-intent
Required fields
FieldTypeDescriptionExample
payment.payment_methodstringPayment methodCASH_PAYMENT
payment.brandstringMultibanco brand identifierMULTIBANCO
payment.currencyStringCurrency code.EUR
payment.amountIntegerPurchase amount in integer format, where the last 2 digits represent the cents. For countries where cents do not apply, fill in the amount with 2 zeros to the right.5000
customer.phone_numberstringPurchaser's phone number.351#912345678
customer.customer_idStringWe recommend the customer's document number, with only letters and numbers and no special characters, separators, or spaces.12345678912
customer.nameStringCustomer's full name.John Doe Smith
customer.emailStringCustomer's email address.customer@email.com.br
customer.billing_address.streetStringName of a street.Calle Gran Via
customer.billing_address.numberStringNumber that identifies the position of a building on a street.1000
customer.billing_address.countryStringCountry code.PT
customer.billing_address.postal_codeStringPostal or ZIP code.90230060
Optional fields
FieldTypeDescriptionExample
configurations.3dsbooleanControls 3D Secure authentication. Does not apply to Multibanco.true or false
configurations.preauthorizationbooleanIndicates if the payment is a pre-authorization.true or false
configurations.card_verificationbooleanIndicates if this is a card verification flow. Does not apply to Bizum.true or false
configurations.success_urlstringRedirect URL in case of successful payment.https://www.mystore.com/checkout/success
configurations.error_urlstringRedirect URL in case of an error during payment.https://www.mystore.com/checkout/error
soft_descriptorstringPayment description that appears on the customer's receipt.Tienda ES
expires_atstringPayment intent expiration.3d4h15m

Example of request

The following example creates a Multibanco payment intent for a customer with billing and shipping addresses in Portugal.

JSON
{ "idempotency_key": "7e2aca20-ad89-4226-a8bb-6ee5ca42ffd7", "request_id": "052d6f4d-4281-4004-9a90-faf2277c0825", "order_id": "ORDER-MULTIBANCO-0001", "data": { "amount": 2500, "currency": "EUR", "customer_id": "customer-123", "payment": { "payment_id": "4991161d-c347-455a-99b3-0103ee807580", "payment_method": "CASH_PAYMENT", "brand": "MULTIBANCO" }, "additional_data": { "customer": { "name": "Maria Silva", "phone_number": "351#912345678", "email": "maria.silva@example.com", "document_number": "12345678", "document_type": "ID", "billing_address": { "street": "Rua do Carmo", "number": "50", "district": "Chiado", "city": "Lisboa", "state": "Lisboa", "country": "PT", "postal_code": "1200-094", "complement": "" } }, "shippings": { "address": { "street": "Rua do Carmo", "number": "50", "district": "Chiado", "city": "Lisboa", "state": "Lisboa", "country": "PT", "postal_code": "1200-094", "complement": "" } } } } }

Step 2: Submit the Multibanco payment

Submit the payment with the Multibanco method. This step bypasses validate-session and 3DS. The backend generates the reference at the provider. It returns the entity, reference, amount, and expiry_date for you to show to the buyer, send by email, or both.

Example of request

The following example submits the Multibanco payment for the customer.

JSON
{ "idempotency_key": "7e2aca20-ad89-4226-a8bb-6ee5ca42ffd7", "request_id": "052d6f4d-4281-4004-9a90-faf2277c0825", "order_id": "ORDER-20260825-0001", "data": { "amount": 2500, "currency": "EUR", "customer_id": "customer-123", "payment": { "payment_id": "4991161d-c347-455a-99b3-0103ee807580", "payment_method": "CASH_PAYMENT", "brand": "MULTIBANCO" }, "additional_data": { "customer": { "name": "João Silva", "phone_number": "+351912345678", "email": "joao.silva@example.com" } } } }

Example of response — pending/waiting

The response returns the WAITING status with the Multibanco entity and reference.
JSON
{ "status": "WAITING", "order_id": "ORDER-20260825-0001", "data": { "amount": 2500, "currency": "EUR", "payment": { "payment_id": "4991161d-c347-455a-99b3-0103ee807580", "payment_method": "CASH_PAYMENT", "brand": "MULTIBANCO", "entity": "12345", "reference": "123456789" } } }

Step 3: Confirm the result

Multibanco is asynchronous / deferred: submitting the payment does not confirm it. The payment stays in PENDING until the buyer pays the reference. Resolve the final status in one of two ways:

  • Webhook: receive the approved or denied notification (see payloads below).

Example of response — approved

The following webhook payload shows an approved payment, with the result status Authorized.
JSON
{ "payment_intent_id": "bb2d70ff-98ff-7ecf-d739-3140fc2d5e5f", "checkout_id": "6bc26e2f-fb9c-4671-95e3-0c4e13280648", "order_id": "ORDER_MB_PT_0001", "mode": "instant", "seller": { "id": "716d899e-9091-4577-a12f-8a77ec4d1e0b", "trade_name": "GetNet Shop", "merchant_document": "00000000000", "settings": { "notification_url_configured": true } }, "customer": { "customer_id": "customer_pt_006", "name": "Jose Silva", "email": "customer@email.com", "document_type": "nif", "document_number": "250000000" }, "payment": { "method": "multibanco", "amount": 200, "currency": "EUR", "result": { "payment_id": "4991161d-c347-455a-99b3-0103ee807580", "status": "Authorized", "authorization_code": "999999", "entity": "12345", "reference": "987654321", "transaction_datetime": "2026-07-09T09:15:00.000Z" } }, "created_at": "2026-07-08T11:58:00.000Z", "updated_at": "2026-07-09T09:15:00.000Z" }

Example of response — denied

The following webhook payload shows a denied payment. In this example, the reference expired without payment.

JSON
{ "payment_intent_id": "bb2d70ff-98ff-7ecf-d739-3140fc2d5e5f", "checkout_id": "6bc26e2f-fb9c-4671-95e3-0c4e13280648", "order_id": "ORDER_MB_PT_0001", "mode": "instant", "payment": { "method": "multibanco", "amount": 200, "currency": "EUR", "result": { "payment_id": "4991161d-c347-455a-99b3-0103ee807580", "status": "Denied", "entity": "12345", "reference": "987654321", "transaction_datetime": "2026-07-11T00:00:00.000Z", "return_message": "Reference expired without payment" } }, "created_at": "2026-07-08T11:58:00.000Z", "updated_at": "2026-07-11T00:00:00.000Z" }

Multibanco status values (Global API contract)

For Multibanco, consider these statuses from the Global API contract:

  • WAITING: reference created, waiting for the customer's payment. This is the initial return.
  • APPROVED: payment confirmed. You can release the order.
  • EXPIRED: reference expired without payment (D+7 by default).
  • DENIED: payment refused by the processor.
  • ERROR: processing error.
  • PENDING: processing not yet complete. It may appear in intermediate states.

In practice, the expected flow is WAITING → APPROVED or EXPIRED. DENIED and ERROR are terminal failure states.

CANCELED exists in the general transaction set. Don't treat it as a normal Multibanco payment status unless you confirm that the tenant allows cancellation of this APM.

Your webhook must be idempotent. Invoice the order only after APPROVED.

On this page

Multibanco payments