JavaScript SDK v6 Reference

// 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
}

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.");
  },
});

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");
  },
});

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;

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" })
  );
});

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);
  }
}

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();
});

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"),
});

// 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
  }
}

// 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);
  }
}

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) => {
  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) => {
  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: 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: 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,
  });
};

<!-- 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>

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);
  }
}

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 }>
  );
});

}