On this page
No Headings
Last updated: August 6, 2026
The PayPal JavaScript SDK v6 enables you to accept the following payment methods on your website:
The v6 SDK is faster and more secure than previous versions. It also supports standalone button integrations and iframe-based integrations.
Before you start, make sure to get your PayPal client ID and secret.
Include the v6 SDK script on each page of your site that needs to accept payments.
<script src="https://www.paypal.com/web-sdk/v6/core"></script>For sandbox and testing environments:
<script src="https://www.sandbox.paypal.com/web-sdk/v6/core"></script>Authenticate with a client ID or a client token. Most integrations should authenticate with a client ID.
Use window.paypal.createInstance() to initialize the SDK with your server-generated client token and configure components, locale, and page type settings. The method returns an SDK instance that provides access to payment eligibility checking and session creation methods.
window.paypal.createInstance(options)Use paypal.createInstance to initialize the PayPal SDK with your client token and configuration. This method configures the SDK for your specific integration needs and returns an SDK instance that you'll use to create payment sessions.
| Parameter | Required | Description |
|---|---|---|
clientToken | yes | string. A secure, browser-safe token that your server generates using your PayPal client ID and secret. This token authenticates all SDK operations and is bound to your domain for security. This token expires after 15 minutes. You must generate a new token when needed. |
components | no | string[]. An array of SDK components to load for your integration. Each component enables specific payment functionality. Available components:
Default: |
pageType | no | string. The type of page where the SDK is being initialized. This helps PayPal optimize the payment experience and provide better analytics. Accepted values:
|
locale | no | string. The locale for the UI components, specified as a BCP-47 language tag, for example, |
clientMetadataId | no | string. A unique identifier for tracking and debugging. You can generate this using |
partnerAttributionId | no | string. PayPal issues this |
Returns a promise that resolves to an SDK instance object. This instance provides methods for checking payment eligibility and creating payment sessions.
findEligibleMethods() - Check payment method availabilitycreatePayPalOneTimePaymentSession() - Create a payment sessioncreateFastlane() - Initialize accelerated guest checkout (Fastlane)// Basic initialization
const sdkInstance = await window.paypal.createInstance({
clientToken: "YOUR_CLIENT_TOKEN",
});
// Full configuration
const sdkInstance = await window.paypal.createInstance({
clientToken: "YOUR_CLIENT_TOKEN",
components: ["paypal-payments", "venmo-payments"],
pageType: "checkout",
locale: "en-US",
clientMetadataId: crypto.randomUUID(),
});
// With error handling
try {
const sdkInstance = await window.paypal.createInstance({
clientToken: clientToken,
});
console.log("PayPal SDK initialized successfully");
} catch (error) {
console.error("Failed to initialize PayPal SDK:", error);
}This is the recommended approach for most implementations. It includes all payment methods with eligibility logic and automatic fallback handling. The following are key components of the integration:
paypal-payments component<paypal-button>: Standard PayPal payment button<paypal-pay-later-button>: Pay Later financing button<paypal-credit-button>: PayPal Credit buttonTo customize button colors, see the JavaScript SDK reference.
The following is an example of what an app.js file might look like when implementing the recommended setup.
async function onPayPalWebSdkLoaded() {
try {
// Get client token for authentication
const clientToken = await getBrowserSafeClientToken();
// Create PayPal SDK instance
const sdkInstance = await window.paypal.createInstance({
clientToken,
components: ["paypal-payments"],
pageType: "checkout",
});
// Check eligibility for all payment methods
const paymentMethods = await sdkInstance.findEligibleMethods({
currencyCode: "USD",
});
// Set up PayPal button if eligible
if (paymentMethods.isEligible("paypal")) {
configurePayPalButton(sdkInstance);
}
// Set up Pay Later button if eligible
if (paymentMethods.isEligible("paylater")) {
const payLaterPaymentMethodDetails = paymentMethods.getDetails("paylater");
setUpPayLaterButton(sdkInstance, payLaterPaymentMethodDetails);
}
// Set up PayPal Credit button if eligible
if (paymentMethods.isEligible("credit")) {
const paypalCreditPaymentMethodDetails = paymentMethods.getDetails("credit");
setUpPayPalCreditButton(sdkInstance, paypalCreditPaymentMethodDetails);
}
} catch (error) {
console.error("SDK initialization error:", error);
}
}
// Shared payment session options for all payment methods
const paymentSessionOptions = {
// Called when user approves a payment
async onApprove(data) {
console.log("Payment approved:", data);
try {
const orderData = await captureOrder({
orderId: data.orderId,
});
console.log("Payment captured successfully:", orderData);
} catch (error) {
console.error("Payment capture failed:", error);
}
},
// Called when user cancels a payment
onCancel(data) {
console.log("Payment cancelled:", data);
},
// Called when an error occurs during payment
onError(error) {
console.error("Payment error:", error);
},
};
// Set up standard PayPal button
async function configurePayPalButton(sdkInstance) {
const paypalPaymentSession = sdkInstance.createPayPalOneTimePaymentSession(
paymentSessionOptions,
);
const paypalButton = document.querySelector("paypal-button");
paypalButton.removeAttribute("hidden");
paypalButton.addEventListener("click", async () => {
try {
await paypalPaymentSession.start(
{ presentationMode: "auto" }, // Auto-detects best presentation mode
createOrder(),
);
} catch (error) {
console.error("PayPal payment start error:", error);
}
});
}
// Set up Pay Later button
async function setUpPayLaterButton(sdkInstance, payLaterPaymentMethodDetails) {
const payLaterPaymentSession = sdkInstance.createPayLaterOneTimePaymentSession(
paymentSessionOptions
);
const { productCode, countryCode } = payLaterPaymentMethodDetails;
const payLaterButton = document.querySelector("paypal-pay-later-button");
// Configure button with Pay Later specific details
payLaterButton.productCode = productCode;
payLaterButton.countryCode = countryCode;
payLaterButton.removeAttribute("hidden");
payLaterButton.addEventListener("click", async () => {
try {
await payLaterPaymentSession.start(
{ presentationMode: "auto" },
createOrder(),
);
} catch (error) {
console.error("Pay Later payment start error:", error);
}
});
}
// Set up PayPal Credit button
async function setUpPayPalCreditButton(sdkInstance, paypalCreditPaymentMethodDetails) {
const paypalCreditPaymentSession = sdkInstance.createPayPalCreditOneTimePaymentSession(
paymentSessionOptions
);
const { countryCode } = paypalCreditPaymentMethodDetails;
const paypalCreditButton = document.querySelector("paypal-credit-button");
// Configure button with PayPal Credit specific details
paypalCreditButton.countryCode = countryCode;
paypalCreditButton.removeAttribute("hidden");
paypalCreditButton.addEventListener("click", async () => {
try {
await paypalCreditPaymentSession.start(
{ presentationMode: "auto" },
createOrder(),
);
} catch (error) {
console.error("PayPal Credit payment start error:", error);
}
});
}The createOrder() function must return a promise that resolves to { orderId: "YOUR_ORDER_ID" }. This is a key difference between v6 and previous versions of the SDK.
// In v6, this must return an object with the shape: { orderId: "YOUR_ORDER_ID" }
return fetch("/paypal-api/checkout/orders/create", {
method: "POST",
headers: {
"Content-Type": "application/json",
},
body: JSON.stringify(orderPayload),
})
.then(response => response.json())
.then(data => ({ orderId: data.id })); // <-- Required return value
} // End createOrderThe following are best practices for integrating the v6 SDK.
Keep sensitive operations server-side and validate all payment data. Provide clear feedback to users throughout the payment flow.
{ presentationMode:auto }For all available SDK methods, see the JavaScript SDK v6 reference.