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 BTPayPalCheckoutRequest with requestBillingAgreement set to true.

  1. Swift
let request = BTPayPalCheckoutRequest(
    amount: "10.00",
    requestBillingAgreement: 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. Swift
let billingPricing = BTPayPalBillingPricing(
    pricingModel: .fixed,
    amount: "9.99",
    reloadThresholdAmount: "99.99"
)

let billingCycle = BTPayPalBillingCycle(
    isTrial: false,
    numberOfExecutions: 1,
    interval: .month,
    intervalCount: 1,
    sequence: 1,
    startDate: "2024-08-01",
    pricing: billingPricing
)

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

let recurringBillingDetails = BTPayPalRecurringBillingDetails(
    billingCycles: [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"
)

let request = BTPayPalCheckoutRequest(
    amount: "10.00",
    requestBillingAgreement: true,
    billingAgreementDescription: "Your Vogue Magazine subscription", // optional
    recurringBillingDetails: recurringBillingDetails,                // optional
    recurringBillingPlanType: .subscription,                         // optional
    amountBreakdown: amountBreakdown                                 // optional
)

ParametersAnchorIcon

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