Accept a Multibanco payment
Learn how to accept the Multibanco payment method.
Checkout
Direct API
Mobile
Multibanco is a voucher-based payment method in Portugal. If your business is based in Europe or the United States, you can accept Multibanco payments from customers in Portugal using Stripe Checkout.
To complete a transaction, customers receive a voucher that includes a Multibanco entity and reference numbers. Customers use these voucher details to make a payment outside your checkout flow through online banking or from an ATM.
Payment confirmation might be delayed by several days due to the initiation of a bank transfer when a customer pays for a Multibanco voucher. Bank transfers can encounter delays, particularly over weekends, contributing to the delay in payment confirmation.
Determine compatibility
A Checkout Session must satisfy all of the following conditions to support Multibanco:
- Prices for all line items must be in the same currency (EUR).
- You can only use one-time line items (recurring subscription plans aren’t supported).
Accept a payment
Note
Build an integration to accept a payment with Checkout before using this guide.
Enable Multibanco as a payment method
When creating a new Checkout Session, you need to:
- Enable Multibanco in your Dashboard. Stripe automatically displays Multibanco to eligible customers using dynamic payment methods . If you currently specify payment _ method _ types , see the migration guide .
- Make sure all your line _ items use the eur currency.
Command Line
Select a language
cURL
Stripe CLI
Ruby
Python
PHP
Java
Node.js
Go
.NET
No results
Redirect to Stripe-hosted voucher page
Note
Unlike card payments, the customer won’t be redirected to the success_url with a Multibanco payment.
After submitting the Checkout form successfully, the customer is redirected to the hosted_voucher_url. The customer can reference the hosted page’s payment instructions for details on how to complete their payment. You can view the page on both desktop and mobile platforms, and it’s also printable.
Stripe sends a payment_intent.requires_action event when a Multibanco voucher is created successfully. If you need to send an email with the voucher’s payment instructions link, locate the PaymentIntent at data.object on the requires_action event, and extract the hosted_voucher_url at next_action.multibanco_display_details.hosted_voucher_url on the PaymentIntent.
Fulfill your orders
Because Multibanco is a delayed notification payment method, you need to use a method such as webhooks to monitor the payment status and handle order fulfillment. Learn more about setting up webhooks and fulfilling orders.
The following events are sent when the payment status changes:
| Event name | Description | Next steps |
|---|---|---|
| checkout.session.completed | The customer has successfully submitted the Checkout form. Stripe has generated a Multibanco voucher. | Wait for the customer to pay the Multibanco voucher. |
| checkout.session.async_payment_succeeded | The customer has successfully paid the Multibanco voucher. The PaymentIntent transitions to succeeded. | Fulfill the goods or services that the customer purchased. |
| checkout.session.async_payment_failed | The Multibanco voucher has expired, or the payment has failed for some other reason. The PaymentIntent returns to a status of requires_payment_method. | Contact the customer by email and request that they place a new order. |
Optional Send automated payment instruction emails
Optional Customize voucher appearance
Test your integration
When testing your Checkout integration, select Multibanco as the payment method, then click Pay. Provide the following email patterns in the Checkout form to test different scenarios:
| Description | |
|---|---|
{any_prefix}@{any_domain} | Simulates a Multibanco voucher that a customer pays. The payment_intent.succeeded webhook arrives after about 3 minutes. Example: |
{any_prefix}succeed_immediately@{any_domain} | Simulates a Multibanco voucher that a customer pays immediately. The payment_intent.succeeded webhook arrives within several seconds. Example: |
{any_prefix}expire_immediately@{any_domain} | Simulates a Multibanco voucher that expires immediately. The payment_intent.payment_failed webhook arrives within several seconds. Example: |
{any_prefix}expire_with_delay@{any_domain} | Simulates a Multibanco voucher that expires before a customer pays. The payment_intent.payment_failed webhook arrives after about 3 minutes. Example: |
{any_prefix}fill_never@{any_domain} | Simulates a Multibanco voucher that never succeeds. The payment_intent.payment_failed webhook arrives after 11 days, which mimics behavior in live mode. Learn about Multibanco expiration. Example: |
Expiration
Multibanco vouchers expire at the expires_at the related setting timestamp in next_action.multibanco_display_details.expires_at, which is 7 days after you create the voucher. Customers can’t pay a Multibanco voucher after it expires. After expiration, the PaymentIntent’s status transitions from requires_action to processing, and Stripe sends a payment_intent.processing event.
The PaymentIntent remains in the processing status for a maximum buffer period of 4 days to allow for potential completed payment notification delays caused by bank-transfer delays. If the Multibanco payment doesn’t complete within the buffer period, the PaymentIntent’s status transitions to requires_payment_method and Stripe sends a payment_intent.payment_failed event. If you receive the customer’s funds after the buffer period, Stripe automatically initiates a refund process for the mispaid amount.
Cancelation
You can cancel Multibanco vouchers using Cancel a PaymentIntent. After cancelation, Stripe sends a payment_intent.canceled event.
If a customer’s funds are received for a canceled Multibanco voucher, Stripe automatically initiates a refund process for the mispaid amount.
Note
Canceling a pending payment invalidates the original voucher instructions. When you cancel a pending Multibanco payment, inform your customer.
When you successfully reconfirm a PaymentIntent in status requires_action, Stripe creates new voucher instructions and a new hosted_voucher_url. You must provide them to your customer.
Refunds
Learn about Multibanco refunds.