Release braintree-web 3.138.0 source

Author: braintreeps

.storybook/stories/PayPalCheckoutV6/PayPalCheckoutV6.stories.ts

@@ -17,12 +17,14 @@ PayPal Checkout V6 - Payment integration with multiple flow types.
 
 **Payment Flow Types:**
 - **One-Time Payments**: Best for infrequent payments with higher AOV (retail, e-commerce)
+- **Checkout with Vault**: Single flow for payment + vault consent (subscriptions with initial charge)
 - **Vaulted Payments**: Ideal for high-frequency, low-AOV purchases (food delivery, marketplaces)
 - **Recurring Payments**: Perfect for subscriptions and automated billing (SaaS, streaming, utilities)
 - **Vault-Initiated Checkout**: Use a previously vaulted PayPal account for subsequent payments
 
 **Implementation Features:**
 - One-time payment session creation
+- Checkout with vault session (payment + save)
 - Billing agreement/vault flow
 - Vault-initiated checkout
 - Payment tokenization
@@ -1093,3 +1095,211 @@ export const LineItemsAndShipping: StoryObj = {
     ["client.min.js", "paypal-checkout-v6.min.js"]
   ),
 };
+
+// Checkout with Vault Story
+const createCheckoutWithVaultForm = (): HTMLElement => {
+  const container = document.createElement("div");
+  container.innerHTML = `
+    <div class="shared-container paypal-container">
+      <h2>PayPal V6 Checkout with Vault</h2>
+
+      <div class="paypal-description">
+        <p class="shared-description">
+          Create a one-time payment while simultaneously saving the PayPal account
+          for future transactions. The returned nonce can be used for both the
+          immediate charge and future recurring payments.
+        </p>
+
+        <div class="paypal-form-group">
+          <label class="paypal-checkbox-label">
+            <input type="checkbox" id="advancedOptionsToggle" class="paypal-checkbox" />
+            <span class="paypal-checkbox-text">Include line items and shipping options</span>
+          </label>
+        </div>
+      </div>
+
+      <div id="paypal-button" class="paypal-button-container"></div>
+
+      <div id="result" class="shared-result"></div>
+    </div>
+  `;
+
+  return container;
+};
+
+const CHECKOUT_WITH_VAULT_BASIC = {
+  amount: "10.00",
+  currency: "USD",
+  intent: "capture",
+  billingAgreementDetails: {
+    description: "Monthly subscription to Totally Real Products!",
+  },
+};
+
+const CHECKOUT_WITH_VAULT_ADVANCED = {
+  amount: "20.00",
+  currency: "USD",
+  intent: "capture",
+  billingAgreementDetails: {
+    description: "Premium subscription service with initial payment",
+  },
+  lineItems: [
+    {
+      quantity: "1",
+      unitAmount: "15.00",
+      name: "Premium Subscription (First Month)",
+      kind: "debit",
+    },
+  ],
+  shippingOptions: [
+    {
+      id: "standard",
+      label: "Standard Shipping",
+      selected: true,
+      type: "SHIPPING",
+      amount: {
+        currency: "USD",
+        value: "5.00",
+      },
+    },
+    {
+      id: "express",
+      label: "Express Shipping",
+      selected: false,
+      type: "SHIPPING",
+      amount: {
+        currency: "USD",
+        value: "10.00",
+      },
+    },
+  ],
+  amountBreakdown: {
+    itemTotal: "15.00",
+    shipping: "5.00",
+  },
+};
+
+const setupCheckoutWithVault = async (
+  container: HTMLElement
+): Promise<void> => {
+  const clientToken = await getClientToken();
+  const resultDiv = container.querySelector("#result") as HTMLElement;
+  const advancedToggle = container.querySelector(
+    "#advancedOptionsToggle"
+  ) as HTMLInputElement;
+
+  if (!clientToken) {
+    resultDiv.className =
+      "shared-result shared-result--visible shared-result--error";
+    resultDiv.innerHTML = `
+      <strong>Configuration Error</strong><br>
+      <small>Please add STORYBOOK_BRAINTREE_CLIENT_TOKEN to your .env file</small>
+    `;
+    return;
+  }
+
+  try {
+    const braintree = getBraintreeSDK(resultDiv);
+    const clientInstance = await braintree.client.create({
+      authorization: clientToken,
+    });
+
+    const paypalCheckoutV6Instance = await braintree.paypalCheckoutV6.create({
+      client: clientInstance,
+    });
+
+    await paypalCheckoutV6Instance.loadPayPalSDK();
+
+    const getSessionOptions = () => {
+      const baseOptions = advancedToggle.checked
+        ? CHECKOUT_WITH_VAULT_ADVANCED
+        : CHECKOUT_WITH_VAULT_BASIC;
+
+      return {
+        ...baseOptions,
+        onApprove: async (data: IPayPalV6ApproveData) => {
+          const tokenizeData = {
+            payerID: data.payerID || data.payerId || data.PayerID,
+            orderID: getOrderId(data),
+          };
+
+          const payload =
+            await paypalCheckoutV6Instance.tokenizePayment(tokenizeData);
+
+          const email =
+            payload.details?.email || payload.details?.payerEmail || "N/A";
+          const mode = advancedToggle.checked
+            ? "with line items and shipping"
+            : "basic payment";
+
+          resultDiv.className =
+            "shared-result shared-result--visible shared-result--success";
+          resultDiv.innerHTML = `
+            <strong>Payment authorized & account vaulted!</strong><br>
+            <small>Nonce: ${payload.nonce}</small><br>
+            <small>Payer Email: ${email}</small><br>
+            <small>Amount: $${advancedToggle.checked ? "20.00" : "10.00"}</small><br>
+            <small>Mode: ${mode}</small>
+          `;
+        },
+
+        onCancel: () => {
+          resultDiv.className = "shared-result shared-result--visible";
+          resultDiv.innerHTML = `
+            <strong>Payment Cancelled</strong><br>
+            <small>Customer cancelled the checkout with vault flow.</small>
+          `;
+        },
+
+        onError: (err: IBraintreeError) => {
+          showDetailedError(resultDiv, "PayPal Error", err);
+        },
+      };
+    };
+
+    const paypalButtonContainer = container.querySelector(
+      "#paypal-button"
+    ) as HTMLElement;
+    const button = document.createElement("button");
+    button.textContent = "Checkout with Vault";
+    button.className = "paypal-button";
+    button.style.cssText = `
+      background-color: #0070ba;
+      color: white;
+      border: none;
+      padding: 12px 24px;
+      font-size: 16px;
+      border-radius: 4px;
+      cursor: pointer;
+      font-weight: 500;
+      width: 100%;
+    `;
+
+    button.addEventListener("click", () => {
+      const session =
+        paypalCheckoutV6Instance.createCheckoutWithVaultSession(
+          getSessionOptions()
+        );
+      session.start();
+    });
+
+    paypalButtonContainer.appendChild(button);
+  } catch (error) {
+    showDetailedError(
+      resultDiv,
+      "Initialization Error",
+      error as IBraintreeError
+    );
+  }
+};
+
+export const CheckoutWithVault: StoryObj = {
+  render: createSimpleBraintreeStory(
+    async (container) => {
+      const formContainer = createCheckoutWithVaultForm();
+      container.appendChild(formContainer);
+      await setupCheckoutWithVault(formContainer);
+    },
+    ["client.min.js", "paypal-checkout-v6.min.js"]
+  ),
+};

.storybook/types/global.d.ts

@@ -997,6 +997,7 @@ interface IPayPalCheckoutV6TokenizePayload {
     firstName?: string;
     lastName?: string;
   };
+  shippingOptionId?: string;
 }
 
 /**
@@ -1086,6 +1087,51 @@ interface IPayPalCheckoutV6Instance {
     onCancel?: () => void;
     onError?: (err: IBraintreeError) => void;
   }) => IPayPalCheckoutV6Session;
+  createCheckoutWithVaultSession: (options: {
+    amount: string;
+    currency: string;
+    intent?: "capture" | "authorize" | "order";
+    billingAgreementDetails?: {
+      description: string;
+    };
+    returnUrl?: string;
+    cancelUrl?: string;
+    lineItems?: Array<{
+      quantity: string;
+      unitAmount: string;
+      name: string;
+      kind: "debit" | "credit";
+      unitTaxAmount?: string;
+      description?: string;
+    }>;
+    shippingOptions?: Array<{
+      id: string;
+      label: string;
+      selected: boolean;
+      type: "SHIPPING" | "PICKUP";
+      amount: { currency: string; value: string };
+    }>;
+    amountBreakdown?: {
+      itemTotal?: string;
+      shipping?: string;
+      handling?: string;
+      taxTotal?: string;
+      insurance?: string;
+      shippingDiscount?: string;
+      discount?: string;
+    };
+    displayName?: string;
+    userAuthenticationEmail?: string;
+    presentationMode?: string;
+    onShippingAddressChange?: (data: {
+      shippingAddress?: { city?: string; state?: string };
+      orderID?: string;
+      orderId?: string;
+    }) => void | Promise<unknown>;
+    onApprove: (data: IPayPalV6ApproveData) => void | Promise<void>;
+    onCancel?: () => void;
+    onError?: (err: IBraintreeError) => void;
+  }) => IPayPalCheckoutV6Session;
   tokenizePayment: (data: {
     billingToken?: string;
     payerID?: string;

CHANGELOG.md

@@ -1,9 +1,15 @@
 # CHANGELOG
 
+## 3.138.0 (2026-03-10)
+
+- PayPal Checkout v6
+  - Add `createCheckoutWithVaultSession` method to enable charging and vaulting in a single session
+
 ## 3.137.0 (2026-03-02)
 
 - Alternative Payment Method
   - Add support for Alternative Payment Method `crypto`
+- Update Data Collector error object
 
 ## 3.136.0 (2026-02-10)
 

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "braintree-web",
-  "version": "3.137.0",
+  "version": "3.138.0",
   "license": "MIT",
   "main": "src/index.js",
   "private": true,

package.json

@@ -29,12 +29,22 @@ var ANALYTICS_EVENTS = {
   // Session Creation
   SESSION_CHECKOUT_CREATED: ANALYTICS_PREFIX + ".session.checkout.created",
   SESSION_VAULT_CREATED: ANALYTICS_PREFIX + ".session.vault.created",
+  SESSION_CHECKOUT_WITH_VAULT_CREATED:
+    ANALYTICS_PREFIX + ".session.checkout-with-vault.created",
 
   // Payment Flow
   PAYMENT_STARTED: ANALYTICS_PREFIX + ".payment.started",
   PAYMENT_APPROVED: ANALYTICS_PREFIX + ".payment.approved",
   PAYMENT_CANCELED: ANALYTICS_PREFIX + ".payment.canceled",
 
+  // Checkout with Vault Flow
+  CHECKOUT_WITH_VAULT_STARTED:
+    ANALYTICS_PREFIX + ".checkout-with-vault.started",
+  CHECKOUT_WITH_VAULT_APPROVED:
+    ANALYTICS_PREFIX + ".checkout-with-vault.approved",
+  CHECKOUT_WITH_VAULT_CANCELED:
+    ANALYTICS_PREFIX + ".checkout-with-vault.canceled",
+
   // Order Creation
   CREATE_ORDER_STARTED: ANALYTICS_PREFIX + ".create-order.started",
   CREATE_ORDER_SUCCEEDED: ANALYTICS_PREFIX + ".create-order.succeeded",