PayPal Adaptive Payments Setup

In order to use PayPal Adaptive Payments, you will need a verified business PayPal account. You will also need to request an API Signature from PayPal. To find out how to do this, visit the following url: https://developer.paypal.com/

See also the How to get started section which explains how to get Sandbox API access and how to go live with your application: https://developer.paypal.com/webapps/developer/docs/classic/products/adaptive-payments/

You will also need to create an Application on https://apps.paypal.com/.

NOTE: Your Application on https://apps.paypal.com/ must be approved and may take some time.

Once your application is approved you will need to enter your live App ID and your PayPal API credentials into the gateway settings in Downloads → Settings → Payment Gateways. If you want to test the integration before going live, just put your store into test mode and add in PayPal Sandbox credentials into the Test API settings sections.

1

In order to actually split up your payments, you will need to add in receivers in the section below the API Credentials. Just add each receiver to a new line with a pipe bracket "|" separating the percentage you want to go to that account. NOTE: If you are using Chained Payments, these accounts must be verified PayPal accounts or the transaction will not work.

2

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.

For more information, visit the Introducing Adaptive Payments.

3

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.

4

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

User Experience

With PayPal Adaptive Payments the end user will always be sent to PayPal to complete the transaction. On-site processing is not an option.

Configuring Test Mode

Go to https://developer.paypal.com and log in using a Paypal Business Account
Step 1: Set up your developer account with Paypal.
  1. Go to: https://developer.paypal.com/developer/accounts/create
  2. Make sure to switch the account type to "Business". Fill out your name, password, and email. Leave all other settings as-is.
  3. At the bottom of the page click "Create Account".
  4. 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
  1. In a separate Browser tab, load up your WordPress dashboard where you have Easy Digital Downloads - Paypal Adaptive Payments activated/installed.
  2. Go to "Dashboard" → "Downloads" → "Settings" → "Payment Gateways" → "Paypal Adaptive Payments".
  3. Go back to your original browser tab and load: https://developer.paypal.com/developer/accounts/
  4. Click on the email address you used to create the test account.
  5. In the "pop-down" after clicking, click on "Profile"
  6. In the "Pop-Up" click the "API Credentials" tab.
  7. Locate the "Username", "Password", and "Signature" and copy each to your WordPress under "Test API Username", "Test API Password", and "Test API Signature".
  8. Under "Test APP ID" enter "APP-80W284485P519543T".

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:
Error:
"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.

Error:
"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.

Error:
"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.

Error:
"Account not found. Unilateral receiver not allowed in chained payment is restricted"
Potential Solutions:
- 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.

Error:
"Unknown Error"
Potential Solutions:
- 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.
Error:
"The fee payer PRIMARYRECEIVER can only be used if a primary receiver is specified".
Potential Solutions:
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.
Error:

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

Potential Solutions:
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.

Related Articles