On this page, you can find additional configuration for adding PayPal to your Components integration.
Before you begin
This page assumes you've already:
Create developer and sandbox accounts
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.
- Create a PayPal developer account, if you don't already have one.
Under your developer account, create PayPal 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.
See the PayPal sandbox testing guide for more information.
The following table shows the PayPal accounts that you need for your test integration:
|Account type||Description||Use it to|
|Developer||PayPal developer account.||Access the PayPal developer dashboard, create and manage Business and Personal sandbox accounts.|
|Business||PayPal sandbox Business account.
For example, ending in @business.example.com
|Add PayPal as a payment method in your test Customer Area. Provide the Merchant ID and email address of this account. For more information, see Add payment methods to your account.|
|Personal||PayPal sandbox Personal account.
For example, ending in @personal.example.com
|Test payments from a shopper's side.|
Set up third-party API access on your PayPal account
To connect your PayPal account to your Adyen integration, you have to grant third-party permissions to Adyen in your PayPal Business account. To do that:
- Log in to your PayPal test store with the test Business account.
Follow PayPal's instructions on granting third-party permissions.
For Third Party Permission Username, use sell1_1287491142_biz_api1.adyen.com.
Under Permissions, select:
- 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.
- Charge an existing customer based on a prior transaction.
- Create and manage Recurring Payments.
- 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 test and your live PayPal Business accounts, and consists of 13 randomly generated alphanumeric characters.
- Log in to PayPal with your test Business account.
- Find your Merchant ID.
- Go to Profile > Account Settings.
- Under Business profile, select Business information.
- Copy or write down your PayPal Merchant ID.
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.
Enable recurring payments
To enable recurring payments for PayPal:
- Contact PayPal Support to enable Reference Transactions on your seller account. For this, you will need your Merchant ID.
- 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.
You can get details about recurring payments in the AUTHORISATION and RECURRING_CONTRACT webhooks.
To receive the
recurring.recurringDetailReference and the
recurring.shopperReference in the
additionalDetails of the AUTHORISATION webhook:
- Log in to your Customer Area with your company-level account.
- Go to Developers > Additional data.
- Under Payment, select Recurring details.
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:
Create a token
To create a token, include in your /payments request:
- shopperReference: Your unique identifier for the shopper.
- When making a zero-auth transaction with
amount.value: 0, you must also include
When the payment has been settled, you receive a webhook containing:
pspReferenceof 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:
pspReferencefrom 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.
recurringProcessingModel: CardOnFile, Subscription or UnscheduledCardOnFile.
For more information about the
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:
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 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.
You can check the status of a PayPal test payment in your Customer Area > Transactions > Payments.
Before you go live
Create a live account
For live operations, you will need another PayPal Business account. To create one:
Go to the PayPal website, select Sign Up and follow the instructions.
We strongly recommend that you use a generic company 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. The email address for your live PayPal Business account will also be displayed on the payment receipt the shopper receives from PayPal.
- After you create your live Business account, make sure to activate it.
To set up your live PayPal Business account:
- Log in to your live PayPal Business account.
- Grant third-party access on your live account.
- Retrieve your live PayPal Merchant ID.
Add PayPal to your live Customer Area
Add PayPal to your live Customer Area. 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.
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.