# Multibanco payments with Sources Use Sources to accept payments using Multibanco, the most popular payment method in Portugal. > We deprecated the Sources API and plan to remove support for local payment methods. If you currently integrate with Multibanco using the Sources API, you must [migrate to the Payment Methods API](https://docs.stripe.com/payments/payment-methods/transitioning.md). > > For information about integrating Multibanco with the current APIs, see [Multibanco payments](https://docs.stripe.com/payments/multibanco.md). Before you can use Multibanco, you must activate it in the [Dashboard](https://dashboard.stripe.com/account/payments/settings). Your use of Multibanco must be in accordance with our [Multibanco Terms of Service](https://stripe.com/multibanco/legal). Stripe users in Europe and the United States can accept Multibanco payments from customers in Portugal using [Sources](https://docs.stripe.com/sources.md)—a single integration path for creating payments using any supported method. During the payment process, a [Source](https://docs.stripe.com/api.md#sources) object is created and your customer is either redirected to the Multibanco website, your website, or a Multibanco ATM to send the funds. After completing this, your integration uses the source to make a charge request and complete the payment. Multibanco is a [push](https://docs.stripe.com/sources.md#pull-or-push-of-funds)-based, [single-use](https://docs.stripe.com/sources.md#single-use-or-reusable) and [synchronous](https://docs.stripe.com/sources.md#synchronous-or-asynchronous-confirmation) method of payment. This means your customer takes action to send the amount to you through a [receiver](https://docs.stripe.com/sources.md#flow-for-customer-action). Pushing funds might take as little as a few minutes or at most 7 days, because your customer must do this outside of your checkout flow. After the funds have been received, the amount is immediately available to be charged. The charge generates an immediate confirmation about the success or failure of a payment. ## Create a Source object A `Source` object is either created client-side using [Stripe.js](https://docs.stripe.com/payments/elements.md) or server-side using the [Source creation endpoint](https://docs.stripe.com/api.md#create_source), with the following parameters: | Parameter | Value | | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `type` | **multibanco** | | `amount` | A positive integer in the [smallest currency unit](https://docs.stripe.com/currencies.md#zero-decimal) representing the amount to charge the customer (for example, **1099** for a 10.99 EUR payment). | | `currency` | **eur** (Multibanco must always use Euros) | | `redirect[return_url]` | The URL the customer should be redirected to after the authorization process. | | `owner[email]` | The full email address of the customer. | To create a source with [Stripe.js](https://docs.stripe.com/payments/elements.md), first include the library within your website and set your [publishable API key](https://dashboard.stripe.com/apikeys). Once included, use the following `createSource` method to create a source client-side: ```json stripe.createSource({ type: 'multibanco', amount: 1099, currency: 'eur', owner: { name: 'Jenny Rosen', email: 'jenny.rosen@example.com', }, redirect: { return_url: 'https://shop.example.com/crtA6B28E1', }, }).then(function(result) { // handle result.error or result.source }); ``` Using either method, Stripe returns a `Source` object containing the relevant details for the method of payment used. Information specific to Multibanco is provided within the `multibanco` subhash. ```json { "id": "src_16xhynE8WzK49JbAs9M21jaR", "object": "source", "amount": 1099, "client_secret": "src_client_secret_UfwvW2WHpZ0s3QEn9g5x7waU", "created": 1445277809, "currency": "eur", "flow": "receiver", "livemode": true, "owner": { "address": null, "email": null, "name": "Jenny Rosen", "phone": null, "verified_address": null, "verified_email": null, "verified_name": "Jenny Rosen", "verified_phone": null }, "redirect": { "return_url": "https://shop.example.com/crtA6B28E1", "status": "pending", "url": "https://hooks.stripe.com/redirect/src_16xhynE8WzK49JbAs9M21jaR?client_secret=src_client_secret_UfwvW2WHpZ0s3QEn9g5x7waU" }, "receiver": { "address": "12345-123456789", "amount_charged": 0, "amount_received": 0, "amount_returned": 0, "refund_attributes_method": "email", "refund_attributes_status": "missing" }, "statement_descriptor": null, "status": "pending", "type": "multibanco", "usage": "single_use", "multibanco": { "reference": "12345", "entity": "123456789", } } ``` ### Source creation in mobile applications If you’re building an iOS or Android app, you can implement sources using our mobile SDKs. ## Have the customer send the funds When creating a source, its status is initially set to `pending` and can’t yet be used to make a charge request. To pay with Multibanco, your customers need to initiate a transfer of funds from their bank account using reference and entity numbers provided by you and either their computer, phone, or local ATM. Portuguese merchants will often display these details within their checkout flow after the customer has confirmed their purchase and by including them in an order confirmation email. You may also redirect your customer to a Multibanco-hosted page that will display these details for you, by using the URL provided within the`redirect[url]` attribute of the `Source` object. Multibanco then redirects them back to the URL provided as a value of `redirect[return_url]`, regardless of whether funds have been sent or not. When the customer does send funds, the status of the `Source` object transitions to `chargeable`, allowing you to charge the source and complete the transaction. If you don’t do this, the status transitions to `canceled` after 6 hours. Stripe populates the `redirect[return_url]` with the following GET parameters when returning your customer to your website: - `source`: a string representing the original ID of the `Source` object - `livemode`: indicates if this is a live payment, either `true` or `false` - `client_secret`: used to confirm that the returning customer is the same one who triggered the creation of the source (source IDs aren’t considered secret) You may include any other GET parameters you may need when specifying `redirect[return_url]`. Don’t use the above as parameter names yourself as these would be overridden with the values we populate. ### Mobile applications To integrate Multibanco within a mobile application, provide your application URI scheme as the `redirect[return_url]` value. By doing so, your customers are returned to your app after completing authorization. ### Testing the redirect and payment When creating a `Source` object using your test API keys, the test payment is fulfilled with a three second delay. Use one of the following test email addresses when you need to test Multibanco payments under different conditions. | Email | Description | | -------------------------------------- | --------------------------------------------------------------------------------------------- | | `{any_prefix}+fill_never@{any_domain}` | Funds are never sent to the receiver address. | | `{any_prefix}+fill_now@{any_domain}` | The next time that the receiver is retrieved after creation, it has received the full amount. | The URL returned in the `redirect[url]` field of takes you to a sample payment page. Returning from this page takes you to the URL specified in `redirect[return_url]`. ## Charge the Source Your integration must use [webhooks](https://docs.stripe.com/webhooks.md) in order for you to receive notifications of status changes on `Source` and `Charge` objects. Once the customer has pushed the funds, the source’s `status` transitions to `chargeable` and it can be used to make a charge request. This transition happens asynchronously and may occur after the customer was redirected back to your website. It may take minutes, hours, or days for a customer to send the funds after following and returning from the redirect. For this reason it’s essential that your integration rely on *webhooks* (A webhook is a real-time push notification sent to your application as a JSON payload through HTTPS requests) to determine when the source becomes chargeable to create a charge. ### Webhooks The following webhook events are sent to notify you about changes to the source’s status: | Event | Description | | ------------------- | ---------------------------------------------------------------------------------------------------- | | `source.chargeable` | A `Source` object becomes `chargeable` after a customer has authenticated and verified a payment. | | `source.failed` | A `Source` object failed to become chargeable as your customer declined to authenticate the payment. | | `source.canceled` | A `Source` object expired and can’t be used to create a charge. | ### Make a charge request using the source Once the source is chargeable, from your `source.chargeable` webhook handler, you can make a charge request using the source ID as the value for the `source` parameter to complete the payment. #### curl ```bash curl https://api.stripe.com/v1/charges \ -u <>: \ -d amount="1099" \ -d currency="eur" \ -d source=src_18eYalAHEMiOZZp1l9ZTjSU0 ``` Multibanco Sources are [single-use](https://docs.stripe.com/sources.md#single-use-or-reusable) and can’t be used for recurring or additional payments. ## Confirm that the charge has succeeded Since Multibanco is a [synchronous](https://docs.stripe.com/sources.md#synchronous-or-asynchronous-confirmation) payment method and the customer has already sent funds, unless there is an unexpected error, the [Charge](https://docs.stripe.com/api.md#charge_object) will immediately succeed. You’ll also receive the following webhook event as the charge is created: | Event | Description | | ------------------ | ------------------------------------------------- | | `charge.succeeded` | The charge succeeded and the payment is complete. | We recommend that you rely on the `charge.succeeded` webhook event to notify your customer that the payment process has been completed and their order is confirmed. ### Disputed payments The risk of fraud or unrecognized payments is extremely low with Multibanco as the customer has to push funds from their bank account. As such, there is no dispute process that can result in a chargeback and funds withdrawn from your Stripe account. ### Mispayments Because a customer can make a payment at any time directly through the ATM, it’s possible (although unlikely) for a customer to supply funds to a canceled or expired source. In these cases, Stripe automatically initiates the refund process for the incorrectly paid amount as described above. ### Refunds Payments made with Multibanco can only be submitted for refund within 180 days from the date of the original charge. After 180 days, it’s no longer possible to refund the charge. Multibanco payments can be refunded through either the [Dashboard](https://dashboard.stripe.com/test/payments) or [API](https://docs.stripe.com/api.md#create_refund). Multibanco doesn’t itself provide any facility for refunds, which means Stripe handles this by creating an IBAN credit transfer. We contact the customer at the email address provided during source creation, and a credit is sent to the customer once they’ve supplied their account information. No interaction from the merchant is required beyond the initial refund request. Some users may want to manage the collection of the refund IBAN details themselves. Multibanco refunds require the customer’s IBAN number, account holder name, and the full address including street, city, country, and postal code. Please [contact us](https://support.stripe.com/email) to learn more about this option. ### Sources expiration A `chargeable` Multibanco source must be charged within six hours of becoming `chargeable`. If it isn’t, its status is automatically transitioned to `canceled` and your integration receives a `source.canceled` webhook event. Once a chargeable source is canceled, the customer’s authenticated Multibanco payment is refunded automatically—no money is moved into your account. For this reason, make sure the order is canceled on your end and the customer is notified when you receive the `source.canceled` event. Additionally, `pending` sources are canceled after seven days if they’re not used to receive funds. This ensures that all sources eventually transition out of their `pending` state to the `canceled` state if they’re not used. ## See also - [Other supported payment methods](https://docs.stripe.com/sources.md) - [Sources API reference](https://docs.stripe.com/api.md#sources)