PayPal

Learn how to accept PayPal payments using our Checkout SDKs or our API.


Payment Type Shopper journey Recurring Refunds Partial Refunds Captures Partial Captures Chargebacks
Wallet Yes Yes Yes Yes Yes Yes Yes

You can accept PayPal payments with:

Prerequisites

Configure PayPal API permissions

To connect your PayPal account with your Adyen integration you'll need to grant permission to Adyen's API to integrate with your PayPal account:

  1. Follow PayPal's instructions on granting third party permissions
  2. Enter the Third Party Permission Usernamepaypal_api2.adyen.com and click Lookup.
  3. In the Available Permissions list, check 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 are using PayPal for recurring payments, also check Charge an existing customer based on a prior transaction and Create and manage Recurring Payments.

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

  4. Click Add.

  5. Contact our Support Team with the email address you will use for your PayPal integration.

Create Sandbox accounts

PayPal's Sandbox accounts are what you'll use to test your integration. There are two types of PayPal Sandbox account:

  • Business: used to simulate your PayPal Business account when testing payments.
  • Personal: used to simulate the role of a shopper when testing payments.

You'll need to create both to test how your integration handles the PayPal payment flow.

Integrate with Checkout SDKs

Our Checkout SDKs support PayPal without any additional configuration. 

Verifying payment results works in the same way as it does for SDKs, but you can also set up notifications.

Integrate with API

In this section, we show the API integration steps for PayPal.

Before you begin this section, make sure you read and understand our API Integration guide.

Step 1: Get payment methods

Call /paymentMethods, specifying the amount, a countryCode, and the appropriate channel

{
  "merchantAccount":"YourMerchantAccount",
  "countryCode":"NL",
  "amount":{
    "currency":"EUR",
    "value":1000
  },
  "channel":"Web"
}

Response

{
  "paymentMethods":[
    {
      "name":"PayPal",
      "type":"paypal"
    },
  ...
  ]
}

Step 2: Redirect shopper

Make a /payments API call, providing the amount and a paymentMethod.type set to paypal. Also provide a returnUrl, which the shopper will be redirected to after they complete the payment.

If the payment will be the first in a series of recurring payments, also include:

  • shopperReference: your unique ID for the shopper.
  • paymentMethod.storeDetails set to true.
  • shopperEmail: the email address of the shopper.
{
  "merchantAccount": "YourMerchantAccount",
  "amount": {
    "currency": "EUR",
    "value": 1000
  },
  "reference": "Your order number",
  "paymentMethod": {
    "type": "paypal"
  },
  "returnUrl": "https://your-company.com/..."
}

This returns the /payments response which contains the redirect.url. Redirect the shopper to this address so they can verify the payment with PayPal.

{
  "resultCode":"RedirectShopper",
  "details":[
    {
      "key":"payload",
      "type":"text"
    }
  ],
  "paymentData":"sdfsdf...",
  "redirect":{
    "method":"GET",
    "url":"https://test.adyen.com/hpp/redirectPayPal.shtml?brandCode=paypal&currencyCode=EUR&merchantAccount..."
  }
}

Step 3: Handle redirect

After the shopper has completed the payment, they are redirected back to the returnUrl you specified in the /payments call. The redirect contains multiple parameters, you only need the payload query parameter to complete the payment.

https://your-company.com/?payload=sdfsdf...&type=complete&resultCode=authorised

Step 4: Present payment result

Finalize the payment and present result.

  1. Submit the the payload returned in the query parameters to the /payments/details endpoint. 

    {
      "details":{
        "payload":"sdfsdfsdf..."
      }
    }

    This will return the resultCode, this status will generally be the same as the resultCode in the redirect parameters. You'll also receive a pspReference, which is our unique identifier for this payment, and your merchantReference.

    If you were tokenizing the payment details, the response will also contain a recurringDetailReference, the token for the shopper's details.

  2. Use the resultCode to display result to shopper. You can use the resultCode returned in the redirect to immediately display a result page to the shopper or call /payments/details first. You should generically handle the resultCode as specified in Result Codes.

Here are the potential resultCodes as well as what they mean in particular for PayPal:

  • authorised: The payment was successful. You will receive the funds in 3 days.
  • cancelled: The shopper canceled the payment while on the PayPal website. Request them to reselect a new payment method.
  • refused: The payment was refused by the shopper's bank.

Notifications

Notifications for PayPal work in the same way as card payments. See our notifications section for more information.

Testing your integration

To test PayPal payments you'll need a PayPal personal sandbox account. Once you've set one up, use these account credentials to complete/verify the PayPal test payment.

See Sandbox account setup for more information.

When you're ready to go live, you'll need a live PayPal account.

Make a recurring PayPal payment

Adyen can not 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 recurringContract set to the value RECURRING.

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
  • deliveryAddressType
  • shopper.firstName
  • shopper.lastName