Payment Method Types/
PayPal/
Payment Flow/
Vaulted Payments

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.

Vaulting creates a PayPal pre-approved payment between you and the customer, displayed in the customer's account profile on PayPal.com.

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)

pwpp_android_screens

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 flowAnchorIcon

  1. Kotlin
// Pass the user's email on the vault request
  val vaultRequest = PayPalVaultRequest(hasUserLocationConsent = true)
  vaultRequest.userAuthenticationEmail = "\<USER_EMAIL>"
  1. Groovy
dependencies {
    implementation 'com.braintreepayments.api:paypal:5.2.0'
}

Invoking the Vault flowAnchorIcon

InitializationAnchorIcon

Create a PayPalLauncher inside of your Activity's onCreate() . Then, create a PayPalClient with a Tokenization Key or Client Token and an appLinkReturnUrl that is used to return to your app from the PayPal payment flows.

  1. Kotlin
override fun onCreate(savedInstanceState: Bundle?) {
    super.onCreate(savedInstanceState)

    // PayPalLauncher must be initialized in onCreate
    payPalLauncher = PayPalLauncher()

    // can initialize the PayPalClient outside of onCreate if desired
    payPalClient = PayPalClient(
        context = this,
        authorization = "[TOKENIZATION_KEY or CLIENT_TOKEN]",
        appLinkReturnUrl = Uri.parse("https://merchant-app.com"), // Merchant App Link
        "com.merchant.app.deeplink.braintree" // Fallback deep link return url scheme
    )

Request a paymentAnchorIcon

After the user clicks the PayPal button, create a PayPalVaultRequest and call PayPalClient.createPaymentAuthRequest() and handle its result. If the result is Failure, handle the error. If the result is ReadyToLaunch, invoke PayPalLauncher.launch() and check the returned PayPalPendingRequest.

If Started is returned, the PayPal flow was launched and the Started.pendingRequestString needs to be persisted. If Failure was returned, handle the error.

  1. Kotlin
private fun onPayPalButtonClick() {
    val payPalVaultRequest = PayPalVaultRequest(
        hasUserLocationConsent = true,
        billingAgreementDescription = "Your agreement description"
    )
    payPalClient.createPaymentAuthRequest(this, payPalVaultRequest) { paymentAuthRequest ->
        when (paymentAuthRequest) {
            is PayPalPaymentAuthRequest.ReadyToLaunch -> {
                val pendingRequest = payPalLauncher.launch(this, paymentAuthRequest)
                when (pendingRequest) {
                    is PayPalPendingRequest.Started -> {/* store pending request */ }
                    is PayPalPendingRequest.Failure -> { /* handle error */ }
                }
            }
            is PayPalPaymentAuthRequest.Failure -> { /* handle paymentAuthRequest.error */ }
        }
    }
}

Handle the payment resultAnchorIcon

Once the user completes or cancels the PayPal Vault flow the Intent needs to be handled. If your Activity's launch mode is >SINGLE_TOP, the Intent needs to be handled in onNewIntent(). For all other launch modes, handle the Intent in onResume().

Call PayPalLauncher.handleReturnToApp() and pass in the persisted pendingRequestString and Intent. Handle the returned PayPalPaymentAuthResult.

If NoResult is returned, the user has canceled the payment flow or returned to the app without completing the payPal flow. If Failure is returned, handle the error. If Success is returned, pass the Success object to PayPalClient.tokenize().

The PayPalClient.tokenize() function takes a PayPalTokenizeCallback which returns a PayPalResult. When the result is Cancel, the user canceled the flow. When the result is Failure, handle the error. When the result is Success, a nonce value is returned inside of PayPalAccountNonce.

You can query the PayPalAccountNonce result for specific customer information if needed.

  1. Kotlin
// ONLY REQUIRED IF YOUR ACTIVITY LAUNCH MODE IS SINGLE_TOP
override fun onNewIntent(intent: Intent) {
    super.onNewIntent(intent)
    handleReturnToApp(intent)
}

// ALL OTHER ACTIVITY LAUNCH MODES
override fun onResume() {
    super.onResume()
    handleReturnToApp(intent)
}

private fun handleReturnToApp(intent: Intent) {
    // fetch stored PayPalPendingRequest.Success
    val pendingRequest: String = fetchPendingRequestFromPersistantStore()
    when (val paymentAuthResult = payPalLauncher.handleReturnToApp(
        pendingRequest = PayPalPendingRequest.Started(pendingRequest),
        intent = intent
    )) {
        is PayPalPaymentAuthResult.Success -> {
            completePayPalFlow(paymentAuthResult)
            // clear stored PayPalPendingRequest.Success
            // clear the intent data
            intent.data = null
        }

        is PayPalPaymentAuthResult.NoResult -> {
            // user returned to app without completing PayPal flow, handle accordingly
        }

        is PayPalPaymentAuthResult.Failure -> {
            // handle error case
        }
    }
}

private fun completePayPalFlow(paymentAuthResult: PayPalPaymentAuthResult.Success) {
    payPalClient.tokenize(paymentAuthResult) { result ->
        when (result) {
            is PayPalResult.Success -> { /* handle result.nonce */ }
            is PayPalResult.Failure -> { /* handle result.error */ }
            is PayPalResult.Cancel -> { /* handle user canceled */ }
        }
    }
}

Complete IntegrationAnchorIcon

  1. Kotlin
class MyActivity : AppCompatActivity() {

    private lateinit var payPalLauncher: PayPalLauncher
    private lateinit var payPalClient: PayPalClient

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // PayPalLauncher must be initialized in onCreate
        payPalLauncher = PayPalLauncher()

        // can initialize the PayPalClient outside of onCreate if desired
        payPalClient = PayPalClient(
        context = this,
        authorization = "[TOKENIZATION_KEY or CLIENT_TOKEN]",
        appLinkReturnUrl = Uri.parse("https://merchant-app.com"), // Merchant App Link
        "com.merchant.app.deeplink.braintree" // Fallback deep link return url scheme
    )
    
    // ONLY REQUIRED IF YOUR ACTIVITY LAUNCH MODE IS SINGLE_TOP
    override fun onNewIntent(intent: Intent) {
        super.onNewIntent(intent)
        handleReturnToApp(intent)
    }

    // ALL OTHER ACTIVITY LAUNCH MODES
    override fun onResume() {
        super.onResume()
        handleReturnToApp(intent)
    }

    private fun handleReturnToApp(intent: Intent) {
        // fetch stored PayPalPendingRequest.Success
        val pendingRequest: String = fetchPendingRequestFromPersistantStore()
        when (val paymentAuthResult = payPalLauncher.handleReturnToApp(
            pendingRequest = PayPalPendingRequest.Started(pendingRequest),
            intent = intent
        )) {
            is PayPalPaymentAuthResult.Success -> {
                completePayPalFlow(paymentAuthResult)
                // clear stored PayPalPendingRequest.Success
            }

            is PayPalPaymentAuthResult.NoResult -> {
                // user returned to app without completing PayPal flow, handle accordingly
            }

            is PayPalPaymentAuthResult.Failure -> {
                // handle error case
            }
        }
    }

    private fun completePayPalFlow(paymentAuthResult: PayPalPaymentAuthResult.Success) {
        payPalClient.tokenize(paymentAuthResult) { result ->
            when (result) {
                is PayPalResult.Success -> { /* handle result.nonce */ }
                is PayPalResult.Failure -> { /* handle result.error */ }
                is PayPalResult.Cancel -> { /* handle user canceled */ }
            }
        }
    }

    private fun onPayPalButtonClick() {
        val payPalVaultRequest = PayPalVaultRequest(
            hasUserLocationConsent = true,
            billingAgreementDescription = "Your agreement description"
        )
        payPalClient.createPaymentAuthRequest(this, payPalVaultRequest) { paymentAuthRequest ->
            when (paymentAuthRequest) {
                is PayPalPaymentAuthRequest.ReadyToLaunch -> {
                    val pendingRequest = payPalLauncher.launch(this, paymentAuthRequest)
                    when (pendingRequest) {
                        is PayPalPendingRequest.Started -> {/* store pending request */ }
                        is PayPalPendingRequest.Failure -> { /* handle error */ }
                    }
                }
                is PayPalPaymentAuthRequest.Failure -> { /* handle paymentAuthRequest.error */ }
            }
        }
    }
}

Collecting device dataAnchorIcon

Collecting device data from your customers is required when initiating non-recurring transactions from Vault records. Collecting and passing this data with transactions will help reduce decline rates.

DataCollector enables you to collect data about a customer's device and correlate it with a session identifier on your server.

Integrating App SwitchAnchorIcon

App Switch allows PayPal users who have the PayPal mobile app installed to complete their checkout directly in the app, whenever it’s available.

To support this behavior, merchants need to implement a new integration pattern called redirect flow. This flow uses a full-page client-side redirect from the browser, which can either:

  • Switch the user to the PayPal app, or
  • Redirect to PayPal in the same browser tab.
Key BenefitsAnchorIcon
  • 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 addressAnchorIcon

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 supportAnchorIcon

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

Currency presentmentAnchorIcon

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 →