PayPal express checkout

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.

1. When the shopper selects the PayPal express checkout button, the Component makes a /payments request.
2. 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. The Component makes a /payments/details request to authorize the payment.
6. When the payment is completed in the PayPal lightbox, the Component receives the shopper's payment information from PayPal.

If you use the Advanced flow, you can additionally implement a review page where your shopper can review and confirm their payment. To learn about this flow and the setup, refer to Add a payment review page.

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		The sessionId from the /sessions response.
paymentData		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		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.

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

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

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

Step 3: Add additional PayPal configuration

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

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.

Step 5: Handle delivery method changes

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.

Step 6: Get the shopper's payment information

After the shopper completes the payment in the PayPal lightbox, the lightbox closes and the Component triggers the onShopperDetails callback.

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

Property	Description
shopperDetails	Shopper details received from PayPal. The Component formats the details for compatibility with the Checkout API.
rawData	The shopper details received from PayPal, in raw format.
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.

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.

Step 1: Store the PSP reference

When the shopper selects the PayPal express checkout button, the onSubmit callback is triggered and your server makes a /payments request.

The /payments response contains the pspReference field. Store the PSP reference in your back end.

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
pspReference		The pspReference from the /payments response.
paymentData		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		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.

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

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

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

Step 3: Add additional PayPal configuration

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

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

Step 5: Handle delivery method changes

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.

Step 6: Get the shopper's payment information

After the shopper completes the payment in the PayPal lightbox, the lightbox closes and the Component triggers the onShopperDetails callback.

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

Property	Description
shopperDetails	Shopper details received from PayPal. The Component formats the details for compatibility with the Checkout API.
rawData	The shopper details received from PayPal, in raw format.
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.

Step 7: Submit additional payment details

In your AdyenCheckout configuration, or in the paypalConfiguration object, implement the onAdditionalDetails callback, which makes a POST /payments/details request to authorize the payment. In your request, include the following fields:

• details: the state.data.details from the onAdditionalDetails event.
• paymentData: the state.data.paymentData from the onAdditionalDetails event.

Below is an example /payments/details request to authorize the payment:

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

After the PayPal lightbox is closed, you can optionally display an order review page that contains the details of the payment, including the delivery method the shopper selected in the PayPal lightbox.

If you implement a review page, the onShopperDetails callback is triggered when the shopper proceeds to review the order instead of when the payment is completed in the PayPal lightbox.

Follow the steps below after you have followed the guide to set up PayPal express until the Submit additional payment details step.

Step 1: Enable the review page flow

In the PayPal configuration object, add the userAction: continue configuration to enable the review page flow.

Step 2: Create a review page

Use the shopper details you collected to present a review page that contains:

• An order summary
• Delivery address and method
• Details of the total amount, showing the breakdown of the order total and delivery fees
• A Pay button to confirm the payment

Step 3: Redirect shopper to the review page

In your AdyenCheckout configuration, or in the paypalConfiguration object, implement the onAdditionalDetails event to collect the final payment data and to redirect your shopper to the review page. You then use the final payment data to finalize the payment in the review page.

Below is an example that uses the storePaymentData and redirectShopperToReviewPage functions.

When the onAdditionalDetails event is triggered, you get a state.data object. Store this value as you need it to submit additional payment details later.

Step 4: Submit additional payment details

When the shopper selects the Pay button on the review page, make a POST /payments/details request with:

• details: the state.data.details from the onAdditionalDetails event.
• paymentData: the state.data.paymentData from the onAdditionalDetails event.