> ## Documentation Index
> Fetch the complete documentation index at: https://docs.paypal.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK v6 Reference

Use the PayPal v6 JavaScript SDK to integrate PayPal, Venmo, Pay Later, and other payment methods into web applications. This reference covers payment eligibility checking, session management, callback handling, and web components.

<Tip>
  * For the React JavaScript SDK v6 reference, see [React SDK v6 Reference](/reference/sdk/react).
  * For setup and initialization, see [Set up JavaScript SDK v6](/developer/how-to/sdk/js/v6/configuration).
</Tip>

## Check payment eligibility

Before displaying payment buttons to your buyers, check which payment methods are available for the current transaction. Eligibility depends on various factors including the buyer's location, currency, merchant configuration, and transaction amount.

### `sdkInstance.findEligibleMethods(options?)`

Use `findEligibleMethods` to determine which payment methods are available for the current context. This method queries PayPal's eligibility service and returns an object with methods to check specific payment options.

#### Parameters

<table>
  <thead>
    <tr>
      <th align="left">Parameter</th>
      <th align="left">Required</th>
      <th align="left">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>currencyCode</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> The three-letter ISO 4217 currency code for the transaction, for example, `"USD"`, `"EUR"`, or `"GBP"`. This affects payment method availability, especially for Pay Later options which have currency restrictions. Default: <code>"USD"</code></p>
      </td>
    </tr>

    <tr>
      <td><code>countryCode</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> The two-letter ISO 3166-1 alpha-2 country code representing the buyer's country. This determines regional payment method availability. For example, Venmo is only available in the US. If not specified, the SDK attempts to detect the buyer's country.</p>
      </td>
    </tr>

    <tr>
      <td><code>amount</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> The transaction amount as a string, for example, `"99.99"`. The amount affects Pay Later eligibility, as different financing options have minimum and maximum amount thresholds.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a promise that resolves to an EligiblePaymentMethods object with methods to check and retrieve payment method information.

The returned object provides these methods:

* `isEligible(method)` - Check if a specific payment method is available
* `getDetails(method)` - Get additional information about a payment method

#### Example

```javascript lines expandable theme={null}
// Check with default settings
const paymentMethods = await sdkInstance.findEligibleMethods();

// Check with specific currency and amount
const paymentMethods = await sdkInstance.findEligibleMethods({
  currencyCode: "USD",
  countryCode: "US",
  amount: "125.00",
});

// Use the eligibility results
if (paymentMethods.isEligible("paypal")) {
  // Show PayPal button
}

if (paymentMethods.isEligible("paylater")) {
  const details = paymentMethods.getDetails("paylater");
  // Show Pay Later button with product-specific messaging
}
```

### `paymentMethods.isEligible(method)`

Check whether a specific payment method is available for the current transaction.

#### Parameters

<table>
  <thead>
    <tr>
      <th align="left">Parameter</th>
      <th align="left">Required</th>
      <th align="left">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>method</code></td>
      <td>yes</td>

      <td>
        <p><strong>string.</strong> The payment method identifier to check.</p>
        <p>Supported values:</p>

        <ul>
          <li><code>paypal</code> — PayPal Checkout</li>
          <li><code>venmo</code> — Venmo (US only)</li>
          <li><code>paylater</code> — Pay Later / Pay in 4</li>
          <li><code>credit</code> — PayPal Credit</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns `true` if the payment method is available, `false` otherwise.

#### Example

```javascript lines  theme={null}
// Check individual payment methods
const canUsePayPal = paymentMethods.isEligible("paypal");
const canUseVenmo = paymentMethods.isEligible("venmo");

// Conditionally show buttons
if (paymentMethods.isEligible("venmo")) {
  document.getElementById("venmo-button").style.display = "block";
}
```

### `paymentMethods.getDetails(method)`

Retrieve additional configuration details for a specific payment method. This is particularly useful for Pay Later and PayPal Credit, which require additional attributes for proper button rendering.

#### Parameters

<table>
  <thead>
    <tr>
      <th align="left">Parameter</th>
      <th align="left">Required</th>
      <th align="left">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>method</code></td>
      <td>yes</td>

      <td>
        <p><strong>string.</strong> The payment method to get details for.</p>
        <p>Currently returns details for:</p>

        <ul>
          <li><code>paylater</code> — Returns product code and country</li>
          <li><code>credit</code> — Returns country configuration</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns an object with payment method-specific details. The structure varies by payment method.

For Pay Later:

```javascript theme={null}
{
  productCode: string; // Example: "PAY_IN_4"
  countryCode: string; // Example: "US"
}
```

For PayPal Credit:

```javascript theme={null}
{
  countryCode: string; // Example: "US"
}
```

#### Example

```javascript lines theme={null}
// Get Pay Later configuration
const payLaterDetails = paymentMethods.getDetails("paylater");
const button = document.querySelector("paylater-button");
button.productCode = payLaterDetails.productCode;
button.countryCode = payLaterDetails.countryCode;

// Get PayPal Credit configuration
const creditDetails = paymentMethods.getDetails("credit");
```

## Creating payment sessions

Payment sessions manage the complete payment flow from initiation through completion. Each payment method has its own session creation method that returns a session object with methods to start and control the payment process.

### `sdkInstance.createPayPalOneTimePaymentSession(options)`

Create a payment session for one-time PayPal payments. This session handles the complete PayPal Checkout flow, including payment approval, shipping address changes, and order updates.

#### Parameters

The options object configures callbacks that handle different stages of the payment flow. These callbacks allow you to respond to buyer actions and update your order accordingly.

<table>
  <thead>
    <tr>
      <th align="left">Parameter</th>
      <th align="left">Required</th>
      <th align="left">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>onApprove</code></td>
      <td>yes</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer approves the payment in the PayPal flow. This is where you should capture or authorize the payment on your server.</p>
        <p>The function receives a data object containing:</p>

        <ul>
          <li><code>orderId</code> — The PayPal order ID to capture</li>
          <li><code>payerId</code> — The buyer's PayPal payer ID</li>
        </ul>

        <p>This function can return a promise if you need to perform async operations like capturing the payment.</p>
      </td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer cancels the payment flow by closing the PayPal window or selecting cancel.</p>
        <p>The data object contains:</p>

        <ul>
          <li><code>orderId</code> — The order ID (if one was created)</li>
        </ul>

        <p>Use this callback to:</p>

        <ul>
          <li>Track abandoned checkouts</li>
          <li>Re-enable your checkout button</li>
          <li>Show a message to the buyer</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td>no</td>

      <td>
        <p><strong>function(error).</strong> Called when an error occurs during the payment flow. This includes network errors, validation errors, or payment failures.</p>
        <p>The error object contains:</p>

        <ul>
          <li><code>code</code> — Error code for identifying the issue</li>
          <li><code>message</code> — Human-readable error description</li>
        </ul>

        <p>Use this to display user-friendly error messages and log errors for debugging.</p>
      </td>
    </tr>

    <tr>
      <td><code>onShippingAddressChange</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer changes their shipping address within the PayPal flow. This allows you to update shipping costs or restrict certain addresses.</p>
        <p>The data object contains:</p>

        <ul>
          <li><code>errors</code> — Errors to show to the user</li>
          <li><code>orderId</code> — The current order ID</li>
          <li><code>shippingAddress</code> — The new address object</li>
        </ul>

        <p>Return a promise to update the order with new shipping costs. If you reject the promise, the address change will be rejected.</p>
      </td>
    </tr>

    <tr>
      <td><code>onShippingOptionsChange</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer selects a different shipping option, for example, standard or express shipping.</p>
        <p>The data object contains:</p>

        <ul>
          <li><code>errors</code> — Errors to show to the user</li>
          <li><code>orderId</code> — The current order ID</li>
          <li><code>selectedShippingOption</code> — The selected option details</li>
        </ul>

        <p>Return a promise to update the order total with the new shipping cost.</p>
      </td>
    </tr>

    <tr>
      <td><code>orderId</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> An existing PayPal order ID to use for this session. This allows you to create the order on your server before starting the payment flow (eager order creation).</p>
        <p>If not provided, you'll pass an order creation function to the <code>start()</code> method.</p>
      </td>
    </tr>

    <tr>
      <td><code>commit</code></td>
      <td>no</td>

      <td>
        <p><strong>boolean.</strong> Controls the final button text in the PayPal flow:</p>

        <ul>
          <li><code>true</code> — Shows "Pay Now" (payment happens immediately)</li>
          <li><code>false</code> — Shows "Continue" (additional confirmation step)</li>
        </ul>

        <p>Default: <code>true</code></p>
      </td>
    </tr>

    <tr>
      <td><code>savePayment</code></td>
      <td>no</td>

      <td>
        <p><strong>boolean.</strong> Saves the customer's payment method during purchase. Set to <code>true</code> if your [Orders API request saves the payment method](https://developer.paypal.com/docs/checkout/save-payment-methods/during-purchase/orders-api/cards/).</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a `PaymentSession` object with methods to control the payment flow.

```javascript lines theme={null}
interface PaymentSession {
  start(options?: StartOptions, orderPromise: Promise): Promise<void>;
  hasReturned(): boolean;
  resume(): Promise<void>;
}
```

#### Example

```javascript lines expandable theme={null}
const paypalSession = sdkInstance.createPayPalOneTimePaymentSession({
  onApprove: async (data) => {
    // Capture the payment on your server
    const response = await fetch(`/api/orders/${data.orderId}/capture`, {
      method: "POST",
    });

    if (response.ok) {
      // Payment successful
      window.location.href = "/order/complete";
    } else {
      throw new Error("Capture failed");
    }
  },

  onShippingAddressChange: async (data) => {
    // Calculate new shipping cost based on address
    const shippingCost = await calculateShipping(data.shippingAddress);

    // Update the order with new shipping
    return fetch(`/api/orders/${data.orderId}/update-shipping`, {
      method: "PATCH",
      body: JSON.stringify({ shippingCost }),
    });
  },

  onCancel: (data) => {
    console.log("Payment cancelled", data);
    // Re-enable checkout button
    document.getElementById("checkout-btn").disabled = false;
  },

  onError: (error) => {
    console.error("Payment error:", error);
    // Show error message to buyer
    showErrorMessage("Payment failed. Please try again.");
  },
});
```

### `sdkInstance.createPayPalSavePaymentSession(options)`

Create a session for saving PayPal as a payment method for future use (vaulting). This allows buyers to save their PayPal account for faster checkout in future purchases.

The parameters and usage are identical to `createPayPalOneTimePaymentSession`, except the `onApprove` callback receives a `billingToken` instead of requiring immediate payment capture.

#### Example

```javascript lines expandable theme={null}
const saveSession = sdkInstance.createPayPalSavePaymentSession({
  onApprove: async (data) => {
    // Save the billing token to your customer's profile
    await savePaymentMethod({
      customerId: currentUser.id,
      billingToken: data.billingToken,
      type: "paypal",
    });

    showSuccess("PayPal saved for future purchases");
  },
});
```

### `sdkInstance.createVenmoOneTimePaymentSession(options)`

Create a payment session for Venmo payments (US only). Venmo provides a mobile-optimized payment experience for US buyers using their Venmo balance or linked payment methods.

The parameters are identical to `createPayPalOneTimePaymentSession`. Venmo sessions support the same callbacks and flow options.

#### Example

```javascript lines theme={null}
const venmoSession = sdkInstance.createVenmoOneTimePaymentSession({
  onApprove: async (data) => {
    // Capture the Venmo payment
    await captureOrder(data.orderId);
  },
});
```

### `sdkInstance.createPayLaterOneTimePaymentSession(options)`

Create a session for Pay Later financing options. Pay Later allows buyers to pay in installments (like Pay in 4) or over time with longer-term financing.

The parameters are identical to `createPayPalOneTimePaymentSession`. Pay Later availability depends on transaction amount and buyer eligibility.

#### Example

```javascript lines expandable theme={null}
const payLaterSession = sdkInstance.createPayLaterOneTimePaymentSession({
  onApprove: async (data) => {
    await captureOrder(data.orderId);
    // Buyer has been approved for Pay Later financing
  },
});

// Configure the Pay Later button with product details
const details = paymentMethods.getDetails("paylater");
const button = document.querySelector("paylater-button");
button.productCode = details.productCode;
button.countryCode = details.countryCode;
```

### `sdkInstance.createPayPalCreditOneTimePaymentSession(options)`

Create a session for PayPal Credit payments (US only). PayPal Credit offers buyers a reusable line of credit for purchases.

### `sdkInstance.createPayPalSubscriptionSession(options)`

Create a payment session for PayPal subscription payments. Use subscriptions when buyers need recurring billing — for example, membership fees, software licenses, or regular service plans.

<Note>
  Before creating a subscription session, create a subscription plan using the [PayPal Subscriptions API](https://developer.paypal.com/docs/subscriptions/). You'll create a subscription ID for the buyer using this Plan ID when the buyer initiates checkout.
</Note>

#### Parameters

<table>
  <thead>
    <tr>
      <th align="left">Parameter</th>
      <th align="left">Required</th>
      <th align="left">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>onApprove</code></td>
      <td>yes</td>

      <td>
        <p><strong>function(data)</strong> — Called when the buyer approves the subscription. The data object includes:</p>

        <ul>
          <li><code>subscriptionId</code> — The approved PayPal subscription ID. Use this to activate or retrieve subscription details on your server.</li>
          <li><code>payerId</code> — The buyer's PayPal payer ID.</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data)</strong> — Called when the buyer cancels the subscription flow. The data object contains <code>subscriptionId</code> if a subscription was created.</p>
      </td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td>no</td>

      <td>
        <p><strong>function(error)</strong> — Called when an error occurs during the subscription flow. The error object contains <code>code</code> and <code>message</code>.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a subscription session object with a `start(options?, subscriptionPromise)` method. `subscriptionPromise` must resolve to `{ subscriptionId: string }` containing your PayPal subscription ID.

#### Example

```javascript lines expandable theme={null}
const subscriptionSession = sdkInstance.createPayPalSubscriptionSession({
  onApprove: async (data) => {
    console.log("Subscription approved:", data.subscriptionId);

    // Record the subscription on your server
    await fetch("/api/subscriptions/activate", {
      method: "POST",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ subscriptionId: data.subscriptionId }),
    });

    window.location.href = "/subscription/success";
  },

  onCancel: (data) => {
    console.log("Subscription cancelled");
    document.getElementById("subscribe-button").disabled = false;
  },

  onError: (error) => {
    console.error("Subscription error:", error.code, error.message);
  },
});

document.getElementById("subscribe-button").addEventListener("click", () => {
  subscriptionSession.start(
    { presentationMode: "auto" },
    Promise.resolve({ subscriptionId: "YOUR_SUBSCRIPTION_ID" })
  );
});
```

### `sdkInstance.createGooglePayOneTimePaymentSession()`

Create a session for Google Pay payments. The Google Pay session integrates with the [Google Pay API](https://developers.google.com/pay/api/web/guides/tutorial) and handles PayPal order confirmation.

<Note>
  Google Pay requires the `googlepay-payments` component and the [Google Pay JavaScript SDK](https://pay.google.com/gp/p/js/pay.js). Load both before calling this method. Enable Google Pay in your PayPal sandbox and production account settings before going live.
</Note>

#### Returns

Returns a `GooglePaySession` object (synchronously) with these methods:

#### `googlePaySession.formatConfigForPaymentRequest(config)`

Format the Google Pay configuration for the Google Pay API. Before calling this method, use `sdkInstance.findEligibleMethods()` to check eligibility and retrieve the raw configuration, then pass the `.config` property from `paymentMethods.getDetails("googlepay")`:

```javascript theme={null}
const paymentMethods = await sdkInstance.findEligibleMethods({ currencyCode: "USD" });
const googlePayPaymentMethodDetails = paymentMethods.getDetails("googlepay");
const googlePayConfig = googlePaySession.formatConfigForPaymentRequest(
  googlePayPaymentMethodDetails.config,
);
```

##### Parameters

| Parameter | Required | Description                                                                      |
| :-------- | :------- | :------------------------------------------------------------------------------- |
| `config`  | yes      | **object.** The `config` property from `paymentMethods.getDetails("googlepay")`. |

##### Returns

Returns a formatted configuration object:

| Property                | Type   | Description                                         |
| :---------------------- | :----- | :-------------------------------------------------- |
| `allowedPaymentMethods` | array  | Payment method configuration for the Google Pay API |
| `merchantInfo`          | object | PayPal merchant information for Google Pay          |
| `apiVersion`            | number | Google Pay API version                              |
| `apiVersionMinor`       | number | Google Pay API minor version                        |
| `countryCode`           | string | Two-letter ISO 3166-1 country code                  |

#### `googlePaySession.confirmOrder(options)`

Use the payment data from Google Pay to confirm the PayPal order. Call this inside the `onPaymentAuthorized` callback.

##### Parameters

| Parameter           | Required | Description                                                                                                       |
| :------------------ | :------- | :---------------------------------------------------------------------------------------------------------------- |
| `orderId`           | yes      | **string.** The PayPal order ID created on your server.                                                           |
| `paymentMethodData` | yes      | **object.** The payment method data from the Google Pay authorization response (`paymentData.paymentMethodData`). |

##### Returns

Returns a promise that resolves to `{ status }`:

| Status                  | Description                                       |
| :---------------------- | :------------------------------------------------ |
| `APPROVED`              | Order confirmed and ready to capture.             |
| `PAYER_ACTION_REQUIRED` | 3D Secure authentication required before capture. |

#### Example

```javascript lines expandable theme={null}
const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
  components: ["googlepay-payments"],
  pageType: "checkout",
});

// Check eligibility before setting up Google Pay
const paymentMethods = await sdkInstance.findEligibleMethods({
  currencyCode: "USD",
});

if (paymentMethods.isEligible("googlepay")) {
  const googlePayPaymentMethodDetails = paymentMethods.getDetails("googlepay");

  // Create Google Pay session and format config
  const googlePaySession = sdkInstance.createGooglePayOneTimePaymentSession();
  const googlePayConfig = googlePaySession.formatConfigForPaymentRequest(
    googlePayPaymentMethodDetails.config,
  );

  // Initialize Google Pay client
  const paymentsClient = new google.payments.api.PaymentsClient({
    environment: "TEST", // Use "PRODUCTION" for live transactions
    paymentDataCallbacks: {
      onPaymentAuthorized: async (paymentData) => {
        try {
          const orderId = await createOrder();

          const { status } = await googlePaySession.confirmOrder({
            orderId,
            paymentMethodData: paymentData.paymentMethodData,
          });

          if (status !== "PAYER_ACTION_REQUIRED") {
            await captureOrder(orderId);
          }

          return { transactionState: "SUCCESS" };
        } catch (err) {
          return {
            transactionState: "ERROR",
            error: { message: err.message },
          };
        }
      },
    },
  });

  // Check readiness and render button
  const { result } = await paymentsClient.isReadyToPay({
    allowedPaymentMethods: googlePayConfig.allowedPaymentMethods,
    apiVersion: googlePayConfig.apiVersion,
    apiVersionMinor: googlePayConfig.apiVersionMinor,
  });

  if (result) {
    const button = paymentsClient.createButton({
      onClick: () => {
        paymentsClient.loadPaymentData({
          ...googlePayConfig,
          transactionInfo: {
            countryCode: googlePayConfig.countryCode,
            currencyCode: "USD",
            totalPriceStatus: "FINAL",
            totalPrice: "10.00",
          },
          callbackIntents: ["PAYMENT_AUTHORIZATION"],
        });
      },
    });
    document.getElementById("google-pay-container").appendChild(button);
  }
}
```

### `sdkInstance.createApplePayOneTimePaymentSession()`

Create a session for Apple Pay payments. The Apple Pay session integrates with the browser's native `ApplePaySession` API and handles merchant validation and order confirmation.

<Note>
  Apple Pay requires:

  * The `applepay-payments` component
  * The [Apple Pay JavaScript SDK](https://applepay.cdn-apple.com/jsapi/v1/apple-pay-sdk.js)
  * An HTTPS connection
  * A merchant domain registration with PayPal
    Apple Pay is available in Safari on Apple devices only.
</Note>

#### Returns

Returns a promise that resolves to an Apple Pay session object with these methods:

#### `applePaySession.config()`

Fetch the Apple Pay merchant configuration from PayPal.

##### Returns

Returns a promise that resolves to:

| Property               | Type      | Description                                                                             |
| :--------------------- | :-------- | :-------------------------------------------------------------------------------------- |
| `merchantCapabilities` | string\[] | Merchant capabilities for the Apple Pay payment request, for example, `["supports3DS"]` |
| `supportedNetworks`    | string\[] | Card networks the merchant accepts, for example, `["visa", "masterCard", "amex"]`       |

#### `applePaySession.validateMerchant(options)`

Complete Apple Pay merchant validation. Call this inside the `onvalidatemerchant` event handler of the browser's `ApplePaySession`.

##### Parameters

| Parameter       | Required | Description                                                                                 |
| :-------------- | :------- | :------------------------------------------------------------------------------------------ |
| `validationUrl` | yes      | **string.** The validation URL from the `onvalidatemerchant` event (`event.validationURL`). |

##### Returns

Returns a promise that resolves to `{ merchantSession }`. Pass `merchantSession` to `applePaySession.completeMerchantValidation()`.

#### `applePaySession.confirmOrder(options)`

Confirm the PayPal order using the payment token from Apple Pay. Call this inside the `onpaymentauthorized` event handler.

##### Parameters

| Parameter         | Required | Description                                                                    |
| :---------------- | :------- | :----------------------------------------------------------------------------- |
| `orderId`         | yes      | **string.** The PayPal order ID created on your server.                        |
| `token`           | yes      | **object.** The Apple Pay payment token from `event.payment.token`.            |
| `billingContact`  | no       | **object.** The buyer's billing contact from `event.payment.billingContact`.   |
| `shippingContact` | no       | **object.** The buyer's shipping contact from `event.payment.shippingContact`. |

#### Payment request structure

Build an `ApplePayPaymentRequest` to pass to the browser's `new ApplePaySession()`:

| Property                        | Description                                                                            |
| :------------------------------ | :------------------------------------------------------------------------------------- |
| `countryCode`                   | Merchant country code, for example, `"US"`                                             |
| `currencyCode`                  | Transaction currency code, for example, `"USD"`                                        |
| `merchantCapabilities`          | From `applePaySession.config()`                                                        |
| `supportedNetworks`             | From `applePaySession.config()`                                                        |
| `requiredBillingContactFields`  | Array of required billing fields: `"name"`, `"phone"`, `"email"`, `"postalAddress"`    |
| `requiredShippingContactFields` | Array of required shipping fields, or empty array if no shipping needed                |
| `total`                         | Object with `label` (string), `amount` (string), and `type` (`"final"` or `"pending"`) |

#### Example

```javascript lines expandable theme={null}
const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
  components: ["applepay-payments"],
  pageType: "checkout",
});

// Create Apple Pay session
const paypalApplePaySession = sdkInstance.createApplePayOneTimePaymentSession();

// Get merchant configuration
    const paymentMethods = await sdkInstance.findEligibleMethods({
      currencyCode: "USD",
    });

    if (paymentMethods.isEligible("applepay")) {
      const applePayPaymentMethodDetails =
        paymentMethods.getDetails("applepay");
      setupApplePayButton(sdkInstance, applePayPaymentMethodDetails);

// Display Apple Pay button
document.getElementById("apple-pay-container").innerHTML =
  '<apple-pay-button buttonstyle="black" type="buy" locale="en"></apple-pay-button>';

document.querySelector("apple-pay-button").addEventListener("click", async () => {
  const paymentRequest = {
    countryCode: "US",
    currencyCode: "USD",
    merchantCapabilities,
    supportedNetworks,
    requiredBillingContactFields: ["name", "postalAddress"],
    requiredShippingContactFields: [],
    total: {
      label: "Your Store",
      amount: "25.00",
      type: "final",
    },
  };

  const applePaySession = new ApplePaySession(4, paymentRequest);

  applePaySession.onvalidatemerchant = async (event) => {
    try {
      const { merchantSession } = await paypalApplePaySession.validateMerchant({
        validationUrl: event.validationURL,
      });
      applePaySession.completeMerchantValidation(merchantSession);
    } catch (err) {
      console.error("Merchant validation failed:", err);
      applePaySession.abort();
    }
  };

  applePaySession.onpaymentauthorized = async (event) => {
    try {
      const orderId = await createOrder();

      await paypalApplePaySession.confirmOrder({
        orderId,
        token: event.payment.token,
        billingContact: event.payment.billingContact,
        shippingContact: event.payment.shippingContact,
      });

      await captureOrder(orderId);

      applePaySession.completePayment({
        status: ApplePaySession.STATUS_SUCCESS,
      });
    } catch (err) {
      console.error("Payment failed:", err);
      applePaySession.completePayment({
        status: ApplePaySession.STATUS_FAILURE,
      });
    }
  };

  applePaySession.oncancel = () => {
    console.log("Apple Pay cancelled");
  };

  applePaySession.begin();
});
```

### `sdkInstance.createFastlane()`

Create a Fastlane instance for accelerated guest checkout. Fastlane enables one-click checkout for recognized guests.

#### Returns

Returns a promise that resolves to a Fastlane instance.

#### Example

```javascript theme={null}
const fastlane = await sdkInstance.createFastlane();
// Use fastlane instance for guest checkout acceleration
```

### `sdkInstance.createPayPalMessages(options?)`

Display PayPal Messages to show financing options and promotional messaging to buyers. These messages dynamically update based on the transaction amount and buyer eligibility.

#### Parameters

<table>
  <thead>
    <tr>
      <th align="left">Parameter</th>
      <th align="left">Required</th>
      <th align="left">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>amount</code></td>
      <td>no</td>

      <td>
        <p><strong>number.</strong> The product or cart amount to display messaging for. Messages update dynamically based on this amount.</p>
      </td>
    </tr>

    <tr>
      <td><code>placement</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> The page placement context for the messages. This affects message format and content.</p>
        <p>Values: <code>product</code>, <code>cart</code>, <code>checkout</code></p>
      </td>
    </tr>

    <tr>
      <td><code>style</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> Visual styling options for the messages, including layout and logo configuration.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a `PayPalMessagesInstance` object with `fetchContent(options?)` and `createLearnMore(options?)` methods.

#### `messagesInstance.fetchContent(options?)`

Fetch message content from PayPal and render it in all `<paypal-messages>` components on the page.

| Option            | Required | Description                                                                                                                                                                     |
| :---------------- | :------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `amount`          | no       | **string.** Transaction amount with up to 2 decimal places, for example, `"125.00"`. Affects which financing offers are displayed.                                              |
| `currencyCode`    | no       | **string.** Three-letter ISO 4217 currency code, for example, `"USD"`.                                                                                                          |
| `logoPosition`    | no       | **string.** Where to place the PayPal logo. Values: `LEFT` (default), `RIGHT`, `TOP`, `INLINE`. Note: `MONOGRAM` logo type requires `LEFT`; `TEXT` logo type requires `INLINE`. |
| `logoType`        | no       | **string.** PayPal branding style. Values: `WORDMARK` (default), `MONOGRAM`, `TEXT`.                                                                                            |
| `textColor`       | no       | **string.** Message text color. Values: `BLACK` (default), `WHITE`, `MONOCHROME`.                                                                                               |
| `onContentReady`  | no       | **function.** Called when content arrives from the server. Takes precedence over `onReady`.                                                                                     |
| `onTemplateReady` | no       | **function.** Called when content is served from local cache. Takes precedence over `onReady`.                                                                                  |
| `onReady`         | no       | **function.** Called when content is ready from either cache or server. Used when neither `onContentReady` nor `onTemplateReady` is specified.                                  |

#### `messagesInstance.createLearnMore(options?)`

Initialize a Learn more presentation that provides additional financing details when buyers select the Learn more link in a message.

| Option             | Required | Description                                                                                              |
| :----------------- | :------- | :------------------------------------------------------------------------------------------------------- |
| `amount`           | no       | **string.** The transaction amount to display in the Learn more presentation.                            |
| `presentationMode` | no       | **string.** How the Learn more content is shown. Values: `AUTO` (default), `MODAL`, `POPUP`, `REDIRECT`. |
| `onApply`          | no       | **function.** Called when the buyer selects Apply in the Learn more presentation.                        |
| `onCalculate`      | no       | **function.** Called when the buyer enters a value in the amount input field.                            |
| `onShow`           | no       | **function.** Called when the Learn more presentation opens.                                             |
| `onClose`          | no       | **function.** Called when the Learn more presentation closes.                                            |

#### CSS custom properties

Customize message appearance using these CSS properties on the `<paypal-messages>` element:

| Property                      | Description                                        | Default |
| :---------------------------- | :------------------------------------------------- | :------ |
| `--paypal-message-font-size`  | Font size in `px`, clamped to `10px`–`16px`.       | `14px`  |
| `--paypal-message-text-align` | Text alignment. Values: `left`, `right`, `center`. | `left`  |

#### Example

```javascript lines expandable theme={null}
const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
  components: ["paypal-messages"],
});

const messagesInstance = sdkInstance.createPayPalMessages();

// Render message with style options
messagesInstance.fetchContent({
  amount: "199.99",
  currencyCode: "USD",
  logoPosition: "LEFT",
  logoType: "WORDMARK",
  textColor: "BLACK",
  onContentReady: () => {
    document.getElementById("paypal-message-container").style.display = "block";
  },
});

// Optional: create a Learn More presentation
const learnMore = messagesInstance.createLearnMore({
  amount: "199.99",
  presentationMode: "MODAL",
  onShow: () => console.log("Learn more opened"),
  onClose: () => console.log("Learn more closed"),
});
```

```html lines theme={null}
<!-- PayPal Messages web component with CSS custom properties -->
<paypal-messages
  style="--paypal-message-font-size: 14px; --paypal-message-text-align: left;"
></paypal-messages>
```

### `paymentSession.start(options?, orderPromise)`

Start the payment user experience. This method opens the payment interface using the specified presentation mode and begins the checkout flow.

#### Parameters

<table>
  <thead>
    <tr>
      <th align="left">Parameter</th>
      <th align="left">Required</th>
      <th align="left">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>options</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> Configuration for how the payment UI is presented.</p>
      </td>
    </tr>

    <tr>
      <td><code>options.presentationMode</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> Controls how the payment interface is displayed to the buyer.</p>
        <p>Available modes:</p>

        <ul>
          <li><code>auto</code> — Recommended. SDK automatically selects the best experience. Tries popup first and falls back to modal if popups are blocked.</li>
          <li><code>popup</code> — Opens PayPal in a popup window. May be blocked by popup blockers.</li>
          <li><code>modal</code> — Creates an iframe overlay on the current page. Recommended only for WebView scenarios. Do not use in desktop web scenarios as this integration has limitations on cookies, which can affect user authentication.</li>
          <li><code>redirect</code> — Full page redirect to PayPal. Recommended for mobile devices. Requires a return/cancel URL.</li>
          <li><code>payment-handler</code> — Experimental. Uses the browser's Payment Handler API. Provides a native payment experience. Modern browsers only. </li>
        </ul>

        <p>Default: <code>auto</code></p>
        <p>The SDK will automatically fall back to alternative modes if the requested mode is unavailable.</p>
      </td>
    </tr>

    <tr>
      <td><code>options.autoRedirect</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> Configuration for redirect mode behavior.</p>

        <ul>
          <li><code>enabled</code> (boolean) — Whether to automatically redirect or return the URL</li>
        </ul>

        <p>Only applies when using <code>presentationMode: "redirect"</code>.</p>
      </td>
    </tr>

    <tr>
      <td><code>options.fullPageOverlay</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> Controls the background overlay when using popup mode.</p>

        <ul>
          <li><code>enabled</code> (boolean) — Show/hide the page overlay</li>
        </ul>

        <p>Default: <code>enabled: true</code></p>
      </td>
    </tr>

    <tr>
      <td><code>options.loadingScreen</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> Customize the loading screen text.</p>

        <ul>
          <li><code>label</code> (string) — Currently only supports "connecting"</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>orderPromise</code></td>
      <td>yes</td>

      <td>
        <p><strong>promise.</strong> A promise that creates or retrieves the PayPal order. This promise should resolve to an object containing the <code>orderId</code>.</p>
        <p>The order creation can happen asynchronously while the payment UI is loading, improving perceived performance.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

For most presentation modes, returns a promise that resolves when the payment flow completes or is cancelled.

For redirect mode with `autoRedirect.enabled: false`, returns the redirect URL:

```javascript theme={null}
Promise<{ redirectURL: string }>
```

#### Example

```javascript lines expandable theme={null}
// Basic usage with auto mode
await paymentSession.start(
  { presentationMode: "auto" },
  createOrder() // Returns Promise<{orderId: string}>
);

// Redirect mode with manual handling
const { redirectURL } = await paymentSession.start(
  {
    presentationMode: "redirect",
    autoRedirect: { enabled: false },
  },
  createOrder()
);

if (redirectURL) {
  // Manually redirect the buyer to a new tab
  // Only recommended for use cases where the v6 SDK is being wrapped in an iframe
  // Or usage with redirect flow for webview use cases
  window.location.href = redirectURL;
}

// Fallback pattern for incompatible browsers
const modes = [
  { mode: "popup", errorCode: "ERR_DEV_UNABLE_TO_OPEN_POPUP" },
  { mode: "modal", errorCode: null },
];

for (const { mode, errorCode } of modes) {
  try {
    await paymentSession.start({ presentationMode: mode }, createOrder());
    break; // Success
  } catch (error) {
    if (errorCode && error.code === errorCode) {
      continue; // Try next mode
    }
    throw error; // Unexpected error
  }
}
```

### `paymentSession.hasReturned()`

Check if the current page load is a return from a redirect payment flow. Use this method on page load to detect and resume interrupted payment sessions.

#### Returns

Returns `true` if the buyer is returning from a PayPal redirect, `false` otherwise.

#### Example

```javascript lines expandable theme={null}
// Runs on page load when SDK has finished downloading
async function onPayPalWebSdkLoaded() {
  try {
    const sdkInstance = await window.paypal.createInstance({
      clientId: "YOUR_CLIENT_ID",
      components: ["paypal-payments"],
      pageType: "checkout",
    });
    const paypalPaymentSession = sdkInstance.createPayPalOneTimePaymentSession(
      paymentSessionOptions
    );
    // Check to see if Buyer is returning from PayPal
    if (paypalPaymentSession.hasReturned()) {
      // Original callbacks will be triggered
      await paypalPaymentSession.resume();
    } else {
      configurePayPalButton(paypalPaymentSession);
    }
  } catch (error) {
    console.error(error);
  }
}
```

### `paymentSession.resume()`

Resume a payment session after returning from a redirect flow. This method continues the payment process and triggers the appropriate callbacks based on the payment outcome.

#### Returns

Returns a promise that resolves when the session is successfully resumed.

## Handling callbacks

Callbacks allow you to respond to events during the payment flow. Each callback receives specific data about the event and can optionally return a promise to perform asynchronous operations.

### `onApprove(data)`

Called when the buyer successfully approves the payment. This is where you should capture or authorize the payment on your server.

#### Parameters

The callback receives a data object with the following properties:

| Property       | Type                | Description                                                                            |
| :------------- | :------------------ | :------------------------------------------------------------------------------------- |
| `orderId`      | string              | The PayPal order ID that was approved. Use this to capture the payment on your server. |
| `payerId`      | string              | The buyer's PayPal payer ID. This identifies the PayPal account used for payment.      |
| `paymentId`    | string \| undefined | Legacy payment ID for backwards compatibility. Only present in certain flows.          |
| `billingToken` | string \| undefined | Token for saving payment method. Only present when using save payment sessions.        |

#### Return value

The callback can optionally return a promise. If a promise is returned, the SDK waits for it to resolve before completing the flow.

#### Example

```javascript lines expandable theme={null}
onApprove: async (data) => {
  console.log("Payment approved for order:", data.orderId);

  // Capture the payment on your server
  const response = await fetch(`/api/orders/${data.orderId}/capture`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
  });

  const captureData = await response.json();

  if (captureData.status === "COMPLETED") {
    // Redirect to success page
    window.location.href = `/order/success?id=${data.orderId}`;
  } else {
    throw new Error("Payment capture failed");
  }
};
```

### `onCancel(data)`

Called when the buyer cancels the payment without completing it. This typically happens when they close the PayPal window or select a cancel button.

#### Parameters

| Property  | Type                | Description                                                                                               |
| :-------- | :------------------ | :-------------------------------------------------------------------------------------------------------- |
| `orderId` | string \| undefined | The order ID if one was created before cancellation. May be undefined if cancelled before order creation. |

#### Example

```javascript lines expandable theme={null}
onCancel: (data) => {
  console.log("Payment cancelled", data);

  // Use your own analytics to track cancellation
  // Always ensure this is a non-blocking call
  analytics.track("checkout_abandoned", {
    orderId: data.orderId,
    timestamp: Date.now(),
  });

  // Show a message to the buyer
  showMessage("Your payment was cancelled. Your cart items are still saved.");

  // Re-enable the checkout button
  document.getElementById("checkout-button").disabled = false;
};
```

### `onError(error)`

Called when an error occurs during the payment flow. This includes network errors, validation failures, and payment processing errors.

#### Parameters

The callback receives an error object with these properties:

| Property  | Type   | Description                                                                                     |
| --------- | ------ | ----------------------------------------------------------------------------------------------- |
| `code`    | string | A specific error code identifying the type of error. Use this for programmatic error handling.  |
| `message` | string | A human-readable error description. This may contain technical details not suitable for buyers. |

#### Common error codes

| Code                                            | Description                        | Recommended action                    |
| :---------------------------------------------- | :--------------------------------- | :------------------------------------ |
| `ERR_INVALID_CLIENT_TOKEN`                      | Client token is invalid or expired | Generate a new token and reinitialize |
| `ERR_DOMAIN_MISMATCH`                           | Current domain doesn't match token | Verify domain configuration           |
| `ERR_DEV_UNABLE_TO_OPEN_POPUP`                  | Popup was blocked by browser       | Fall back to modal or redirect mode   |
| `ERR_FLOW_PAYMENT_HANDLER_BROWSER_INCOMPATIBLE` | Payment handler not supported      | Use traditional checkout flow         |
| `INSTRUMENT_DECLINED`                           | Payment method was declined        | Suggest alternative payment method    |
| `NETWORK_ERROR`                                 | Network request failed             | Retry or check connection             |

#### Example

```javascript lines expandable theme={null}
onError: (error) => {
  console.error("Payment error:", error);

  // Log to error tracking service
  errorReporter.log(error);

  // Show user-friendly message based on error code
  let message;
  switch (error.code) {
    case "ERR_INVALID_CLIENT_TOKEN":
      message = "Your session has expired. Please refresh and try again.";
      setTimeout(() => location.reload(), 3000);
      break;
    case "INSTRUMENT_DECLINED":
      message =
        "Your payment was declined. Please try a different payment method.";
      break;
    case "NETWORK_ERROR":
      message = "Connection lost. Please check your internet and try again.";
      break;
    default:
      message = "Something went wrong. Please try again.";
  }

  showErrorMessage(message);
};
```

### `onShippingAddressChange(data)`

Called when the buyer selects or changes their shipping address within the PayPal flow. Use this callback to update shipping costs, validate addresses, or apply location-based restrictions.

#### Data properties

| Property                      | Type   | Description                                                   |
| :---------------------------- | :----- | :------------------------------------------------------------ |
| `errors`                      | object | Error messages you can display to the user in the Checkout UI |
| `errors.ADDRESS_ERROR`        | string | "Your order can't be shipped to this address."                |
| `errors.COUNTRY_ERROR`        | string | "Your order can't be shipped to this country."                |
| `errors.STATE_ERROR`          | string | "Your order can't be shipped to this state."                  |
| `errors.ZIP_ERROR`            | string | "Your order can't be shipped to this zip."                    |
| `orderId`                     | string | The current order ID                                          |
| `shippingAddress`             | object | The newly selected shipping address                           |
| `shippingAddress.city`        | string | City name                                                     |
| `shippingAddress.state`       | string | State or province code                                        |
| `shippingAddress.countryCode` | string | ISO 3166-1 alpha-2 country code                               |
| `shippingAddress.postalCode`  | string | Postal or ZIP code                                            |

#### Return value

Return a promise to update the order asynchronously. If the promise rejects, the address change will be rejected and the buyer must select a different address.

#### Example

```javascript lines expandable theme={null}
onShippingAddressChange: async (data) => {
  const { errors, shippingAddress } = data;

  // Check if we ship to this address
  if (!isShippableLocation(shippingAddress)) {
    // Reject the address change
    throw new Error(errors.ADDRESS_ERROR);
  }

  // Calculate new shipping cost
  const shippingCost = calculateShipping({
    address: shippingAddress,
    items: cartItems,
  });

  // Update the order with new shipping
  const response = await fetch(`/api/orders/${data.orderId}/shipping`, {
    method: "PATCH",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      shippingAddress,
      shippingCost,
    }),
  });

  if (!response.ok) {
    throw new Error("Failed to update shipping");
  }
};
```

### `onShippingOptionsChange(data)`

Called when the buyer selects a different shipping option, for example, standard or express delivery. Use this to update the order total with the selected shipping cost.

#### Data properties

| Property                    | Type   | Description                                                                                        |
| :-------------------------- | :----- | :------------------------------------------------------------------------------------------------- |
| `errors`                    | object | Error messages you can display to the user in the Checkout UI                                      |
| `errors.METHOD_UNAVAILABLE` | string | "The shipping method you chose is unavailable. To continue, choose another way to get your order." |
| `errors.STORE_UNAVAILABLE`  | string | "Part of your order isn't available at this store."                                                |
| `orderId`                   | string | The current order ID                                                                               |
| `selectedShippingOption`    | object | Details of the selected shipping option                                                            |

#### Example

```javascript lines expandable theme={null}
onShippingOptionsChange: async (data) => {
  const { errors, selectedShippingOption } = data;

  // disable store pickup
  if (selectedShippingOption.type === 'PICKUP') {
    throw new Error(errors.STORE_UNAVAILABLE);
  }

  // Update order with new shipping option
  await updateOrderShipping({
    orderId: data.orderId,
    shippingId: selectedShippingOption.id,
    shippingCost: selectedShippingOption.amount.value,
  });
};
```

## Web components

PayPal.js provides native web components for rendering payment buttons. These components automatically handle styling and accessibility while allowing customization through CSS variables.

### `paypal-button`

The PayPal button web component renders a PayPal-branded button that buyers select to start the payment flow.

#### Attributes

<table>
  <thead>
    <tr>
      <th align="left">Attribute</th>
      <th align="left">Type</th>
      <th align="left">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>type</code></td>
      <td>string</td>

      <td>
        <p>Controls the button label text. Different types are optimized for different contexts in your checkout flow.</p>
        <p>Values:</p>

        <ul>
          <li><code>pay</code> — "Pay with PayPal"</li>
          <li><code>checkout</code> — "PayPal Checkout"</li>
          <li><code>buynow</code> — "PayPal Buy Now"</li>
          <li><code>subscribe</code> — "PayPal Subscribe"</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>class</code></td>
      <td>string</td>

      <td>
        <p>Applies a predefined color scheme to the button.</p>
        <p>Values:</p>

        <ul>
          <li><code>paypal-gold</code> — Gold background (recommended)</li>
          <li><code>paypal-blue</code> — Blue background</li>
          <li><code>paypal-white</code> — White with border</li>
        </ul>
      </td>
    </tr>
  </tbody>
</table>

#### CSS variables

Customize the button appearance using CSS custom properties:

| Variable                        | Description                            | Example values  |
| :------------------------------ | :------------------------------------- | :-------------- |
| `--paypal-button-border-radius` | Border radius for the button           | 4px, 20px, 50px |
| `--paypal-mark-border-radius`   | Border radius for the PayPal mark/logo | 4px, 8px        |

#### Example

```html lines expandable theme={null}
<!-- Basic button -->
<paypal-button type="pay" class="paypal-gold"></paypal-button>

<!-- Initially hidden button -->
<paypal-button type="checkout" class="paypal-blue" hidden> </paypal-button>

<!-- Custom styled button -->
<style>
  paypal-button {
    --paypal-button-border-radius: 10px;
    width: 100%;
    max-width: 350px;
  }

  paypal-button.custom-style {
    --paypal-button-border-radius: 25px;
  }
</style>

<paypal-button type="pay" class="paypal-gold custom-style"></paypal-button>

<script>
  // Attach click handler
  const onClick = async () => {
    try {
      await paypalSession.start({ presentationMode: "auto" }, createOrder());
    } catch (error) {
      console.log(error);
    }
  };

  document.querySelector("paypal-button").addEventListener("click", onClick);
</script>
```

### `venmo-button`

The Venmo button web component renders a Venmo-branded button for US buyers. The attributes and styling options are identical to `<paypal-button>`.

### Example

```html theme={null}
<venmo-button type="pay" class="venmo-blue"></venmo-button>
```

### `paylater-button`

The Pay Later button component displays financing options to buyers. This button requires additional configuration based on the available Pay Later products.

#### Attributes

| Attribute     | Type   | Description                                                                                                                  |
| :------------ | :----- | :--------------------------------------------------------------------------------------------------------------------------- |
| `productCode` | string | The specific Pay Later product to display, for example, `"PAY_IN_4"`. Get this from `paymentMethods.getDetails('paylater')`. |
| `countryCode` | string | The country code for the Pay Later offer. Required for proper messaging display.                                             |

#### Example

```javascript lines theme={null}
// Configure Pay Later button
const payLaterDetails = paymentMethods.getDetails("paylater");

const button = document.querySelector("paylater-button");
button.productCode = payLaterDetails.productCode;
button.countryCode = payLaterDetails.countryCode;
button.removeAttribute("hidden");
```

### `paypal-credit-button`

The PayPal Credit button component displays PayPal's credit offering for eligible buyers (US only).

#### Attributes

| Attribute     | Type   | Description                                                                   |
| :------------ | :----- | :---------------------------------------------------------------------------- |
| `countryCode` | string | The country code for PayPal Credit availability. Required for proper display. |

#### Example

```javascript lines theme={null}
const creditDetails = paymentMethods.getDetails("credit");

const button = document.querySelector("paypal-credit-button");
button.countryCode = creditDetails.countryCode;
```

### Browser compatibility

The JavaScript SDK v6 supports modern browsers. Check browser compatibility before initializing the SDK to ensure optimal user experience.

#### Minimum supported versions

| Browser (web/mobile web) | Minimum Supported Version |
| :----------------------- | :------------------------ |
| Chrome                   | 69                        |
| Safari                   | 12                        |
| Firefox                  | 63                        |
| Samsung Internet         | 10                        |
| Edge                     | 79                        |

#### Browser support check

Use the `window.isBrowserSupportedByPayPal()` function to verify browser compatibility before initializing the SDK:

```javascript lines theme={null}
// Check browser compatibility
if (window.isBrowserSupportedByPayPal()) {
  // Initialize PayPal SDK
  const sdkInstance = await window.paypal.createInstance({
    clientId: "YOUR_CLIENT_ID",
  });
} else {
  // Show fallback payment options or browser upgrade message
  showBrowserNotSupportedMessage();
}
```

## Card fields

Card fields let you embed inline card input components on your page for credit and debit card payments. Card fields keep buyers on your page for the entire payment experience. Card data flows through PayPal-hosted iframes, so your site never handles raw card numbers.

<Note>
  Card fields require the `card-fields` component. Check eligibility using `paymentMethods.isEligible("advanced_cards")` before rendering the fields. For PCI compliance requirements, see [PCI DSS SAQ A-EP](https://www.pcisecuritystandards.org/).
</Note>

### `sdkInstance.createCardFieldsOneTimePaymentSession()`

Create a card fields session for a one-time payment. The session provides methods to create individual card input components and submit the payment.

#### Returns

Returns a `CardFieldsOneTimePaymentSession` object with `createCardFieldsComponent(options)` and `submit(orderId, options?)` methods.

### `sdkInstance.createCardFieldsSavePaymentSession()`

Create a card fields session for saving a card payment method (vaulting) for future use. The session behaves the same as the one-time session.

### `cardSession.createCardFieldsComponent(options)`

Create an individual card field input component. The method returns an `HTMLElement` that you append directly to a DOM container.

#### Parameters

<table>
  <thead>
    <tr>
      <th align="left">Parameter</th>
      <th align="left">Required</th>
      <th align="left">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>type</code></td>
      <td>yes</td>

      <td>
        <p><strong>string.</strong> The card field to render.</p>
        <p>Values:</p>

        <ul>
          <li><code>number</code> — Card number field</li>
          <li><code>expiry</code> — Expiration date field</li>
          <li><code>cvv</code> — Security code field</li>
          <li><code>name</code> — Cardholder name field</li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>placeholder</code></td>
      <td>no</td>

      <td>
        <p><strong>string.</strong> Placeholder text shown inside the field when empty, for example, <code>"Card number"</code> or <code>"MM/YY"</code>.</p>
      </td>
    </tr>

    <tr>
      <td><code>style</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> CSS styles applied within the PayPal-hosted iframe. See <a href="#card-field-styling">Card field styling</a>.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns an `HTMLElement`. Mount it to a container using `appendChild()` or equivalent.

```javascript lines theme={null}
const numberField = cardSession.createCardFieldsComponent({
  type: "number",
  placeholder: "Card number",
});

document.getElementById("card-number-container").appendChild(numberField);
```

### `cardSession.submit(orderId, options?)`

Submit the card payment. This validates the card data, runs 3D Secure (3DS) authentication if required, and returns the payment outcome.

#### Parameters

<table>
  <thead>
    <tr>
      <th align="left">Parameter</th>
      <th align="left">Required</th>
      <th align="left">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>orderId</code></td>
      <td>yes</td>

      <td>
        <p><strong>string.</strong> The PayPal order ID created on your server. Pass the string directly — do not pass an object such as <code>{"{ orderId }"}</code>.</p>
      </td>
    </tr>

    <tr>
      <td><code>options.billingAddress</code></td>
      <td>no</td>

      <td>
        <p><strong>object.</strong> Billing address fields to include with the payment for risk and SCA purposes. Include at minimum the fields your risk strategy requires.</p>
        <p>Available fields: <code>postalCode</code>, <code>streetAddress</code>, <code>city</code>, <code>state</code>, <code>countryCode</code>.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a promise that resolves to `{ data, state }`:

| State       | Description                                                                                                |
| :---------- | :--------------------------------------------------------------------------------------------------------- |
| `succeeded` | Payment succeeded. `data.orderId` is the order ID to capture. `data.liabilityShift` indicates 3DS outcome. |
| `canceled`  | Buyer dismissed the 3D Secure modal. Display a non-blocking message and allow the buyer to retry.          |
| `failed`    | Validation or processing failure. `data.message` may contain details. Show an error and allow retry.       |

### Card field styling

Pass a `style` object to `createCardFieldsComponent()` to customize card field appearance. Styles are applied within the PayPal-hosted iframe.

#### Supported CSS selectors

| Selector   | When it applies                               |
| :--------- | :-------------------------------------------- |
| `input`    | The card input element                        |
| `.invalid` | Applied when the field value fails validation |
| `:focus`   | Applied when the field has keyboard focus     |

#### Supported CSS properties

* `appearance`
* `background`
* `border`
* `borderRadius`
* `boxShadow`
* `color`
* `direction`
* `font`
* `fontFamily`
* `fontSize`
* `fontSizeAdjust`
* `fontStretch`
* `fontStyle`
* `fontVariant`
* `fontVariantAlternates`
* `fontVariantCaps`
* `fontVariantEastAsian`
* `fontVariantLigatures`
* `fontVariantNumeric`
* `fontWeight`
* `height`
* `letterSpacing`
* `lineHeight`
* `opacity`
* `outline`
* `padding`
* `paddingBottom`
* `paddingLeft`
* `paddingRight`
* `paddingTop`
* `textShadow`
* `transition`

#### Example

```javascript lines theme={null}
const numberField = cardSession.createCardFieldsComponent({
  type: "number",
  placeholder: "Card number",
  style: {
    input: {
      fontSize: "16px",
      lineHeight: "24px",
      color: "#333333",
    },
    ".invalid": {
      color: "#e53e3e",
    },
  },
});
```

### Full card fields example

```javascript lines expandable theme={null}
async function onPayPalWebSdkLoaded() {
  try {
    const sdk = await window.paypal.createInstance({
      clientId: "YOUR_CLIENT_ID",
      components: ["card-fields"],
      pageType: "checkout",
    });

    // Check eligibility before rendering
    const paymentMethods = await sdk.findEligibleMethods({ currencyCode: "USD" });
    if (!paymentMethods.isEligible("advanced_cards")) {
      return; // Fall back to other payment methods
    }

    // Create card fields session
    const cardSession = sdk.createCardFieldsOneTimePaymentSession();

    // Create and mount field components
    const numberField = cardSession.createCardFieldsComponent({
      type: "number",
      placeholder: "Card number",
      style: { input: { fontSize: "16px" } },
    });
    const expiryField = cardSession.createCardFieldsComponent({
      type: "expiry",
      placeholder: "MM/YY",
    });
    const cvvField = cardSession.createCardFieldsComponent({
      type: "cvv",
      placeholder: "CVV",
    });

    document.getElementById("card-number").appendChild(numberField);
    document.getElementById("card-expiry").appendChild(expiryField);
    document.getElementById("card-cvv").appendChild(cvvField);

    // Handle submission
    document.getElementById("pay-button").addEventListener("click", async () => {
      try {
        const orderId = await createOrder();

        const { data, state } = await cardSession.submit(orderId, {
          billingAddress: { postalCode: "10001" },
        });

        switch (state) {
          case "succeeded":
            // 3DS may or may not have run; check liabilityShift
            await captureOrder(data.orderId);
            window.location.href = "/order/success";
            break;
          case "canceled":
            // Buyer dismissed 3DS — allow retry without a new session
            showMessage("Authentication cancelled. Please try again.");
            break;
          case "failed":
            showMessage(data?.message || "Payment failed. Check your card details.");
            break;
        }
      } catch (err) {
        console.error("Card payment error:", err);
        showMessage("An unexpected error occurred. Please try again.");
      }
    });
  } catch (err) {
    console.error("SDK initialization failed:", err);
  }
}
```

## Guest payments

Guest payments render a PayPal-hosted card form without requiring the buyer to create or log in to a PayPal account. The card form appears as an overlay on your page, handling card input and validation inside a PayPal-hosted environment.

<Note>
  Guest payments require the `paypal-guest-payments` component. Use the `<paypal-basic-card-button>` web component to trigger the payment flow.
</Note>

### `sdkInstance.createPayPalGuestOneTimePaymentSession(options)`

Create a guest payment session for one-time card payments. This session manages the full card collection and payment authorization flow.

#### Parameters

<table>
  <thead>
    <tr>
      <th align="left">Parameter</th>
      <th align="left">Required</th>
      <th align="left">Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>onApprove</code></td>
      <td>yes</td>

      <td>
        <p><strong>function(data).</strong> Called when the payment is approved. Capture the order using <code>data.orderId</code>.</p>
      </td>
    </tr>

    <tr>
      <td><code>onComplete</code></td>
      <td>yes</td>

      <td>
        <p><strong>function(data).</strong> Called after <code>onApprove</code> when the payment flow finishes. Use this to navigate to a confirmation page or update UI state.</p>
      </td>
    </tr>

    <tr>
      <td><code>onCancel</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer closes the card form without completing payment.</p>
      </td>
    </tr>

    <tr>
      <td><code>onError</code></td>
      <td>no</td>

      <td>
        <p><strong>function(error).</strong> Called when an unrecoverable error occurs. The error object contains <code>code</code> and <code>message</code>.</p>
      </td>
    </tr>

    <tr>
      <td><code>onWarn</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer encounters a recoverable error after submitting the card form — for example, a card decline, name formatting error, or invalid address. The overlay stays open so the buyer can correct and retry.</p>
        <p>The data object contains:</p>

        <ul>
          <li><code>message</code> — Human-readable description</li>
          <li><code>name</code> — Warning type, for example, <code>PaymentFlowWarning</code></li>
          <li><code>code</code> — Warning code, for example, <code>WARN\_FLOW\_GUEST\_CHECKOUT\_SUBMIT\_ERROR</code></li>
        </ul>
      </td>
    </tr>

    <tr>
      <td><code>onShippingAddressChange</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer changes their shipping address. See <a href="#onshippingaddresschangedata"><code>onShippingAddressChange</code></a> for the full data structure.</p>
      </td>
    </tr>

    <tr>
      <td><code>onShippingOptionsChange</code></td>
      <td>no</td>

      <td>
        <p><strong>function(data).</strong> Called when the buyer selects a different shipping option. See <a href="#onshippingoptionschangedata"><code>onShippingOptionsChange</code></a> for the full data structure.</p>
      </td>
    </tr>
  </tbody>
</table>

#### Returns

Returns a guest payment session object with a `start(options, orderPromise)` method.

#### `start(options, orderPromise)` parameters

| Parameter                  | Required | Description                                                                                                 |
| :------------------------- | :------- | :---------------------------------------------------------------------------------------------------------- |
| `options.presentationMode` | no       | **string.** How the card form overlay is displayed. Values: `auto` (default), `modal`, `popup`, `redirect`. |
| `options.targetElement`    | no       | **HTMLElement.** The element that triggered the session, used for overlay positioning.                      |
| `orderPromise`             | yes      | **Promise.** A promise that resolves to `{ orderId: string }`.                                              |

#### Web components

Use these web components to render the guest payment button:

```html lines theme={null}
<paypal-basic-card-container>
  <paypal-basic-card-button id="guest-card-button">
  </paypal-basic-card-button>
</paypal-basic-card-container>
```

#### Example

```javascript lines expandable theme={null}
const sdkInstance = await window.paypal.createInstance({
  clientId: "YOUR_CLIENT_ID",
  components: ["paypal-guest-payments"],
  pageType: "checkout",
});

const paymentMethods = await sdkInstance.findEligibleMethods({ currencyCode: "USD" });

if (paymentMethods.isEligible("card")) {

const guestPaymentSession = await sdkInstance.createPayPalGuestOneTimePaymentSession({
  onApprove: async (data) => {
    const orderData = await captureOrder({ orderId: data.orderId });
    console.log("Payment captured:", orderData);
  },
    window.location.href = "/order/success";
  },
  onCancel: () => {
    document.getElementById("guest-card-button").disabled = false;
  },
  onError: (error) => {
    console.error("Payment error:", error.code, error.message);
  },
  onWarn: (data) => {
    // Buyer encountered a recoverable error — overlay stays open for retry
    console.warn("Payment warning:", data.code, data.message);
  },
});

document.getElementById("guest-card-button").addEventListener("click", async () => {
  await guestPaymentSession.start(
    { presentationMode: "auto" },
    createOrder() // Returns Promise<{ orderId: string }>
  );
});

}
```