Payment Method Types/
PayPal/
Payment Flow/
Checkout with Vault

Checkout with Vault

OverviewAnchorIcon

The Checkout with Vault flow allows you to collect a payment and create a billing agreement in a single checkout session. The customer completes a standard PayPal checkout, and their PayPal account is simultaneously vaulted for future merchant-initiated payments.

This is distinct from the Recurring Payments flow, which uses a Billing Without Purchase checkout (no transaction occurs at signup). Use Checkout with Vault when you want to charge the customer immediately and store their payment method for future use.

IntegrationAnchorIcon

To enable this flow, construct a PayPalCheckoutRequest with shouldRequestBillingAgreement set to true.

  1. Kotlin
val request = PayPalCheckoutRequest(
    amount = "10.00",
    hasUserLocationConsent = true,
    shouldRequestBillingAgreement = true
)

You can optionally provide a billingAgreementDescription to display a custom message to the customer during checkout, and pass recurringBillingDetails and recurringBillingPlanType if this checkout is the entry point for a recurring arrangement:

  1. Kotlin
val billingPricing = PayPalBillingPricing(
    pricingModel = PayPalPricingModel.FIXED,
    amount = "9.99",
    reloadThresholdAmount = "99.99"
)

val billingCycle = PayPalBillingCycle(
    isTrial = false,
    numberOfExecutions = 1,
    interval = PayPalBillingInterval.MONTH,
    intervalCount = 1,
    sequence = 1,
    startDate = "2024-08-01",
    pricing = billingPricing
)

val amountBreakdown = AmountBreakdown(
    itemTotal = "9.99",    // required
    taxTotal = "0.99",     // required when lineItems.taxAmount exists
    shippingTotal = "1.99" // optional
)

val recurringBillingDetails = PayPalRecurringBillingDetails(
    billingCycles = listOf(billingCycle),
    currencyISOCode = "USD",
    totalAmount = "32.56",
    productName = "Vogue Magazine",
    productDescription = "Home delivery to Chicago, IL",
    productQuantity = 1,
    oneTimeFeeAmount = "9.99",
    shippingAmount = "1.99",
    productAmount = "19.99",
    taxAmount = "0.59"
)

val request = PayPalCheckoutRequest(
    amount = "10.00",
    hasUserLocationConsent = true,
    shouldRequestBillingAgreement = true,
    billingAgreementDescription = "Your Vogue Magazine subscription", // optional
    recurringBillingDetails = recurringBillingDetails,                // optional
    recurringBillingPlanType = PayPalRecurringBillingPlanType.SUBSCRIPTION // optional
).also {
    it.amountBreakdown = amountBreakdown // optional
}

ParametersAnchorIcon

ParameterTypeDefaultDescription
shouldRequestBillingAgreementBoolfalseEnables the Checkout with Vault flow. The customer is prompted to consent to a billing agreement during checkout.
billingAgreementDescriptionString?nullCustom description displayed to the customer for the billing agreement.
recurringBillingDetailsPayPalRecurringBillingDetails?nullRecurring billing product details. See Recurring Payments.
recurringBillingPlanTypePayPalRecurringBillingPlanType?nullRecurring billing plan type (e.g. .subscription, .recurring, .installment, .unscheduled).
amountBreakdownAmountBreakdown?nullBreakdown of items associated with the total cost. Note: discountTotal, handlingTotal, insuranceTotal, and shippingDiscount are not accepted when passing recurringBillingDetails.