Search

Are you looking for test card numbers?

Would you like to contact support?

Payment-method icon

PayPal Component

Add PayPal to an existing Components integration.

Our PayPal Component renders PayPal in your payment form.
When a shopper selects PayPal, the Component 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.

The PayPal Smart Payment Buttons are available from Components v 3.7.0 and later. If you're running an earlier version, see how you can upgrade.

Before you begin

Set up the PayPal payment method

This page explains how to add PayPal to your existing Web Components integration. The Web Components integration works the same way for all payment methods. If you haven't done this integration yet, refer to our Components integration guide.

Before starting your PayPal integration:

  1. Make sure that you have set up your back end implementation, and created an instance of AdyenCheckout.
  2. Add PayPal in your test Customer Area.

Set up a PayPal test environment

To test your integration, you need a developer account, a sandbox environment and a Business and a Personal sandbox account.

  1. Create a PayPal developer account.
    1. Go to https://developer.paypal.com and select Sign up.
    2. Confirm your developer account. Respond to the verification email you will receive from PayPal on the email address that you used to sign up for your developer account.
  2. Create PayPal sandbox user accounts.
    1. Go to https://developer.paypal.com and log in with your developer account.
    2. Create a Business and a Personal sandbox account.

See the PayPal Sandbox Testing Guide for more information.

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

  1. Log in to PayPal with your PayPal Business account.
  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 Charge an existing customer based on a prior transaction and Create and manage Recurring Payments.

      If you're using MASSPAY, also select Obtain your PayPal account balance and Initiate transactions to multiple recipients in a single batch.

  3. Contact our Support Team with the email address you will use for your live PayPal integration or your PayPal sandbox test integration.

Obtain your PayPal Merchant ID

To accept live payments, you need to include your PayPal Merchant ID in your Component configuration.

To get your PayPal Merchant ID:

  1. Log in to PayPal with your PayPal Business account.
  2. Go to Settings > Account Settings.
  3. Under Business profile, click Business information. Copy or write down your PayPal Merchant ID.

Show PayPal in your payment form

To show PayPal Component in your payment form, you need to:

  1. From your server, make a POST /paymentMethods request with:

    Pass the full response from the /paymentMethods call as the paymentMethodsResponse object when creating an instance of the AdyenCheckout.

  2. Add the PayPal Component:

    a. Create a DOM element for PayPal, placing it where you want the form to be rendered:

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

    b. Create an instance of the PayPal Component, specifying:

    • 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.
    • intent: Defaults to capture. Change this to authorize if you don't want to immediately capture the funds. Contact our Support Team to enable the authorize flow.
    • merchantId: your PayPal Merchant ID. Required for accepting live payments.
    • onSubmit: event handler that you define to handle the action of the shopper pressing a Pay button, for example a PayPal Smart Payment button.
    • onCancel: event handler that you define for PayPal specifically to handle the situation when the shopper cancels the payment.
    • onError: event handler that you define to handle any errors.
    • onAdditionalDetails : event handler that you define to handle sending data to the /payments/details endpoint and presenting the response to the shopper.

    Then, you mount the Component.

    When you store the PayPal Component instance in a variable, do not use the namespace paypal. This namespace is used by the PayPal Smart Payment Buttons SDK.

    const paypalComponent = checkout.create("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
      },
      intent: "capture", // Change this to "authorize" if the payments should not be captured immediately. Contact Support to enable this flow.
      merchantId: "YOUR_PAYPAL_MERCHANT_ID",  // Your PayPal Merchant ID. Required for accepting live payments.
      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);
            });
        },
      onCancel: (data, component) => {
          // Sets your prefered status of the component when a PayPal payment is cancelled. In this example, return to the initial state.
          component.setStatus('ready');
      },
      onError: (error, component) => {
          // Sets your prefered status of the component when an error occurs. In this example, return to the initial state.
          component.setStatus('ready');
      },
      onAdditionalDetails: (state, component) => {
          // 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);
            })
      }
    }).mount("#paypal-container");

Optional configuration

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.

   const paypalComponent = checkout.create("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
      },
      style: { // Example optional configuration for PayPal.
              color: 'blue',
              },
      ...

Make a payment

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

  1. If state.isValid is true, collect the state.data and pass this to your server.

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

    • paymentMethod: The state.data.paymentMethod from the onSubmit event from your front end.
    curl https://checkout-test.adyen.com/v64/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 or onChange}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.
    $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'
    })
    /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. The Component needs the action object to present the PayPal overlay.

Present the PayPal overlay

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

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

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

resultCode Description Action to take
Authorised The payment was successful. Inform the shopper that the payment has been successful.
Pending or
Received
The shopper has completed the payment but the final result is not yet known. Inform the shopper that you've received their order, and are waiting for the payment to be completed.
You will receive the final result of the payment in an AUTHORISATION notification.
Error There was an error when the payment was being processed. Inform the shopper that there was an error processing their payment. The response contains a refusalReason, indicating the cause of the error.
Refused The payment was refused by the shopper's bank. Ask the shopper to try the payment again using a different payment method.
Cancelled The shopper canceled the PayPal payment. Ask the shopper to select a different payment method.

Recurring payments

Adyen can't enable recurring payments on your PayPal account. To enable recurring payments for PayPal:

  1. Contact PayPal Support to enable reference transactions on your seller account.
  2. Enable the recurring permission on your PayPal account. Follow the steps described in the third-party API permission setup section.
  3. Send a payment request to the Adyen payments platform for PayPal with the parameter storePaymentMethod set to the value true.

PayPal notifications

Our notifications are webhooks informing you of important events related to your account.

To inform you of the outcome of a payment, we send you a notification with:

  • eventCode: AUTHORISATION.
  • pspReference: Adyen's unique reference associated with the payment request.
  • success: Indicates the outcome of the payment. Possible values:
    • true: The payment was authorised.
    • false: The payment failed.

AUTHORISATION is just one of the events that trigger a notification. Refer to Notification webhooks to accept notifications and learn about their structure and content.

Set up PayPal Seller Protection

If you're enrolled 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

Test and go live

Test your integration

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

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 with a PayPal Merchant ID and a live account.
  2. Contact our Support Team and submit a request to configure your PayPal merchantId.

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