Last updated: June 17, 2026
Here's an example PayPal integration with all possible customizations enabled.
The server-side examples below show a standard integration without vault. If your account has vault enabled and you want to save payment methods, see Save payment methods to add vault configuration. Including vault by default can block other products like Pay Later messaging for merchants who don't have vault enabled.
Create and capture a PayPal order with complete customization options including shipping and payment source details.
curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{
"intent": "CAPTURE",
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"amount": {
"currency_code": "USD",
"value": "100.00"
},
"payee": {
"email_address": "[email protected]",
"merchant_id": "MERCHANT-ID"
},
"soft_descriptor": "PAYPAL *TEST STORE",
"shipping": {
"name": {
"full_name": "Firstname Lastname"
},
"address": {
"address_line_1": "123 Main St.",
"admin_area_1": "CA",
"admin_area_2": "Anytown",
"postal_code": "12345",
"country_code": "US"
}
}
}
],
"payment_source": {
"paypal": {
"experience_context": {
"return_url": "https://example.com/return",
"cancel_url": "https://example.com/cancel",
"brand_name": "EXAMPLE INC",
"locale": "en-US",
"landing_page": "BILLING",
"shipping_preference": "SET_PROVIDED_ADDRESS",
"user_action": "PAY_NOW"
}
}
}
}'After creating the order, you'll receive a complete response with order details, payer information, and payment confirmation:
{
"id": "0KD30046EH157382X",
"intent": "CAPTURE",
"status": "COMPLETED",
"payment_source": {
"paypal": {
"email_address": "[email protected]",
"account_id": "PAYER-ID",
"account_status": "UNVERIFIED",
"name": {
"given_name": "Firstname",
"surname": "Lastname"
},
"address": {
"address_line_1": "2211 N First Street",
"address_line_2": "17.3.160",
"admin_area_2": "San Jose",
"admin_area_1": "CA",
"postal_code": "95131",
"country_code": "US"
}
}
},
"purchase_units": [
{
"reference_id": "d9f80740-38f0-11e8-b467-0ed5f89f718b",
"amount": {
"currency_code": "USD",
"value": "100.00"
},
"payee": {
"email_address": "[email protected]",
"merchant_id": "MERCHANT-ID"
},
"soft_descriptor": "PAYPAL *TEST STORE",
"shipping": {
"name": {
"full_name": "Firstname Lastname"
},
"address": {
"address_line_1": "123 Main St.",
"admin_area_1": "CA",
"admin_area_2": "Anytown",
"postal_code": "12345",
"country_code": "US"
}
},
"payments": {
"captures": [
{
"id": "CAPTURE-ID",
"status": "COMPLETED",
"amount": {
"currency_code": "USD",
"value": "100.00"
},
"final_capture": true,
"seller_protection": {
"status": "ELIGIBLE",
"dispute_categories": [
"ITEM_NOT_RECEIVED",
"UNAUTHORIZED_TRANSACTION"
]
},
"seller_receivable_breakdown": {
"gross_amount": {
"currency_code": "USD",
"value": "100.00"
},
"paypal_fee": {
"currency_code": "USD",
"value": "3.98"
},
"net_amount": {
"currency_code": "USD",
"value": "96.02"
}
},
"links": [
{
"href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID",
"rel": "self",
"method": "GET"
},
{
"href": "https://api.sandbox.paypal.com/v2/payments/captures/CAPTURE-ID/refund",
"rel": "refund",
"method": "POST"
},
{
"href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
"rel": "up",
"method": "GET"
}
],
"create_time": "2024-03-15T20:41:04Z",
"update_time": "2024-03-15T20:41:04Z"
}
]
}
}
],
"payer": {
"name": {
"given_name": "Firstname",
"surname": "Lastname"
},
"email_address": "[email protected]",
"payer_id": "PAYER-ID",
"address": {
"address_line_1": "123 Main St.",
"admin_area_1": "CA",
"admin_area_2": "Anytown",
"postal_code": "12345",
"country_code": "US"
}
},
"create_time": "2024-03-15T19:57:25Z",
"update_time": "2024-03-15T20:41:04Z",
"links": [
{
"href": "https://api.sandbox.paypal.com/v2/checkout/orders/ORDER-ID",
"rel": "self",
"method": "GET"
}
]
}Complete client-side implementation using the PayPal JavaScript SDK with support for PayPal, Pay Later, and PayPal Credit payment methods.
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);
}
});
}Implement these server-side functions to support the client-side integration:
# Get client token
curl -X POST https://api-m.sandbox.paypal.com/v1/oauth2/token \
-H "Content-Type: application/x-www-form-urlencoded" \
-H "Authorization: Basic BASE64_ENCODED_CLIENT_ID_SECRET" \
-d "grant_type=client_credentials&target_customer_id=CUSTOMER_ID"
# Capture order
curl -X POST https://api-m.sandbox.paypal.com/v2/checkout/orders/ORDER_ID/capture \
-H "Content-Type: application/json" \
-H "Authorization: Bearer ACCESS_TOKEN" \
-d '{}'See the JavaScript SDK reference for more details on available options and features.