PayPal Adaptive Payments Setup

In this documentation, we provided all the setup and installation instructions you need to do, as well as configuring the PayPal Sandbox Testing for the PayPal Adaptive Payments Plugin. If you haven’t acquired the plugin yet, please also visit the plugin’s download site.

Unfortunately, PayPal no longer accepts new application for PayPal Adaptive payments gateway. PayPal Adaptive payments gateway can still be used by existing users but not by new users anymore. We are currently investigating this, so if you are interested to be notified when an alternative solution becomes available, kindly drop us an email.

What to check before purchasing

The following are the things you need to have before purchasing and using this plugin.

  • Check whether your country is supported by PayPal
  • Approved account by PayPal – you can contact PayPal Support through the following links: Link 1 | Link 2
  • Commissions Plugin installed in your website
  • PayPal Business account

Setup and Installation

Before proceeding with the installation, you must by now have an approved PayPal Account or else you can’t use this plugin at all. Next steps are:

  • Go to your WordPress Dashboard. Select Plugins on the left and Add New.
  • Select Upload Plugin.
  • Select the Browse Button to install the zip file with the plugin.
  • Activate the plugin if needed.
add new plugin

Then, go to Downloads > Settings > Payment Gateways > General. Tick PayPal Adaptive Payments as your Payment Gateway. You can also set it as your Default Gateway.

Further below, you can tick the box of which Accepted Payment Method Icons will show in your Checkout Page.

PayPal Adaptive PAyments General Settings

Plugin Configuration

a) Once your application is approved and have the plugin installed in your WordPress website, go to gateway settings in Downloads → Settings → Payment Gateways → PayPal Adaptive Payments. You can then see the following details that needed to be filled out.

Note:  You can get your API Credentials by visiting your PayPal Profile → API Credentials tab and fill out the necessary details in the PayPal Adaptive Payments settings.

  • PayPal Adaptive Payments License Key – Enter your license key that will be provided upon purchase of this plugin.
  • Live API Username, Live API Password and Live API Signature – Fill these sections by the details from your API Credentials located at your PayPal Profile.
  • Live APP ID – You can get this by creating an account at www.x.com and registering a new APP.
  • Test API Username, Test API Password, Test API Signature and Test APP ID – Only needs to be filled out when testing the plugin and by using a Sandbox Account. If not, just leave these fields empty.

b) In order to actually split up your payments, you will need to add in your receivers email in the section below the API Credentials. Just add each receiver email to a new line with a pipe bracket “|” separating the percentage you want to go to that account.

e.g.

[email protected]|50

[email protected]|30

[email protected]|20

NOTE: If you are using Chained Payments, these accounts must be verified PayPal accounts or the transaction will not work.

c) You can choose your Payment Type as well. The options available are Chained Payments and Parallel Payments.

  • Chained Payments: Your Store accepts the entire payment and secretly pays commissions to Vendors after the sale.
  • Parallel Payments: The customer knows everyone who will receive payment upon checkout – as the payments are split visually at checkout.

d) The last option is to set whether you want to require a Pre-Approval before actually charging the customer. If this is enabled, the customer will authorize the charge and you will have up to a year to submit the charge before the customers approval will be cancelled.

NOTE: If you have enabled Pre-Approvals, you will be able to approve the payments inside the Payment History section, under the Preapproval Pending status.

For more information, visit the Introducing Adaptive Payments.

Splitting Commissions automatically

By using PayPal Adaptive Payments plugin, expect that each of your  respective vendor will receive their commission automatically. Now, how can we configure our receivers?

Vendor Profile Form

Please ensure you activate the PayPal field (coming from this plugin) in the Menu FES / Registration Form. All vendors will need to enter a valid PayPal Email address, otherwise the payments will not come through.

Defining Vendor Commission Rates

The way this plugin works is that the commission settings (coming from the Commissions Plugin) overrule the general plugin settings. So for every product download, you can basically define different commission recipients. Take note that the split can be set individually by product.

Splitting Commissions Automatically per product page

Now, the plugin settings should only include 1 hard-coded recipient.

splitting commissions automatically plugin settings

Above settings will split the sale in the ratio 10 / 5 / 85 automatically upon purchase. The customer will only see the PayPal address of the admin appears while the PayPal email addresses of the other commission receivers will remain hidden. We recommend to not only test this on the PayPal Sandbox but also do 2-3 test purchases on the live environment (with low amounts) to verify that this works correctly.

How to test if PayPal Adaptive Payments really works?

After having this plugin installed and configured, we can conduct a test and see if this plugin properly works just to be sure and which prevents us from future problems. We can try either tests: (1) testing via a live paypal account or (2) testing with a sandbox account.

(1) Testing via Live PayPal Account

For website starters, you can save yourself time by testing the plugin using a Live PayPal Account. This way, you only need to test once which prevents additional time-consuming work needed when conducting the first test with PayPal Sandbox.

In order to do live testing of this plugin, you can simply follow the steps above to configure the plugin first, then use a Test Live PayPal account to simulate test purchase and see if this plugin works correctly.

(2) Testing via a Sandbox Account

If you are currently operating a webstore with a huge amount of traffic and is using a different payment gateway, you might need an extensive and careful testing first to prevent problems and complications with your customers.

We then recommend you to try testing using PayPal Sandbox Account first. In order to do this, you can follow the steps below before logging in with PayPal Sandbox and conducting some test purchase to see if this plugin works perfectly.

Test Mode Configuration

Go to https://developer.paypal.com and log in using a Paypal Business Account.

Step 1: Set up your developer account with Paypal.

a. Go to: https://developer.paypal.com/developer/accounts/create

b. Make sure to switch the account type to “Business”. Fill out your name, password, and email. Leave all other settings as-is.

c. At the bottom of the page click “Create Account”.

d. Also create a test buyer account so you can do a test purchase. Set your “Buyer” account to be a “Personal” account. You will also do this here: https://developer.paypal.com/developer/accounts/.

Step 2: Copy your API credentials into WordPress

a. In a separate Browser tab, load up your WordPress dashboard where you have Easy Digital Downloads – Paypal Adaptive Payments activated/installed.

b. Go to “Dashboard” → “Downloads” → “Settings” → “Payment Gateways” → “Paypal Adaptive Payments”.

c. Go back to your original browser tab and load: https://developer.paypal.com/developer/accounts/.

d. Click on the email address you used to create the test account.

e. In the “pop-down” after clicking, click on “Profile”

f. In the “Pop-Up” click the “API Credentials” tab.

g. Locate the “Username”, “Password”, and “Signature” and copy each to your WordPress under “Test API Username”, “Test API Password”, and “Test API Signature”.

h. Under “Test APP ID” enter “APP-80W284485P519543T”.

Common Errors and Solutions

Paypal Adaptive Payments is one of the most complex payment gateways to properly configure. There’s a good chance that you’ll run into an error message while getting setup. This is normal. If you run into one of the following errors, try each of the listed solutions to make sure you have configured everything correctly.

You must specify only one primary receiver and at least one secondary receiver

Potential Solutions:
Double check that your Payout percentage adds up to 100. You can check this by going to “Dashboard” → “Downloads” → “Settings” → “Payment Gateways” → “Paypal Adaptive Payments” → “PayPal Adaptive Receivers”.

If you are using the Commissions extension, make sure you have enabled automatic payouts under “Dashboard” → “Downloads” → “Settings” → “Extensions” → “Commissions”.

Make sure you aren’t paying from yourself to yourself. This can often happen during testing. Your payee email must be a different account than your receiver – and they must both be Paypal test accounts. You can create test account in your Paypal Sandbox account here:https://developer.paypal.com/developer/accounts/

Make sure you are not using “Chained” payments – which requires more than one reciever.

Invalid request parameter: email is invalid

Potential Solutions:
Double check that you have an email entered under “Dashboard” → “Downloads” → “Settings” → “Payment Gateways” → “Paypal Adaptive Payments”.

If you are using the “Commissions” extension and you are purchasing a Download, double check that the “Users” field isn’t blank.

Unilateral receiver not allowed in chained payment is restricted

Potential Solutions:
Make sure that the email you are sending money to is connected to a Paypal account. If it isn’t, Paypal can’t deposit money to it.

If you are in “test” (or “Sandbox”) mode, make sure the emails are connected to sandbox accounts.

Account not found. Unilateral receiver not allowed in chained payment is restricted

Potential Solution:
This is usually caused by a receiver’s email address that is unconfirmed. When using Chained Payments, all receivers must have an existing PayPal already. Here’s how to confirm the email address: Log in to your PayPal account. Click Profile near the top of the page. Click Update beside Email. Select the email address you want to confirm, click Confirm and Paypal will send you an email. Click the link in the email to complete the confirmation process.

Unknown Error

Potential Solution:
Paypal Adaptive requires certain security protocols and some servers and versions of MAMP may not be using those and fail without relevant errors. If you are getting an “Unknown Error”, it is likely that your server is not using the correct security protocols and those need to be upgraded. You may need help with your Webhost or upgrade to the latest version of MAMP.

https://developer.paypal.com/docs/classic/lifecycle/info-security-guidelines/

The X-PAYPAL-APPLICATION-ID header contains an invalid value

Potential Solution:
–  It may be possible that your Live APP ID has not been approved by Paypal yet. Double check with Paypal support to make sure they have approved your Live APP ID.

The fee payer PRIMARYRECEIVER can only be used if a primary receiver is specified.

Potential Solution:
– Double check that you aren’t using “Chained Payments” along with the the Fee Payer being set to “Primary Reciever”. This is not a combination that Paypal allows. Switching from “Chained” to “Parallel” mode will fix this. For more info on this, see this page from Paypal.

Payment status is not updated from Pending to Completed

Potential Solution:
Make sure in your PayPal Account IPN, the Instant Payment Notification Service is enabled. This service is needed so that PayPal can inform your EDD Store in case users did not properly finish the checkout process. In EDD, the in-built PayPal Standard Gateway acts as the receiving endpoint for the the PayPal IPN Service of your Easy Digital Downloads store. See here for futher information.

After turning on the IPN service in PayPal, you can view your IPNs on the IPN History page. If necessary, you can resend IPN messages from that page. For more information on using and troubleshooting this feature, read more about Instant Payment Notification (IPN).

Frequently Asked Questions

Is this plugin compliant with the new European Payment Services (PSD2) directive regarding Strong Customer Authentication (SCA)?

Yes our PayPal Adaptive Payments plugin is fully compliant. We checked this with PayPal Merchant Technical Support (see also here). The checkout flow for PayPal Adaptive Payments is hosted on PayPal website and therefore PayPal confirms to take care of the PSD2 requirements. There is nothing to be done from the merchant’s end.

PSD2 aims to protect European consumers from financial fraud. The directive also applies to businesses outside the EU as purchases made to EU customers can be refused if not properly authenticated (as one leg of the transaction is based in the EU, see also PaymentsGuru. However, please recheck with your payments provider. PSD2 asks for using two out of three accepted methods to authenticate European customers such as methods related to (1) knowledge (something only the user knows such as password or PIN), (2) possession (something only the user possesses, e.g. a token) and (3) inherence (something the user is such as a fingerprint).

For further information regarding the PSD2 directive (Strong Customer Authentication SCA) see the two articles on Wikipedia with respect to PSD2 and Strong Customer Authentication and the EU Website regarding PSD2.

How to contact PayPal and get your account approved for PayPal Adaptive Payments?

Best way to do this is to contact PayPal Support through the following links: Link 1 | Link 2

Simply ask them that you like to use PayPal Adaptive Payments Gateway and would need to know how you can get your account approved and what information they need from you. Better to ask two times and make sure you insist on getting clear answers from PayPal.

How do you configure receivers and expect each of them receive their commission automatically?

The way this plugin works is that the commission settings (coming from the Commissions Plugin) overrule the general plugin settings. So for every product download, you can basically define different commission recipients. Then at plugin settings, should only include 1 hard-coded recipient. We recommend to not only test this on the PayPal Sandbox but also do 2-3 test purchases on the live environment (with low amounts) to verify that this works correctly. If you have any other questions, please Contact Us.

Can I select two or more Payment Gateways?

Yes. If you still wish to give your customers different payment options, you can select two or more Payment Gateways in the General Settings. But be aware that if the customer uses the other payment gateway, commissions received will not be split.

Where can I get my API Credentials?

You can go to your PayPal Account, locate “Profile” then in the pop-up, select the API Credentials tab. You can copy and paste those details to your PayPal Adaptive Payments settings.

Where can I approve payment pre-approvals?

If you have enabled Pre-Approvals, you will be able to approve the payments inside the Payment History section, under the Preapproval Pending status.

Can I use PayPal in my country?

Here is the list of countries we are aware of in which PayPal Adaptive Payments should work. Please double check with PayPal Support once more to be sure this information are still accurate before you purchase our plugin.

– Australia, Canada, Denmark, Finland, France, Ireland, Norway, Sweden, United Kingdom, United States, Austria, Belgium, Germany, Italy, Netherlands, Spain, Brazil, Hong Kong, Switzerland, China, Poland, Turkey.

I receive PayPal Instant Payment Notification (IPN) Warnings. What shall I do?

You might need to recheck if your IPN listener is correctly configured and must be in the correct format: “https://www.domain.com/?ipn=epap”.

Also, make sure that your URL query is excluded from caching (Litespeed, W3, Cloudflare, …. etc.) and that your PayPal IP adresses need to be whitelisted (Webhost, Cloudflare, Wordfence).

See list of PayPal IP addresses, sections notify.paypal.com and ipnpb.paypal.com.

Do Customers need to have a PayPal account in order to purchase via the PayPal Adaptive Payment Gateway?

No, you can perfectly have them checkout as a Guest via PayPal Guest Checkout. However, this is something you need to request from PayPal Support as per default they will want your customers to register with them. So kindly contact PayPal Support and ask them to confirm that PayPal Guest Checkout is enabled so that any user can checkout without requiring a PayPal account.

How long does it take to set up PayPal Adaptive Payments?

This depends if your PayPal Account is already approved or not, which actually takes some time. But in principle, this can be done quickly.

Which payment type should I use – chained or parallel payments?

We recommend you to use Chained Payments as your vendors, in principle, should not see your customer email addresses for data privacy reasons.

What happens if a customer requests a refund?

You can go to your PayPal Account and challenge the transaction. Simply request a refund from whoever you paid the commission to.

It says “A payment did not go through”, what should I do?

You can check if the vendor entered a valid PayPal email address or not.

It works on test environment but not on production environment, what should I do?

Go back through the setup process and check each step if you have correctly and properly followed it. If it’s still not working, please reach out to PayPal suppport and us to assist with the configuration.

Where can I see all commissions paid to the vendors?

You can go to your commissions report in EDD (Commissions Plugin) or go to your PayPal account to see the activity for payments made.

I need help in setting up this plugin. Can you help?

Yes. Kindly contact us and we will do our best to help you set this up.

Contact Us

If you face any problem installing and bringing this plugin to work, please contact us via support and we will get back to you within 24 hours.