PayPal Drop-in integration

This page explains how to add PayPal to your existing Web Drop-in integration.

Requirements

API reference

Select which endpoint you are using:

Amounts in Hungarian Forints (HUF)

In case of a transaction in HUF, PayPal expects the transaction amount and the line item amounts to be rounded to the nearest whole amount. For example, an amount of HUF 74499 must be rounded to HUF 74500. PayPal also expects the rounded line item amounts to add up to the rounded transaction amount.

If you do not round the amounts, Adyen will do that. However, a discrepancy can occur between the transaction amount and the total of the line item amounts. When this happens, PayPal doesn't accept the transaction. To avoid that problem, we recommend that you round all HUF amounts yourself and check that they add up.

PayPal risk fields

PayPal requires marketplaces and also merchants in specific verticals to send information about the context of the transaction, for risk mitigation purposes.

Common PayPal risk fields for marketplaces

As an example, the following table shows the most common paypalRisk fields that marketplaces need to send. It is possible that PayPal requires you to send more, less, or other fields.

Drop-in configuration

Required configuration

Select which endpoint you are using:

Optional configuration

When creating an instance of Drop-in, you can also:

• Add a Content Security Policy (CSP) nonce.
• Customize the layout of the PayPal Smart Payment Buttons.
• Handle shipping changes.
• Validate user input.
• Disable the PayPal Credit button.
• Add PayPal Pay Later messages and buttons.
• Disable PayPal Pay Later.
• Set the intent for individual payments.
• Hide Venmo.

Content Security Policy (CSP) nonce

You can include a cspNonce to add a CSP nonce if you use this on your site. This was added in v5.2.0.

Layout

You can configure the layout of the PayPal Smart Payment Buttons. To do that, configure the style element in the PayPal payment method configuration. Use the available style options.

Shipping changes

You can use PayPal's callback method onShippingChange to listen to shipping address changes and validate that you support the shipping address.

Validate user input

You can validate user input with the following parameters:

• onInit: Called when the button renders.
• onClick: Called when one of the PayPal buttons is clicked.

Disable PayPal Credit

You can use blockPayPalCreditButton to control rendering the PayPal Credit button. Set this parameter to true if you do not want the PayPal Credit button to be rendered. The default value is false.

Add PayPal Pay Later messages and buttons

PayPal Pay Later is supported in the following countries/regions: AU, FR, DE, IT, ES, UK, US, with local currencies. Certain limitations apply to cross-border payments, when a shopper pays in a country/region other than where you are registered.

To present this option:

1. Set enableMessages to true, to enable Pay Later messaging on your website.
2. Render Pay Later messages and buttons by adding code to your page as described in PayPal's instructions.

Disable PayPal Pay Later

You can use blockPayPalPayLaterButton to control rendering the PayPal PayLater button. Set this parameter to true if you do not want the PayPal PayLater button to be rendered. The default value is false.

Example

const paypalConfiguration = {
  style: { // Optional configuration for PayPal payment buttons.
      layout: "vertical",
      color: "blue"
  },
  cspNonce: "MY_CSP_NONCE",
  onShippingChange: function(data, actions) {
      // Listen to shipping changes.
  },
  onInit: (data, actions) => {
      // onInit is called when the button first renders.
      // Call actions.enable() to enable the button.
      actions.enable();
      // Or actions.disable() to disable it.
  },
  onClick: () => {
      // onClick is called when the button is clicked.
  },
  blockPayPalCreditButton: true,
  blockPayPalPayLaterButton: true
};

Set the intent for individual payments

From v5.34.0 onwards, you can use intent to determine when the funds are captured and whether the payment details are tokenized:

• capture: authorizes and capture immediately.
• authorize: authorizes immediately and captures later.
• subscription: specifies this is a subscription payment.
• tokenize: specifies this is a billing payment.

Example

const paypalConfiguration = {
    intent: "authorize"
};

Hide Venmo

If you and your shopper are both located in the US, Venmo is shown in the PayPal Component by default. To hide Venmo in the PayPal Component, set blockPayPalVenmoButton to true.

Get the payment outcome

You can use the resultCode from the API response to show the shopper the current payment status. The resultCode values you can receive for PayPal are:

However, the synchronous API response doesn't give you the final outcome. To learn the final status of a payment and determine how to proceed with the order, you should wait for webhooks. This is especially important if you use any standard risk rules or custom risk rules that trigger after authorisation.

The webhooks you can receive for PayPal are:

Include more information in webhooks

For PayPal, we recommend adding the following information to your standard webhooks:

• OFFER_CLOSED event code: informs you if the shopper failed to complete the payment. To enable receiving this event code, follow the instructions for non-default event codes.

• PayPal specific details. When enabled, your standard webhooks return the following details as additionalData:

  • paypalEmail: the email address of the shopper's PayPal account.
  • paypalPayerId: the shopper's PayPal Payer ID.
  • paypalPayerStatus: indicates if the shopper's account has been verified by PayPal.
  • paypalAddressStatus: indicates if the shopper's address has been confirmed by PayPal.
  • paypalProtectionEligibility: indicates if the payment is eligible for PayPal Seller Protection.
  • paypalPayerResidenceCountry: the shopper's country or region of residence.

  To enable receiving these details, follow the instructions for additional settings, making sure to select Include PayPal Details.

Recurring payments

PayPal supports tokenization for recurring payments.

Prepare for tokenization

1. Note the PayPal setup requirements:

   • If you are not a marketplace and do not have a so-called indirect settlement arrangement, Vault (recurring) permissions must be enabled in your PayPal setup. If you completed the setup without enabling recurring transactions, restart the setup flow and this time select the relevant option.
   • If you are a marketplace or have an indirect settlement arrangement, inform our Support Team that you want to make recurring PayPal payments. They will then take care of the correct setup.

2. To be able to create tokens through initial zero-value authorization requests:

   • If you use the /sessions endpoint, make sure you are on v5.3.0 or later.
   • If you use the /payments endpoint, update your configuration as described in the next step.

3. If you want to use the /payments endpoint for creating a token through an initial zero-value authorization request, update your Drop-in configuration in one of the following ways:

   • Add intent: "tokenize" to the PayPal configuration object. This requires v5.34.0 or later.
   • Add the amount object to the global Drop-in configuration. This requires v5.3.0 or later.

   Skip this step if you are not going to create tokens through zero-value authorization requests to the /payments endpoint.

   No token is created if you send a zero-value authorization request to the /payments endpoint without having updated the configuration as described above.

Create and use tokens

When the preparation is completed, creating and using tokens for PayPal payments is the same as described for tokenization in general, except for the following:

1. To create a token through a zero-value authorization request, in your initial /sessions or /payments payment request include:

   Parameter	Description
   shopperEmail	The shopper's email address. Required when making a zero-value authorization request. Do not include this parameter if the request is not for a zero-value authorization.
   amount.value	Set to 0 when making a zero-value authorization request.

2. Proceed as described for tokenization in general: get the shopper reference and the token from the RECURRING_CONTRACT webhook, and use this data in future payments for the shopper.

For instructions, see:

• CardOnFile
• Subscription
• UnscheduledCardOnFile
• RECURRING_CONTRACT webhook

Refunds

If you have not captured a PayPal payment, you can cancel it. If you have captured the payment and you want to return the funds to the shopper, you need to refund it.

For partial refunds, the instructions differ depending on your capture settings:

• If payments are captured immediately after authorization you need to include lineItems in your partial refund request.
• If payments are captured later you need to include a capturePspReference in your partial refund request.

Partial refund when payments are captured immediately

If you are using the default setup where PayPal payments are captured immediately after authorization, partially refund a PayPal payment as follows:

1. In your /payments/{paymentPspReference}/refunds request, specify:

   Parameter	Required	Description
   amount		The amount that is refunded to the shopper.
   lineItems		Price and product information for the items that the shopper should pay for. The sum of the lineItems must match the amount. If they do not match, Adyen will add a dummy lineItem entry to account for the difference.

   Only specify the items that you are refunding the money for.

   The following example shows how to make a partial refund for item #1 of the above order.

2. Note that in the response, the pspReference is specifically for the refund transaction, not for the original payment.

Partial refund when payments are captured later

Your request for a partial refund must include a capturePspReference if all of the following is true:

• You configured capturing payments later, instead of immediately after authorization.
• Multiple partial captures are enabled for your account.
• You are going to do more than one partial capture.

PayPal uses this unique capture reference to locate the transaction in their systems. Without it, the refund can fail.

To partially refund a PayPal payment if payments are captured later:

1. Get the pspReference from the /payments/{paymentPspReference}/captures response for the payment that you want to partially refund. This is the reference to the capture that PayPal needs.

2. In your /payments/{paymentPspReference}/refunds request, specify:

   Parameter	Required	Description
   capturePspReference		The pspReference from the /payments/{paymentPspReference}/captures response. Do not use the paymentPspReference.

Set up PayPal Seller Protection

If you participate in the PayPal Seller Protection program, make sure that you submit the following fields in your payment requests:

• deliveryAddress
• shopperName
• lineItems

The details provided in these fields will populate the Ship to section of the PayPal checkout.

We recommend that you check that your setup is working correctly with a test payment. Make sure that you submit the correct fields, and that the test payment is marked as eligible for PayPal Seller Protection in the transaction details.

Test and go live

Test your integration

When you are done setting up your integration, use your PayPal sandbox accounts to test the PayPal payment flow. Your business sandbox account lets you simulate your role as a merchant when testing payments. With your personal sandbox account you can simulate the role of a customer.

Refer to the following resources:

You can check the status of a PayPal test payment in your Customer Area > Transactions > Payments.

Before you go live

For live operations, you need to get a live PayPal business account and configure your live environment. See Set up PayPal.

Note that in the live environment, PayPal will only be available if:

• The shopper is logged in to their PayPal account.
• The shopper has at least one valid payment method on their PayPal account.

See also