Payment-method icon

PayPal Express Checkout

Render a PayPal Express Checkout button for one-click checkout.

You can render a PayPal Express Checkout button anywhere on your site, like a product page, to let shoppers pay without going to an additional checkout page.

PayPal Checkout Shortcut on HPP is deprecated. If you use HPP, upgrade your integration and use the instructions here to implement PayPal Express Checkout. You must do this before May 1st, 2025. Contact our Support Team or your account manager if you have questions.

Requirements

Try it out!

Implement the PayPal Web Component. PayPal Express Checkout is supported from v5.59.0 and later.

How it works

  1. You create a payment session with a /sessions request.
  2. When the shopper selects the PayPal Express Checkout button, the Component shows a PayPal lightbox either with the delivery methods for the shopper's default delivery address or without delivery methods.
  3. Depending on how you present the lightbox, the final payment amount can change when there is a change in delivery details. For example:
    • If you show the lightbox with delivery methods, and the shopper selects a different delivery method, or changes the delivery address.
    • If you show the lightbox without delivery methods, and the shopper changes the delivery address.
  4. If the final payment amount changes, you update the amount and send it to Adyen.
  5. When the shopper completes the payment in the PayPal lightbox, the Component receives the shopper's payment information from PayPal.

PayPal Lightbox with delivery methods:

PayPal Lightbox without delivery methods:

Set up PayPal express

Step 1: Create a session

  1. Make a POST /sessions request.
    You get a response that contains a sessionId.
  2. Store the sessionId in your back end.

When you set up your Web Component integration, you created a global configuration object that passes your session.id and session.sessionData to AdyenCheckout. After passing your session, you create the PayPal component. This is handled the same way as the standard PayPal Web Component for the express flow.

Step 2: Implement the API endpoint to update PayPal orders

Integrate an additional endpoint to update PayPal orders.

Depending on how you present the PayPal lightbox, the final payment amount can change:

  • PayPal lightbox with delivery methods: you show the delivery methods for the shopper's default delivery address. If your shopper changes their delivery address, or selects a different delivery method, the delivery fees may change the final payment amount.
  • PayPal lightbox without delivery methods: you show the default delivery address of the shopper. If your shopper changes their delivery address, the final payment amount may change.

If the payment amount does not change, no additional action is required.

If the payment amount changes, update it and send it to Adyen. To update the payment amount, make a POST  /paypal/updateOrder request, including the following parameters:

Parameter Required Description
sessionId -white_check_mark- The sessionId from the /sessions response.
paymentData -white_check_mark- The paymentData that you received to your front end. The value of this parameter changes each time you make a /paypal/updateOrder request.
Use the paymentData retrieved from the Component.
amount -white_check_mark- The currency and value of the final payment amount including the delivery fees, in minor units.
deliveryMethods Only for PayPal lightbox with delivery methods The array that lists the delivery methods available for the delivery address and their fees. Use the selected field to specify the chosen delivery method by setting it to true.

Below is an example to update the payment amount if you present the PayPal lightbox with delivery methods. In this example, the original item costs EUR 110 and the selected delivery method costs EUR 10.

Update payment amount with delivery methods
Expand view
Copy link to code block
Copy code
Copy code
curl https://checkout-test.adyen.com/v71/paypal/updateOrder \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
"sessionId": "CS12345679",
"paymentData": "XYZ...",
"amount": {
"currency": "EUR",
"value": 12000
},
"deliveryMethods": [
{
"reference": "1",
"description": "Express Shipping",
"type": "Shipping",
"amount": {
"currency": "EUR",
"value": 1000
},
"selected": true
},
{
"reference": "2",
"description": "Standard Ground",
"type": "Shipping",
"amount": {
"currency": "EUR",
"value": 500
},
"selected": false
}
]
}'

Below is an example to update the payment amount if you present the PayPal lightbox without delivery methods:

Update payment amount without delivery methods
Expand view
Copy link to code block
Copy code
Copy code
curl https://checkout-test.adyen.com/v71/paypal/updateOrder \
-H 'x-api-key: ADYEN_API_KEY' \
-H 'content-type: application/json' \
-d '{
"sessionId":"CS12345678",
"paymentData": "XYZ...",
"amount": {
"currency": "EUR",
"value": 12000
}
}'

In the response, you get an updated paymentData. Pass the new value to your front end. The Component needs it to complete the payment.

Example successful update response
Expand view
Copy link to code block
Copy code
Copy code
{
"paymentData": "ABC...",
"status": "success"
}

If your request fails, you receive a response that contains an errorCode. Use the errorType and message fields to troubleshoot the error.

Example failed update response
Expand view
Copy link to code block
Copy code
Copy code
{
"status": 422,
"errorCode": "000",
"message": "Only 1 deliveryMethod should be selected",
"errorType": "validation",
"pspReference": "993617895204576J"
}

Step 3: Add additional PayPal configuration

In the PayPal configuration object, set the property isExpress to true.

Configure isExpress
Expand view
Copy link to code block
Copy code
Copy code
const payPalConfiguration = {
isExpress: true,
// ... Your other configurations.
}

Step 4: Handle delivery address changes

Implement the onShippingAddressChange event in your PayPal configuration object. The event is triggered when the PayPal lightbox opens. You make an initial POST /paypal/updateOrder request.

  • PayPal lightbox with delivery methods: with your initial request, you pass the available delivery methods to Adyen, based on the shopper's default shipping address.
  • PayPal lightbox without delivery methods: with your initial request, you pass the current payment amount to Adyen.

If your shopper changes their delivery address, the onShippingAddressChange event is triggered again. For the PayPal lightbox with delivery methods, you then need to handle the delivery method changes. For the PayPal lightbox without delivery methods, you make a POST  /paypal/updateOrder request to update the final amount.

Implement your own function to make a POST /paypal/updateOrder request and update the amount. Below is an example that uses the updatePayPalOrder function. You need to pass the updated paymentData you get in the response to the Component.

Implement onShippingAddressChange
Expand view
Copy link to code block
Copy code
Copy code
const payPalConfiguration = {
isExpress: true,
onShippingAddressChange: async function(data, actions, component) {
// Example: not shipping to NL.
if (data.shippingAddress.countryCode == 'NL') {
return actions.reject();
}
// Get the current paymentData value stored within the Component.
const currentPaymentData = component.paymentData;
// Implement the code to call your backend endpoint to update the final amount based on the selected delivery method, passing the paymentData.
const { paymentData } = await updatePayPalOrder(data.shippingAddress, currentPaymentData);
// Update the Component paymentData value with the new one.
component.updatePaymentData(paymentData);
},
// ... Your other configurations.
}

Handle errors

If an error occurs, PayPal returns an error in the data object that you must pass to action.reject(). You can optionally use the included error message for some validation scenarios.

Step 5: Handle delivery method changes

This step is only required if you present default delivery methods when the PayPal lightbox opens.

Implement the onShippingOptionsChange event in your PayPal configuration object to handle situations where the shopper selects a different delivery method.

Make a POST /paypal/updateOrder request. In your request, specify the chosen delivery method by setting selected:true, and update the amount.value based on the selected delivery method.

Implement onShippingOptionsChange
Expand view
Copy link to code block
Copy code
Copy code
const payPalConfiguration = {
isExpress: true,
onShippingAddressChange: function(data, actions, component) {...},
onShippingOptionsChange: async function(data, actions, component) {
// Example: PostNL is unavailable.
if (data.selectedShippingOption.label.includes('PostNL')) {
return actions.reject(data.errors.METHOD_UNAVAILABLE);
}
// Get the current paymentData value stored within the Component.
const currentPaymentData = component.paymentData;
// Implement the code to call your backend endpoint to update the final amount based on the selected delivery method, passing the paymentData.
const { paymentData } =await updatePayPalOrder(data.selectedShippingOption, currentPaymentData)
// Update the Component paymentData value with the new one.
component.updatePaymentData(paymentData);
}
},
// ... Your other configurations.

Step 6: Get the shopper's payment information

After the shopper completes the payment in the PayPal lightbox and the lightbox closes, you can get the shopper's payment information.

How you do this depends on the Web Component version you are using:

When the lightbox closes, the Component triggers the onAuthorized callback.

Implement the onAuthorized callback in your PayPal configuration object to get the information, using the following properties:

Property Description
data The raw event received from PayPal that contains the shopper details in the authorizedEvent object, the billingAddress, and the deliveryAddress. The Component formats the details for compatibility with the Checkout API.
actions
  • actions.resolve(): continues the flow.
  • actions.reject(): cancels the flow.

You can use the shopper's details to manage the order. For example, use the shopper's name and delivery address for the shipping label.

Implement onAuthorized
Expand view
Copy link to code block
Copy code
Copy code
const payPalConfiguration = {
isExpress: true,
onShippingAddressChange: function(data, actions, component) {...},
onShippingOptionsChange: function(data, actions, component) {...}, // Only if you need to handle delivery method changes.
onAuthorized: (data, actions) => {
// You can use the shopper's details to manage the order.
actions.resolve();
},
// ... Your other configurations.
}

Step 7: Complete the payment

The Component makes an authorization request to complete the payment. Use the onPaymentCompleted callback to redirect the shopper to the payment confirmation page.

Add a payment review page

Adding a payment review page is not possible if your integration uses the Sessions flow.

Recurring payments

PayPal Express Checkout supports tokenization for recurring payments.

We strongly recommend that you ask explicit permission from the shopper if you intend to make future recurring payments. Being transparent about the payment schedule and the charged amount reduces the risk of chargebacks.

When creating a token through a PayPal Express Checkout payment, keep in mind the following:

  • PayPal Express Checkout does not allow zero-value authorization requests to create a token.
  • Tokenization through a PayPal Express Checkout request fails if the PayPal configuration object includes intent: "tokenize".

Other than the above points, creating and using tokens for PayPal Express Checkout payments is the same as described for tokenization in general.

For instructions, see: