PayPal Component

Add PayPal to an existing Components integration.

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

The PayPal Smart Payment Buttons are available from Components v 3.7.0 and later.

Before you begin

This page assumes you have already:

Built a Components integration.
Completed the PayPal setup steps or, if you are a marketplace, the PayPal setup steps for marketplaces.

API reference

Select which endpoint you're integrating:

This is the default with Components v5.0.0 or later.

Parameter name	Required	Description
lineItems		Price and product information about the purchased items. For each item, you only need to send `quantity`, `description`, `itemCategory`, `sku`, `amountExcludingTax`, and `taxAmount`. The allowed values for `itemCategory` are: DIGITAL_GOODS: goods that are stored, delivered, and used in electronic format. PHYSICAL_GOODS: tangible goods that can be shipped with proof of delivery. DONATION: a contribution or gift for which no goods or services are exchanged, usually to a not-for-profit organization.
`additionalData.paypalPairingId`		Only for customer-initiated transactions where you use the Fraudnet SDK and pass the same pairing ID to Fraudnet and Adyen. A unique ID determined by you, to link a transaction to a Fraudnet PayPal risk session. PayPal refers to this ID as pairing ID, CMID, or tracking ID.
`additionalData.paypalRisk`		Only for marketplaces and for merchants in specific verticals. A stringified `additional_data` array with the PayPal risk fields that PayPal told you to send. Each array item consists of: `key`: the name of the PayPal risk field. `value`: the value of the PayPal risk field for the current transaction. Contact your PayPal account manager to learn which `paypalRisk` fields apply in your case and what happens if you don't populate a specific field. For a list of example fields, refer to the common risk fields for marketplaces.

The following example shows a payment request with the lineItems fields you can use for PayPal, and a few paypalRisk keys and values in additionalData.

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.

Not all businesses need to send risk fields. Contact your PayPal account manager to verify.

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.

PayPal risk field	Description	Data type/format	Example
Sender profile fields:
sender_account_id	The unique identifier of the buyer's account on the marketplace platform.	String, alphanumeric	A12345N343
sender_first_name	The buyer's first name registered with their marketplace account.	String, alphanumeric	John
sender_last_name	The buyer's last name registered with their marketplace account.	String, alphanumeric	Smith
sender_email	The buyer's email address registered with their marketplace account.	String in E.123 email address format	john.smith@email.com
sender_phone	The buyer's phone number registered with their marketplace account.	String in E.123 telephone number format, national notation	0687164125
sender_address_zip	US only. The buyer's postal code registered with their marketplace account.	String, alphanumeric	60661
sender_country_code	The buyer's country registered with their marketplace account.	String in two-character ISO-3166-1 alpha-2 country code format	US
sender_create_date	The date that the buyer's marketplace account was created.	String in ISO 8601 date format	2012-12-09T19:14:55.277-0:00
sender_signup_ip	The IP address that the buyer used when signing up on the marketplace platform.	String in IPv4 or IPv6 format	213.52.172.120
sender_popularity_score	If you need to provide this field, ask your PayPal account manager for instructions.	String, possible values: high, medium, low	high
Receiver profile fields:
receiver_account_id	The unique identifier of the seller's account on the marketplace platform.	String, alphanumeric	AH00000000000000000000001
receiver_create_date	The date that the seller's marketplace account was created.	String in ISO 8601 date format	2012-12-09T19:14:55.277-0:00
receiver_email	The seller's email address registered with their marketplace account.	String in E.123 email address format	john.smith@email.com
receiver_address_country_code	The seller's country registered with their marketplace account.	String in two-character ISO-3166-1 alpha-2 country code format	US
business_name	The seller's business name registered with their marketplace account.	String, alphanumeric
recipient_popularity_score	If you need to provide this field, ask your PayPal account manager for instructions.	String, possible values: high, medium, low	high
Sender-Receiver interaction:
first_interaction_date	The date of the first interaction between the buyer and the seller. The marketplace defines what an interaction is. For example, a payment transaction, a buyer choosing to follow a seller, and so on.	String in ISO 8601 date format	2012-12-09T19:14:55.277-0:00
Transaction information:
txn_count_total	The total number of transactions that the buyer has made on the platform. These can be PayPal payments, or payments using a different payment method.	Number
Payment Flow/Model/Type:
vertical	If the seller is active in more than one business vertical, this field indicates the vertical that applies to the transaction.	String, alphanumeric	Household goods
transaction_is_tangible	Indicates if the transaction is for tangible goods.	Boolean in string format. Possible values: 0 (false), or 1 (true)	0

Component configuration

Step 1: Create a DOM element

Create a DOM element on your checkout page, placing it where you want the payment method form to be rendered:

 <div id="paypal-container"></div>

Be sure to append -container, because using just paypal in the DIV will result in an error.

Step 2: Create an instance of the Component

Select which endpoint you are integrating:

This is the default with Components v5.0.0 or later.

There is no additional configuration you need to include for PayPal.

Use the create method of your AdyenCheckout instance, in this case checkout, to create the Component:

const paypalComponent = checkout.create('paypal').mount('#paypal-container');

If you implemented an additional use case.

Parameter name	Required	Description
`amount`		The `currency` and `value` of the transaction.
`countryCode`		The shopper's country code.
`onSubmit`		Called when the shopper selects the Pay button. For PayPal, you must use the `handleAction` method to process the additional action from the PayPal pop-up window.

Include the parameters when creating an object for the global configuration of your Components integration.

Components v3.13.0 or earlier

For Components v3.13.0 or earlier, you must also provide the following parameters in the payment method configuration.

Parameter name	Required	Description
`configuration.merchantId`		Your PayPal Merchant ID.
`configuration.intent`		Set to `authorize` if you don't want to immediately capture the funds. The default value is capture.

The following example shows additional required configuration Components if you are using v3.13.0 or earlier.

const paypalConfiguration = {
    configuration: {
        merchantId: "YOUR_PAYPAL_MERCHANT_ID",
        intent: "authorize"
    }
};

Optional configuration

When creating an instance of the Component, 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.
Disable the PayPal Pay Later button.
Enable the PayPal Pay Later message.
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 don't want the PayPal Credit button to be rendered. The default value is false.

Disable PayPal PayLater

You can use blockPayPalPayLaterButton to control rendering the PayPal PayLater button. Set this parameter to true if you don't 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
};

Enable the PayPal Pay Later message

You can set the enableMessages property to true to enable the PayPal Pay Later messages.

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.

Use the create method of your AdyenCheckout instance, in this case checkout, to create an instance of the Component. Add the configuration object if you created one.

const paypalComponent = checkout.create('paypal', paypalConfiguration).mount('#paypal-container');

Recurring payments

To prepare for making recurring payments:

Enable recurring payments.
Configure webhooks to ensure they include details about recurring payments.

Then you can make recurring payments:

In the initial payment request, include specific parameters to create a token.
This token represents the shopper's stored payment details.
In the later recurring payment requests, use the token.

Enable recurring payments

If you are a marketplace, reach out to your Adyen contact to enable recurring payments for PayPal.

It you are not a marketplace, enable recurring payments for PayPal by following these steps:

Contact PayPal Support to enable Reference Transactions on your seller account. For this, you need your Merchant ID.
Enable the recurring permissions on your PayPal account. Follow the steps described in the section Give Adyen access to your PayPal account, and also grant the permissions Charge an existing customer based on a prior transaction and Create and manage Recurring Payments.

Configure webhooks

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

AUTHORISATION webhook

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

Log in to your Customer Area with your company-level account.
Go to Developers > Additional data.
Under Payment, select Recurring details.

RECURRING_CONTRACT webhook

Make sure that your server is able to receive RECURRING_CONTRACT as part of your standard webhooks.
For instructions, see non-default event codes and additional settings.

Create a token

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

shopperReference: Your unique identifier for the shopper
shopperInteraction: Ecommerce
recurringProcessingModel: Subscription or UnscheduledCardOnFile
storePaymentMethod: true
shopperEmail: Required when making a zero-value authorization request with amount.value: 0. Don't include this parameter if the request is not for a zero-value authorization.

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

eventCode: RECURRING_CONTRACT
originalReference: The pspReference of the initial payment.
pspReference: This is the token for making later recurring payments for this shopper.

Make a payment with a token

To make a later, recurring 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: Subscription or UnscheduledCardOnFile.

Set up PayPal Seller Protection

PayPal Seller Protection only applies to physical goods.

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

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:

For instructions to create sandbox accounts, see Set up PayPal, or if you are a marketplace see Set up PayPal for marketplaces.
For testing instructions, see the PayPal sandbox testing guide.

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. If you are marketplace, see Set up PayPal for marketplaces.

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.

PayPal Component

Before you begin

API reference

PayPal risk fields

Common PayPal risk fields for marketplaces

Component configuration

Step 1: Create a DOM element

Step 2: Create an instance of the Component

Components v3.13.0 or earlier

Optional configuration

Content Security Policy (CSP) nonce

Layout

Shipping changes

Validate user input

Disable PayPal Credit

Disable PayPal PayLater

Example

Enable the PayPal Pay Later message

Set the intent for individual payments

Example

Hide Venmo

Recurring payments

Enable recurring payments

Configure webhooks

AUTHORISATION webhook

RECURRING_CONTRACT webhook

Create a token

Make a payment with a token

Set up PayPal Seller Protection

Test and go live

Test your integration

Before you go live

See also

Set the `intent` for individual payments