Vaulted Payments

Vaulted payments with PayPal account will allow you to charge the account in the future without requiring your customer to be present during the transaction or re-authenticate with PayPal when they are present during the transaction.

Important

The SSL certificates for Braintree Mobile (iOS and Android) SDKs are set to expire on March 30, 2026. This will impact existing versions of the SDK in published versions of your app. To reduce the impact, upgrade the iOS SDK to version 6.17.0+ for the new SSL certifications.

If you do not decommission your app versions that include the older SDK versions or force upgrade your app with the updated certificates by the expiration date, 100% of your customer traffic will fail.

The Vault is used to process payments with our recurring billing feature, and is also used for non-recurring transactions so that your customers don't need to re-enter their information each time they make a purchase from you.

Vaulted payments with PayPal account allows you to charge the account in the future without requiring your customer’s presence during the transaction.

The vaulted payment flow lets the user:

Select or add shipping addresses in the PayPal account
Select or add funding instruments in the PayPal account
Two-factor authentication support (currently only for US, UK, CA, DE, AT, and AU)

Typical use cases for the vaulted payment flow:

Faster payments for repeat customers
Subscriptions
Recurring billing (e.g. automatic top-up or usage based charges)

Launch the flow

swift

// Pass the user's email on the vault request
let vaultRequest = BTPayPalVaultRequest()
vaultRequest.userAuthenticationEmail = "\<USER_EMAIL>"

Invoking the Vault flow

Swift

import BraintreePayPal

class MyViewController: UIViewController {
    var apiClient: BTAPIClient?
    var payPalClient: BTPayPalClient?

    override func viewDidLoad() {
        super.viewDidLoad()
        apiClient = BTAPIClient(authorization: "<#CLIENT_AUTHORIZATION#>")!
        payPalClient = BTPayPalClient(apiClient: apiClient)
    }

    func startCheckout() {
        let request = BTPayPalVaultRequest()
        request.billingAgreementDescription = "Your agreement description" // Displayed in customer's PayPal account
        payPalClient.tokenize(request) { (tokenizedPayPalAccount, error) -> Void in
            if let tokenizedPayPalAccount = tokenizedPayPalAccount {
                print("Got a nonce: \(tokenizedPayPalAccount.nonce)")
                // Send payment method nonce to your server to create a transaction
            } else if let error = error {
                // Handle error here...
            } else {
                // Buyer canceled payment approval
            }
        }
    }
}

Collecting device data

Collecting device data from your customers is required when initiating non-recurring transactions from Vault records. For instructions, see the Premium Fraud Management Tools Guide.

App Switch

The App Switch initiative enables PayPal users who have a PayPal installed on their phone to complete payments on the PayPal app when it is available.

In this experience the SDK will attempt to switch to the PayPal App after calling tokenize if the PayPal App is installed and the user meets eligibility requirements. If the switch into the PayPal App cannot be completed, we will fall back to the ASWebAuthenticationSession experience.

Note

BTAPIClient needs to be instantiated during the app load phase instead of during on button click.

Key Benefits

Faster checkout: Customers can complete payments without re-entering login credentials.
Improved mobile experience: The native app interface provides smoother interaction than web-based flows.
Higher conversion rates: Reduced friction leads to fewer abandoned transactions.
Seamless fallback: Automatically falls back to standard web checkout when the app isn’t available.

Ready to implement App Switch? Continue to the App Switch Integration Guide for detailed implementation steps, code examples, and important considerations for your checkout flow.

Shipping address

Shipping addresses may or may not be collected during the PayPal Vault flow. However, if you choose to collect shipping addresses yourself, it can be passed along with the server side Transaction.Sale call. Look at the Server-side page for more information.

Country and language support

PayPal is available to merchants in all countries that we support and to customers in 140+ countries.

Currency presentment

In the Vault flow itself, the transaction currency and amount are not displayed to the customer. It is up to you to display these details in your checkout flow somewhere (e.g. cart page, order review page, etc.). Our Server-Side guide outlines which currencies are supported for PayPal transactions.

Next Page: Recurring Payments →