Accept a Multibanco payment
Learn how to accept the Multibanco payment method.
Caution
Stripe automatically presents your customers payment method options by evaluating their currency, payment method restrictions, and other parameters. We recommend that you configure your payment methods from the Stripe Dashboard using the instructions in Accept a payment.
If you want to continue manually configuring the payment methods you present to your customers with Checkout, use this guide. Otherwise, migrate to the Dashboard.
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 the Payment Intents API.
To complete a transaction, customers receive a voucher that includes 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 are not supported).
Accept a payment
Note
Build an integration to accept a payment with Checkout before using this guide.
Enable Multibanco by making the following updates to your card payment integration.
Enable Multibanco as a payment method
When creating a new Checkout Session, you need to:
- Add
multibancoto the list ofpayment_.method_ types - Make sure all your
line_use theitems eurcurrency.
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_. 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. on the requires_ event, and extract the hosted_ 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_. | Contact the customer by email and request that they place a new order. |
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 | |
|---|---|
| Simulates a Multibanco voucher that a customer pays. The Example: jenny@example.com |
| Simulates a Multibanco voucher that a customer pays immediately. The Example: succeed_immediately@example.com |
| Simulates a Multibanco voucher that expires immediately. The Example: expire_immediately@example.com |
| Simulates a Multibanco voucher that expires before a customer pays. The Example: expire_with_delay@example.com |
| Simulates a Multibanco voucher that never succeeds. The Example: fill_never@example.com |
Expiration
Multibanco vouchers expire at the expires_ UNIX 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_ 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_ 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_, Stripe creates new voucher instructions and a new hosted_. You must provide them to your customer.