PayPal Component

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

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

PayPal may require you to send PayPal risk fields. Other than that, 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 additional use case.

PayPal risk fields

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

To include paypalRisk data in your payment request, select which endpoint you are integrating:

curl https://checkout-test.adyen.com/v70/sessions \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "amount":{
      "currency":"",
      "value":1000
   },
   "shopperReference":"YOUR_UNIQUE_SHOPPER_ID",
   "reference":"YOUR_ORDER_NUMBER",
   "returnUrl":"https://your-company.com/checkout?shopperOrder=12xy..",
   "additionalData": {
      "paypalRisk": "{\"additional_data\":[{\"key\":\"sender_first_name\",\"value\":\"John\"},{\"key\":\"sender_last_name\",\"value\":\"Smith\"},{\"key\":\"receiver_account_id\",\"value\":\"AH00000000000000000000001\"}]}"
      }
   }
}'

curl https://checkout-test.adyen.com/v70/payments \
-H "x-API-key: YOUR_X-API-KEY" \
-H "content-type: application/json" \
-d '{
   "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
   "amount":{
      "currency":"",
      "value":1000
   },
   "shopperReference":"YOUR_UNIQUE_SHOPPER_ID",
   "reference":"YOUR_ORDER_NUMBER",
   "paymentMethod":{
      "type":"paypal"
   },
   "returnUrl":"https://your-company.com/checkout?shopperOrder=12xy..",
   "additionalData": {
      "paypalRisk": "{\"additional_data\":[{\"key\":\"sender_first_name\",\"value\":\"John\"},{\"key\":\"sender_last_name\",\"value\":\"Smith\"},{\"key\":\"receiver_account_id\",\"value\":\"AH00000000000000000000001\"}]}"
      }
   }
}'

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.

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>

Step 2: Create an instance of the Component

Select which endpoint you are integrating:

/sessions /payments

/sessions /payments

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.

AdyenCheckout configuration

const configuration = {
    // ...  other required configuration
    environment: "test", // Change this to "live" when you are ready to accept live PayPal payments.
    countryCode: "NL", // Only needed for test. When live, this is retrieved automatically.
    amount: {
        currency: "EUR",
        value: 1000
    },
  onSubmit: (state, component) => {
    // Your function calling your server to make the /payments request.
      makePayment(state.data)
        .then(response => {
          if (response.action) {
            // The Component handles the action object from the /payments response.
            component.handleAction(response.action);
          } else {
            // Your function to show the final result to the shopper.
            showFinalResult(response);
          }
        })
        .catch(error => {
          throw Error(error);
        });
  }
};

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

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 PayLater button

From v5.34.0 onwards, you can also set the intent for individual payments

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, validate that you support the shipping address, and update shipping costs.

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
};

Set the intent for individual payments

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"
};

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

Enable recurring payments

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

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 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:

1. Log in to your Customer Area with your company-level account.
2. Go to Developers > Additional data.
3. 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.

Make a recurring payment

You can make recurring payments once you've enabled recurring payments on your PayPal account, and configured webhooks. 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 making a zero-auth transaction with amount.value: 0, you must also include shopperEmail .

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

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.

See also