Accept a Multibanco payment

First, you need a Stripe account. Register now.

Server-side

This integration requires endpoints on your server that talk to the Stripe API. Use the official libraries for access to the Stripe API from your server:

# Available as a gem
sudo gem install stripe

# If you use bundler, you can add this line to your Gemfile
gem 'stripe'

Client-side

The Stripe iOS SDK is open source, fully documented, and compatible with apps supporting iOS 13 or above.

Configure the SDK with your Stripe publishable key on app start. This enables your app to make requests to the Stripe API.

import UIKit
import StripePaymentsUI

@main
class AppDelegate: UIResponder, UIApplicationDelegate {

    func application(_ application: UIApplication, didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
        StripeAPI.defaultPublishableKey = 
"pk_test_TYooMQauvdEDq54NiTphI7jx"
        // do any other necessary launch configuration
        return true
    }
}

Stripe uses a PaymentIntent object to represent your intent to collect payment from a customer, tracking state changes from Multibanco voucher creation to payment completion.

Server-side

Create a PaymentIntent on your server with an amount and the eur currency (Multibanco doesn’t support other currencies). If you already have an integration using the Payment Intents API, add multibanco to the list of payment method types for your PaymentIntent.

curl https://api.stripe.com/v1/payment_intents \
  -u "
sk_test_BQokikJOvBiI2HlWgH4olfQ2
:" \
  -d amount=1099 \
  -d currency=eur \
  -d "payment_method_types[]"=multibanco

The returned PaymentIntent includes a client secret, that you’ll use to confirm the PaymentIntent. Send the client secret back to the client so you can use it in the next step.

Client-side

On the client, request a PaymentIntent from your server and store its client secret.

class CheckoutViewController: UIViewController {
    var paymentIntentClientSecret: String?

    // ...continued from previous step

    override func viewDidLoad() {
        // ...continued from previous step
        startCheckout()
    }

    func startCheckout() {
        // Request a PaymentIntent from your server and store its client secret
        // Click View full sample to see a complete implementation
    }
}

In your app, collect the following required billing details from the customer. Create a STPPaymentIntentParams with the billing details.

let billingDetails = STPPaymentMethodBillingDetails()
billingDetails.email = "jenny@example.com"

Submit the customer’s billing details by calling STPPaymentHandler confirmPayment with the client secret of the PaymentIntent object that you created. This presents a webview to display the Multibanco voucher. Afterwards, the completion block is called with the result of the payment.

let paymentIntentParams = STPPaymentIntentParams(clientSecret: paymentIntentClientSecret)
let multibancoParams = STPPaymentMethodMultibancoParams();
paymentIntentParams.paymentMethodParams = STPPaymentMethodParams(
    multibanco: multibancoParams,
    billingDetails: billingDetails,
    metadata: nil
)

STPPaymentHandler.shared().confirmPayment(paymentIntentParams, with: self) { (handlerStatus, paymentIntent, error) in
    switch handlerStatus {
    case .succeeded:
        // The Multibanco voucher was displayed successfully. The customer can now pay the Multibanco voucher
    case .canceled:
        // Handle cancelation
    case .failed:
        // Handle failure
    @unknown default:
        fatalError()
    }
}

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, you can locate the hosted_voucher_url at payment_intent.next_action.multibanco_display_details.hosted_voucher_url.

Multibanco is a delayed notification payment method. A customer pays for a Multibanco voucher outside your checkout flow through online banking or from an ATM.

After a Multibanco payment completes, Stripe sends a payment_intent.succeeded event. Use the Dashboard or build a webhook handler to receive these events and run actions, such as sending an order confirmation email to your customer, logging the sale in a database, or initiating a shipping workflow.

Learn about Multibanco expiration.

Receive events and run business actions

Manually

Use the Stripe Dashboard to view all your Stripe payments, send email receipts, handle payouts, or retry failed payments.

View your test payments in the Dashboard.

Custom Code

Build a webhook handler to listen for events and build custom asynchronous payment flows. Test and debug your webhook integration locally with the Stripe CLI.

Learn how to build a custom webhook.

In a sandbox, set STPPaymentMethodBillingDetails email to the following values when you call STPPaymentHandler confirmPayment to test different scenarios.