PayPal Drop-in integration

On this page, you can find additional configuration for adding PayPal to your Drop-in integration.

Check that you're using a supported browser to make sure that the PayPal Smart Payment Buttons render and work correctly.

Before you begin

This page assumes you've already:

• Built a Drop-in integration.
• Added PayPal in your Customer Area.

Create developer and sandbox accounts

To test your integration, you need a PayPal developer account. Under your developer account you create a PayPal sandbox environment and a PayPal Business and Personal sandbox account to test payments.

1. Create a PayPal developer account, if you don't already have one. Follow the instructions in PayPal's documentation.
2. Under your developer account, create PayPal new Business and Personal sandbox accounts. Follow the instructions in PayPal's documentation.
   To be able to see your test payments later, it is important that you create your sandbox accounts under your PayPal developer account. For more details, see the PayPal FAQ.

See the PayPal Sandbox Testing Guide for more information.
In the following table you see an overview of the PayPal accounts that you need for your test integration:

Set up third party API access on your PayPal account

To connect your PayPal account to your Adyen integration, you have to grant third party permissions to Adyen in your PayPal Business account. To do that:

Get your PayPal Merchant ID

When you add PayPal as a payment method in your Customer Area, you need to provide your PayPal Merchant ID. Your PayPal Merchant ID is generated when you create your test and your live PayPal Business accounts, and consists of 13 randomly generated alphanumeric characters.

Set up the PayPal payment method

When you add PayPal to your test Customer Area, you will be asked to provide:

• Your PayPal email address. Use your test PayPal Business email address, for example ending in @business.example.com.
• Your PayPal account ID. Use your test PayPal Merchant ID.
• Whether you want to enable authorisation first, and capture the payment later. By default, payments will be captured immediately after authorisation. Check this box only if payments should not be captured immediately.

API reference

You don't need to send additional fields for PayPal. To see optional fields that you can send for all payment methods, choose the endpoint you integrated:

• /sessions: This is the default with Components v5.0.0 or later.
• /payments: If you implemented an advanced use case, or integrated Components before v5.0.0.

Drop-in configuration

Required configuration

Select which endpoint you're integrating:

• /sessions
• /payments

This is the default with Components v5.0.0 or later.
There's no additional configuration you need to include for PayPal.

If you implemented an advanced use case, or integrated Components before v5.0.0.

Parameter name	Required	Description
environment		Required for accepting live payments; set to live when you're ready to accept live payments. The default value is test.
amount		The currency and value of the transaction.
countryCode		The shopper's country code.
configuration.merchantId	Required with Drop-in v3.13.0 or earlier.	Your PayPal Merchant ID.
configuration.intent	Required with Drop-in v3.13.0 or earlier.	Set to authorize if you don't want to immediately capture the funds. The default value is capture.

const paypalConfiguration = {
  environment: "test", // Change this to "live" when you're ready to accept live PayPal payments.
  countryCode: "NL", // Only needed for test. When live, this is retrieved automatically.
  amount: {
      currency: "EUR",
      value: 1000
  }
};

Include the paypalConfiguration object when creating a configuration object:

https://docs.adyen.com/payment-methods/google-pay/web-component#-code-adyencheckout-code-configuration

AdyenCheckout configuration

const configuration = {
  // ...  other required configuration
  paymentMethodsConfiguration: {
    paypal: paypalConfiguration
  }
};

Optional configuration

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

• Customizing the layout of the PayPal Smart Payment Buttons.
• Handling shipping changes.
• Validating user input.
• Disabling the PayPal Credit button.

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. For the available style options, refer to Customize the PayPal Buttons in PayPal's documentation.

Shipping changes

You can configure onShippingChange to listen to shipping address changes, validate that you support the shipping address, and update shipping costs. For more information, refer to Listen for Shipping Changes in PayPal's documentation.

Validate user input

You can configure user input parameters, such as:

• onInit: Called when the button first renders. This can be useful for validating user input along with the onClick event.
• onClick: Called when one of the PayPal buttons is clicked. This can be useful for validating user input.

For more information, refer to Validation in PayPal's documentation.

Disable PayPal Credit

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

Example

const paypalConfiguration = {
  environment: "test", // Change this to "live" when you're ready to accept live PayPal payments.
  countryCode: "NL", // Only needed for test. When live, this is retrieved automatically.
  amount: {
      currency: "EUR",
      value: 1000
  },
  style: { // Optional configuration for PayPal Smart Payment Buttons.
      layout: "vertical",
      color: "blue"
  },
  onShippingChange: function(data, actions) {
      // Listen to shipping changes.
  },
  onInit: function(data, actions) => {
      // onInit is called when the button first renders.
  },
  onClick: function() => {
      // onClick is called when the button is clicked.
  },
  blockPayPalCreditButton: true
};

Recurring payments

Enable recurring payments

To enable recurring payments for PayPal:

1. Contact PayPal Support to enable Reference Transactions on your seller account. For this, you will need your Merchant ID.
2. Enable the recurring permissions on your PayPal account. Follow the steps described in the third-party API permission setup section, and also grant the permissions Charge an existing customer based on a prior transaction and Create and manage Recurring Payments.

Configure notifications

You can get details about recurring payments in the AUTHORISATION and RECURRING_CONTRACT notifications.

AUTHORISATION notification

To receive the recurring.recurringDetailReference and the recurring.shopperReference in the additionalDetails of the AUTHORISATION notification:

1. Log in to your Customer Area with your company-level account.
2. Go to Developers > API URLs > Additional data settings.
3. Under Payments, select Recurring details.

RECURRING_CONTRACT notification

Make sure that your server is able to receive RECURRING_CONTRACT as part of your standard notifications.

Make a recurring payment

You can make recurring payments once you've enabled recurring payments on your PayPal account, and configured notifications. To do this:

1. Create a shopper token.
2. Use the token to make future payments for the shopper.

Create a token

To create a token, include in your /payments request:

• storePaymentMethod: true
• shopperReference: Your unique identifier for the shopper.

When the payment has been settled, you receive a webhook notification containing:

• eventCode: RECURRING_CONTRACT
• originalReference: The pspReference of the initial payment.
• pspReference: This is the token that you need to make recurring payments for this shopper.

Make a payment with a token

To make a payment with the token, include in your /payments request:

• paymentMethod.storedPaymentMethodId: The pspReference from the RECURRING_CONTRACT.
  You can also get this value by using the /listRecurringDetails endpoint.
• shopperReference: The unique shopper identifier that you specified when creating the token.
• shopperInteraction: ContAuth.
• recurringProcessingModel: CardOnFile, Subscription or UnscheduledCardOnFile.

For more information about the shopperInteraction and recurringProcessingModel fields, refer to Recurring transaction types.

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

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 developer sandbox accounts to test the PayPal Smart Payment Buttons payment flow. There are two types of accounts that you'll use to test how your integration handles the flow:

• Business: used to simulate your role as a merchant when testing payments.
• Personal: used to simulate the role of a shopper when testing payments.

You can check the status of a PayPal test payment in your Customer Area > Transactions > Payments.
For more information, see test PayPal's Smart Payment Buttons.

Before you go live

Create a live account

For live operations, you will need another PayPal Business account. To create one:

1. Go to the PayPal website, select Sign Up and follow the instructions.
   We strongly recommend that you use a generic company email address for your live PayPal Business account instead of a personal email address. This is to prevent having to configure a new account for your business in the future, should the personal email address no longer be in use for any reason.
2. After you create your live Business account, make sure to activate it.

To set up your live PayPal Business account:

1. Log in to your live PayPal Business account.
2. Grant third party access on your live account.
3. Retrieve your live PayPal Merchant ID.

Add PayPal to your live Customer Area

1. Add PayPal to your live Customer Area. Provide:
   • Your email address. Use your live PayPal Business email address.
   • Your account ID. Use your live PayPal Merchant ID.
   • Whether you want to enable authorisation first, and capture the payment later. By default, payments will be captured immediately after authorisation. Check this box only if payments should not be captured immediately.

In the live environment, note that 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