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.
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.
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.
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.
If you have enabled Pre-Approvals, you will be able to approve the payments inside the Payment History section, under the Preapproval Pending status.
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/developer/accounts/create
- Make sure to switch the account type to "Business". Fill out your name, password, and email. Leave all other settings as-is.
- At the bottom of the page click "Create Account".
- 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/
- In a separate Browser tab, load up your WordPress dashboard where you have Easy Digital Downloads - Paypal Adaptive Payments activated/installed.
- Go to "Dashboard" → "Downloads" → "Settings" → "Payment Gateways" → "Paypal Adaptive Payments".
- Go back to your original browser tab and load: https://developer.paypal.com/developer/accounts/
- Click on the email address you used to create the test account.
- In the "pop-down" after clicking, click on "Profile"
- In the "Pop-Up" click the "API Credentials" tab.
- Locate the "Username", "Password", and "Signature" and copy each to your WordPress under "Test API Username", "Test API Password", and "Test API Signature".
- Under "Test APP ID" enter "APP-80W284485P519543T".
Errors and Solutions.
"You must specify only one primary receiver and at least one secondary receiver"
- 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".
"Invalid request parameter: email is invalid"
- Double check that you have an email entered under "Dashboard" → "Downloads" → "Settings" → "Payment Gateways" → "Paypal Adaptive Payments".
"Unilateral receiver not allowed in chained payment is restricted"
- 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.
"Account not found. Unilateral receiver not allowed in chained payment is restricted"
- 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.
- 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.
"The fee payer PRIMARYRECEIVER can only be used if a primary receiver is specified".
- 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.
"The X-PAYPAL-APPLICATION-ID header contains an invalid value"
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.