PayPal Drop-in integration

Our Web Drop-in renders the PayPal available Smart Payment Buttons in your payment form. When a shopper selects PayPal, Drop-in presents a PayPal overlay, where shoppers can log in with their PayPal account details to complete the payment process.

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 explains how to add PayPal to your existing Web Drop-in integration. The Web Drop-in integration works the same way for all payment methods. If you haven't done this integration yet, refer to our Drop-in integration guide.

Set up a PayPal test environment

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.
   1. Go to https://developer.paypal.com and select Log into Dashboard.
   2. Select Sign up.
   3. Enter an email address and a password for your developer account.
   4. Select Create Account.
2. Create PayPal sandbox user accounts.
   1. Go to https://developer.paypal.com and select Log into Dashboard.
   2. Log in with your PayPal developer account.
   3. Under Sandbox > Accounts, you can view your default sandbox user accounts, or create new Business and Personal sandbox accounts.
      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 integration:

Set up third party API access on your PayPal account

To connect your PayPal account with your Adyen integration, you have to grant third party permissions to Adyen in your PayPal account. You have to grant third party API access on your live as well as your test PayPal Business account.

1. Log in to PayPal with your Business account.
   • Live: https://www.paypal.com/signin
   • Test: https://www.sandbox.paypal.com/signin
2. Follow PayPal's instructions:
   Under Third Party Permission Username, depending on your account type, enter:
   • Live: Enter paypal_api2.adyen.com
   • Test: Enter sell1_1287491142_biz_api1.adyen.com
   Under Permissions, select the following boxes:
   • Use Express Checkout to process payments.
   • Issue a refund for a specific transaction.
   • Process your shopper's credit or debit card payments.
   • Authorize and capture your PayPal transactions.
   • Obtain information about a single transaction.
   • Obtain authorization for pre-approved payments and initiate pre-approved transactions.
   • Generate consolidated reports for all accounts. (if available in your region)
   • Use Express Checkout to process mobile payments. (if you plan on supporting mobile payments)
   If you're using PayPal for recurring payments, also select the following boxes:
   • Charge an existing customer based on a prior transaction.
   • Create and manage Recurring Payments.
   If you're using MASSPAY, also select the following boxes:
   • Obtain your PayPal account balance
   • Initiate transactions to multiple recipients in a single batch.

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 live and your test PayPal Business accounts, and consists of 13 randomly generated letters and numbers.
To get your PayPal Merchant ID:

1. Log in to PayPal with your Business account.
   • Live: https://www.paypal.com/signin
   • Test: https://www.sandbox.paypal.com/signin
2. Find your Merchant ID.
   Live
   • Go to Settings > Account Settings.
   • Under Business profile, select Business information.
   • Copy or write down your PayPal Merchant ID.
   Test
   • Go to Profile > Account Settings.
   • Under Business profile, select Business information.
   • Copy or write down your PayPal Merchant ID.

Set up the PayPal payment method

Before you continue setting up your test integration:

1. Make sure that you have set up your back end implementation, and added Drop-in to your payments form.

2. Add PayPal in your Customer Area. 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.

Show PayPal in your payment form

Drop-in uses the countryCode and the amount.currency from your /paymentMethods request to show the available payment methods to your shopper.

1. From your server, make a /paymentMethods request specifying:
   • countryCode: Country where PayPal is supported. For example, NL.
   • amount.currency: Any supported currency. For example, EUR.
     
     

2. When creating an instance of Drop-in, specify:

   • environment: test. Change this to live when you're ready to accept live payments.
   • countryCode: the country code of the transaction.
   • amount: the currency and value of the transaction.
   • configuration.merchantId: your PayPal Merchant ID. Only required if you are using a version of Drop-in earlier than v 3.13.0 / Checkout API v64.
   • configuration.intent: Defaults to capture. Change this to authorize if you don't want to immediately capture the funds. Only required if you are using a version of Drop-in earlier than v 3.13.0 / Checkout API v64.
   • onCancel: event handler that you define for PayPal specifically to handle the situation when the shopper cancels the payment.
   • onSubmit: event handler that you define to handle the action of the shopper pressing a Pay button, for example a PayPal Smart Payment button.
   • onAdditionalDetails : event handler that you define to handle sending data to the /payments/details endpoint and presenting the response to the shopper.
   • onError: event handler that you define to handle any errors.

   const dropin = checkout
     .create('dropin', {
       paymentMethodsConfiguration: { // Example required configuration for PayPal
          paypal: {
             environment: "test", // Change this to "live" when you're ready to accept live PayPal payments
             countryCode: "NL", // Only needed for test. This will be automatically retrieved when you are in production
             amount: {
               currency: "EUR",
               value: 1000
             },
             onCancel: (data, dropin) => {
               dropin.setStatus('ready');
               // Sets your prefered status of the Drop-in component when a PayPal payment is cancelled. In this example, return to the initial state.
             }
          }
       },
       onSubmit: (state, dropin) => {
         // Your function calling your server to make the /payments request.
         makePayment(state.data)
           .then(response => {
             if (response.action) {
               // Drop-in handles the action object from the /payments response.
               dropin.handleAction(response.action);
             } else {
               // Your function to show the final result to the shopper.
               showFinalResult(response);
             }
           })
           .catch(error => {
             throw Error(error);
           });
       },
       onAdditionalDetails: (state, dropin) => {
         // Your function to submit a state.data object to the payments/details endpoint.
         submitDetails(state.data)
           .then(result => {
              // Your function to show the final result to the shopper.
              showFinalResult(result);
           })
       },
       onError: (state, dropin) => {
          // Sets your prefered status of Drop-in when an error occurs. In this example, return to the initial state.
          dropin.setStatus('ready');
       },
       ...
      })
     .mount('#dropin-container');

Optional Drop-in configuration

When creating an instance of Drop-in, you can optionally configure the layout of the PayPal Smart Payment Buttons. To do that, you configure the style element in the PayPal payment method configuration. For the available style options, refer to PayPal's documentation.

   paymentMethodsConfiguration: { // Example PayPal configuration with a different Smart Payment Button style.
   paypal: {
     merchantId: 'YOUR_PAYPAL_MERCHANT_ID',
     environment: "test", // Change this to "live" when you're ready to accept live PayPal payments
       countryCode: "NL", // Only needed for test. This will be automatically retrieved when you are in production
       amount: {
            currency: "EUR",
            value: 1000
       },
       style: { // Example optional configuration for PayPal.
              color: 'blue',
       },
     ...

Make a payment

When the shopper selects the PayPal Smart Payment button, Drop-in calls the onSubmit event, which contains a state object.

1. Pass the state.data to your server.

2. From your server, make a /payments request, specifying:

   • paymentMethod: The state.data.paymentMethod from the onSubmit event from your front end.
   https://docs.adyen.com/payment-methods/paypal/web-drop-in#paypal-api

   • curl
   • Ruby
   • Java
   • PHP
   • Python
   • NodeJS

   curl Ruby Java PHP Python NodeJS

   curl https://checkout-test.adyen.com/v66/payments \
   -H "x-API-key: YOUR_X-API-KEY" \
   -H "content-type: application/json" \
   -d '{
    "merchantAccount":"YOUR_MERCHANT_ACCOUNT",
    "shopperReference": "YOUR_UNIQUE_SHOPPER_ID",
    "reference":"YOUR_ORDER_NUMBER",
    "amount":{
      "currency":"EUR",
      "value":1000
     },
    "{hint:state.data.paymentMethod from onSubmit}paymentMethod{/hint}":{
      "type":"paypal",
      "subtype": "sdk"
       }
   }'

   # Set your X-API-KEY with the API key from the Customer Area.
   adyen = Adyen::Client.new
   adyen.api_key = "YOUR_X-API-KEY"
   
   response = adyen.checkout.payments({
     :amount => {
       :currency => "EUR",
       :value => 1000
     },
     :reference => "YOUR_ORDER_NUMBER",
     :paymentMethod => {
       :type => "paypal",
       :subtype => "sdk"
     },
     :merchantAccount => "YOUR_MERCHANT_ACCOUNT"
   })

   // Set YOUR_X-API-KEY with the API key from the Customer Area.
   // Change to Environment.LIVE and add the Live URL prefix when you're ready to accept live payments.
       Client client = new Client("YOUR_X-API-KEY", Environment.TEST);
       Checkout checkout = new Checkout(client);
   
       PaymentsRequest paymentsRequest = new PaymentsRequest();
   
       String merchantAccount = "YOUR_MERCHANT_ACCOUNT";
       paymentsRequest.setMerchantAccount(merchantAccount);
   
       Amount amount = new Amount();
       amount.setCurrency("EUR");
       amount.setValue(1000L);
       paymentsRequest.setAmount(amount);
   
       PayPalDetails payPalDetails = new PayPalDetails();
       payPalDetails.setSubtype(state.data.paymentMethod.sdk);
       payPalDetails.setPayerID(state.data.paymentMethod.payerID);
       payPalDetails.setOrderID(state.data.paymentMethod.orderID);
   
       paymentsRequest.setPaymentMethod(payPalDetails);
   
       paymentsRequest.setReference("YOUR_ORDER_NUMBER");
   
       PaymentsResponse paymentsResponse = checkout.payments(paymentsRequest);

   // Set your X-API-KEY with the API key from the Customer Area.
   $client = new \Adyen\Client();
   $client->setXApiKey("YOUR_X-API-KEY");
   $service = new \Adyen\Service\Checkout($client);
   
   $params = array(
     "amount" => array(
       "currency" => "EUR",
       "value" => 1000
     ),
     "reference" => "YOUR_ORDER_NUMBER",
     "paymentMethod" => array(
       "type" => "paypal",
       "subtype" => "sdk"
     ),
     "merchantAccount" => "YOUR_MERCHANT_ACCOUNT"
   );
   $result = $service->payments($params);

   #Set your X-API-KEY with the API key from the Customer Area.
   adyen = Adyen.Adyen()
   adyen.client.xapikey = 'YOUR_X-API-KEY'
   
   result = adyen.checkout.payments({
      'amount': {
         'value': 1000,
         'currency': 'EUR'
      },
      'reference': 'YOUR_ORDER_NUMBER',
      'paymentMethod': {
         'type': 'paypal',
         'subtype': 'sdk'
      },
      'merchantAccount': 'YOUR_MERCHANT_ACCOUNT'
   })

   // Set your X-API-KEY with the API key from the Customer Area.
   const {Client, Config, CheckoutAPI} = require('@adyen/api-library');
   const config = new Config();
   // Set your X-API-KEY with the API key from the Customer Area.
   config.apiKey = '[API_KEY]';
   config.merchantAccount = '[YOUR_MERCHANT_ACCOUNT]';
   const client = new Client({ config });
   client.setEnvironment("TEST");
   const checkout = new CheckoutAPI(client);
   checkout.payments({
       amount: { currency: "EUR", value: 1000 },
       paymentMethod: {
           type: 'paypal',
           subtype: 'sdk'
       },
       reference: "YOUR_ORDER_NUMBER",
       merchantAccount: config.merchantAccount
   }).then(res => res);

   https://docs.adyen.com/payment-methods/paypal/web-drop-in#-payments-response

   /payments response

   {
   "resultCode": "Pending",
   "action": {
       "type": "sdk",
       "paymentMethodType": "paypal",
       "paymentData": "Ab02b4c0!BQABAgARb1TvUJa4nwS0Z1nOmxoYfD9+z...",
       "sdkData": {
           "token": "EC-42N19135GM6949000"
       }
   }
3. Pass the action object to your front end. Drop-in needs the action object to continue to perform additional front end actions.

Present the PayPal overlay

When your front end receives the action object with the type sdk, Drop-in uses the dropin.handleAction(action) function to present the PayPal overlay. After the shopper completes, or fails to complete, the payment in the overlay, Drop-in calls the onAdditionalDetails event.

• Get the state.data from the onAdditionalDetails event and pass it to your server.

  https://docs.adyen.com/payment-methods/paypal/web-drop-in#state-from-onadditionaldetails

  state from onAdditionalDetails

  {
   data: {
      details: {
          orderID: "EC-42N19135GM6949000",
          payerID: "8QNW9UFUKS9ZC",
          paymentID: null,
          billingToken: null,
          facilitatorAccessToken: "A21AAEI5fCNvQ94oLgK_8d80lk1nDIQqT3DNx2SdxYjWotbMo..."
      },
      paymentData: "Ab02b4c0!BQABAgARb1TvUJa4nwS0Z1nOmxoYfD9+z..."
   }
  }

Submit additional payment details

1. From your server, submit a /payments/details request specifying the state.data object, that consists of:

   • paymentData: Payment data from the onAdditionalDetails event.
   • details: Object that contains the details of the onAdditionalDetails event.
   https://docs.adyen.com/payment-methods/paypal/web-drop-in#-payments-details-request

   /payments details request

   {
       "paymentData": "Ab02b4c0!BQABAgARb1TvUJa4nwS0Z1nOmxoYfD9+z...",
       "details": {
           "orderID": "EC-42N19135GM6949000",
           "payerID": "8QNW9UFUKS9ZC",
           "paymentID": null,
           "billingToken": null,
           "facilitatorAccessToken": "A21AAEI5fCNvQ94oLgK_8d80lk1nDIQqT3DNx2SdxYjWotbMo..."
       }
   }

   Depending on the payment result, you receive a response containing:

   • resultCode: Provides information about the result of the request.
   • pspReference: Our unique identifier for the transaction.

Present the payment result

Use the resultCode that you received in the /payments/details response to present the payment result to your shopper.
The resultCode values you can receive for PayPal are:

¹ If you use any standard risk rules or have configured any custom risk rules that might trigger after authorisation, you should monitor notifications carefully to determine the status of a payment.

Wait for notification webhooks to know the outcome of the payment. The notification webhooks you can receive for PayPal are:

Include more details in notifications

You can include more PayPal details in your Standard notifications. When you enable additional settings, you can get the following PayPal specific information returned as additionalData in your standard notifications:

To include PayPal details in your standard notifications:

1. In your Customer Area, go to Account > Server Communication.
2. Next to Standard Notification, click Edit & Test.
3. Under Additional Settings, select Include PayPal Details.
4. Click Save Configuration.

Recurring payments

Enable recurring payments

To enable recurring payments for PayPal:

1. Contact PayPal Support to enable reference transactions on your seller account.
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 Settings > 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 want to participate in the PayPal Seller Protection program, contact our Support Team to set this up for your Adyen integration.

Once you're set up, submit the following fields with a payment:

• deliveryAddress
• shopperName

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

Test and go live

Test your integration

Once you are done setting up your integration, use your PayPal test Business and Personal 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.

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

Before you go live

1. Make sure you have a PayPal Business account set up. This will be your live account.
   1. Log in to your PayPal Business account.
      
      • If you don't have a PayPal Business account, go to the PayPal website, select Sign Up and follow the instructions on your screen.
        
        We strongly recommend that you use a generic 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.
      • If you already have a PayPal Business account, go to the PayPal website, select Log In.
   2. Grant third party access on your live account.
   3. Retrieve your PayPal Merchant ID.
2. Add PayPal to your live Customer Area. You will be asked to 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.