Search

Are you looking for test card numbers?

Would you like to contact support?

Payment-method icon

PayPal Drop-in integration

Add PayPal to an existing Drop-in integration.

Our Android Drop-in renders Afterpay in your payment form, and redirects the shopper to complete the payment. As with other redirect payment methods, you need to check the payment result after the shopper returns to your app.

Before you begin

This page explains how to add PayPal to your existing Android Drop-in integration. The Android 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.

Before starting your PayPal integration:

  1. Make sure that you have set up your back end implementation, and added Drop-in to your payment form.
  2. Add PayPal in your Customer Area.

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:

Environment Account What to use it for
Test - PayPal sandbox environment PayPal developer account Access the PayPal developer dashboard, create and manage Business and Personal sandbox accounts.
Test - Business PayPal sandbox Business account. Generated by PayPal, for example ending in @business.example.com Use the Merchant ID and email address of this account to add PayPal as a payment method in your test Customer Area. For more information, see Set up the PayPal payment method.
Test - Personal PayPal sandbox Personal account. Generated by PayPal, for example ending in @personal.example.com Test shopper account to test payments.
Live - Business PayPal Business account Use the Merchant ID and email address of this account to add PayPal as a payment method in your live Customer Area. For more information, see Test and go live.

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

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.

To show PayPal in your payment form, specify in your /paymentMethods request:

When the shopper proceeds to pay, Drop-in returns the paymentComponentData.paymentMethod. Pass the paymentComponentData.paymentMethod to your server — these are the shopper details that you need to make the payment.

Make a payment

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

    • paymentMethod: The paymentComponentData.paymentMethod from your client app.
    • channel: The platform where a payment transaction takes place.
    • returnUrl: URL to where the shopper should be redirected back to after they complete the payment. Get this URL from the Component in the RedirectComponent.getReturnUrl(context).
    curl https://checkout-test.adyen.com/v67/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"
     },
     "returnUrl":"adyencheckout://your.package.name"
    }'
    # 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 => ""
      },
      :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.);
    
        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" => ""
      ),
      "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': ''
       },
       '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: ''
        },
        reference: "YOUR_ORDER_NUMBER",
        merchantAccount: config.merchantAccount
    }).then(res => res);

    The /payments response contains:

    • action: Object containing information about the redirect.
    /payments response
    {
      "resultCode":"RedirectShopper",
      "action":{
         "paymentData":"Ab02b4c0!BQABAgCSZT7t...",
         "paymentMethodType":"paypal",
         "url":"https://test.adyen.com/hpp/checkout.shtml?u=redirectPayPal&p=eJxtkt..",
         "method":"GET",
         "type":"redirect"
      },
      "details":[
         {
            "key":"payload",
            "type":"text"
         }
      ],
      ...
    }
  2. Pass the action object to your client app.

Check the payment result

Drop-in redirects the shopper to complete the payment. When the shopper returns back to your app, Drop-in provides the actionComponentData object.

From your server, make a POST /payments/details request providing:

  • details: The actionComponentData.details object from Drop-in.

/payments/details request
  curl https://checkout-test.adyen.com/v67/payments/details \
  -H "x-API-key: YOUR_X-API-KEY" \
  -H "content-type: application/json" \
  -d '{
       "details": {
         "redirectResult": "eyJ0cmFuc1N0YXR1cyI6IlkifQ=="
     }
  }'

You receive a response containing:

/payments/details response
{
     "resultCode": "Authorised",
     "pspReference": "88154795347618C"
}

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.
See note 1
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.
You will receive more information about the error in the AUTHORISATION notification. The notification 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.

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

eventCode success field Description Action to take
AUTHORISATION false The transaction failed. Cancel the order and inform the shopper that the payment failed.
AUTHORISATION true The shopper successfully completed the payment. Inform the shopper that the payment has been successful and proceed with the order.
OFFER_CLOSED true The shopper did not complete the payment. Cancel the order and inform the shopper that the payment timed out.
To receive this notification as part of your standard notifications, see additional configuration.

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:

Setting Description Fields included in additionalData
Include PayPal Details Receive the PayPal details of the shopper.
  • paypalEmail – The email address of the shopper's PayPal account
  • paypalPayerId – The shopper's PayPal Payer ID
  • paypalPayerStatus – Whether the shopper's account has been Verified by PayPal
  • paypalAddressStatus – Whether the shopper's address has been Confirmed by PayPal
  • paypalProtectionEligibility – Whether the payment is eligible for PayPal Seller Protection
  • paypalPayerResidenceCountry – The shopper's country of residence

To include PayPal details in your standard notifications:

  1. In your Customer Area, go to Account > Webhooks.
  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.

If you have not requested this additional configuration yet, contact our Support Team.

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.
  • shopperInteractionContAuth.
  • recurringProcessingModel: CardOnFile, Subscription or UnscheduledCardOnFile.

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

Set up PayPal Seller Protection

PayPal Seller Protection only applies to physical goods.

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:

Сheck 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.

Test and go live

Use the following credentials to test PayPal :
Check the status of PayPal test payments in your Customer Area > Transactions > Payments.

Before you can accept live PayPal payments, you need to submit a request for PayPal in your live Customer Area.

See also