PayPal Payouts Installation and Usage

How to Install and Use the PayPal Payouts Add-on for AffiliateWP

The PayPal Payouts add-on gives you the ability to instantly pay your affiliates their earnings from your PayPal account using PayPal’s MassPay/Payout APIs.

In this article, we’ll show you how to install and set up the PayPal Payouts add-on for AffiliateWP.

1. Installing the PayPal Payouts add-on
2. Payouts API Application
3. Payouts MassPay
4. Error Codes

1. Installing the PayPal Payouts Add-on

Before we get started, be sure to install and activate AffiliateWP on your WordPress site.

Once you’ve got AffiliateWP installed and your license is verified, you’ll be able to quickly install and activate the PayPal Payouts add-on.

PayPal Payout Methods

There are two payout methods available:

• API Application
• MassPay

Using an API Application is the preferred method as it utilizes PayPal’s new REST API, whereas PayPal MassPay is an older PayPal technology that is no longer available for most accounts. If your account has MassPay enabled, you are more than welcome to use it.

The payout method used can be set from AffiliateWP » Settings » Commissions » PayPal Payouts.

Processing Payouts

Once you have entered your API credentials, all unpaid referral records will have a Pay Now action link available:

You can click Pay Now to process a payout for individual referral records. AffiliateWP will inform you of whether the payout was successful or if there was an issue:

If you prefer, you can also process payouts in bulk in one of two ways:

• Check the box on the left side of the screen for each referral you wish to pay and then choose Pay Now from the Bulk Actions menu. This will process a payment for each referral selected.
• Generating a bulk payment beginning with the blue Pay Affiliates button. This brings you to a separate screen that allows you to specify a date range and a minimum amount that affiliates need to have accumulated in order to be paid. AffiliateWP will calculate the amount due to each affiliate and then send the amount as a single payment, marking each of the included referrals as Paid in the process.

To begin, enter your filtering criteria, then click PayPal for the Payout Method, then click Preview Payout to see a list of all referrals that have been selected to pay:

If everything appears as expected, the final step is to click the Submit Payout button at the bottom of the screen:

Important Notes

PayPal Payouts requires API access to be enabled in your PayPal account. API access is available for all business accounts.

You must have a sufficient balance already present in your PayPal account to cover the payouts being processed.

You will need to pay the PayPal transfer fees in order to payout your affiliates.

2. PayPal Payouts with an API Application

Creating Your API Application

To send affiliate payouts using PayPal’s API, you will need to first create an “API Application”. This is simply a set of credentials you provide to AffiliateWP in order to allow AffiliateWP to send payment details to PayPal on your behalf.

API Applications are created from the My Apps & Credentials page of the PayPal Developer portal. Don’t worry, you do not need to be a developer to create the application.

Log in with your normal PayPal account credentials.

Live Payouts

Click on the Live toggle and then click Create App under REST API apps, select Merchant for the type of app.

On the next screen, enter “AffiliateWP – PP Payouts” as the App Name. 

Once the application is created, click on the application name to view the details page of the application.

Next, from your WordPress Dashboard, navigate to the AffiliateWP » Commissions, and under the PayPal API Application Credentials sub-heading, enter the Client ID and Secret as shown in the application details page.

Finally, to enable Payouts permission, first go to your PayPal My Account page. Then, scroll down and click Enable in the Payouts row, Live column. Fill out the form that appears and click Submit.

Once you receive approval from PayPal for Payouts, you’ll be able to process payouts to your affiliates.

Sandbox Transactions

If you’d like to set up test transactions, you can click the Sandbox toggle and use the Default Application, unless you’d like to create a specific Sandbox account for this application. Click on the app name to open the application details page.

In  AffiliateWP » Settings » Commissions, and under PayPal Payouts Payment Method, enable Test Mode, which will cause AffiliateWP to use your Sandbox credentials so you can test payout processing without transferring actual funds:

Then, enter your Sandbox app credentials in the Test Client ID and Test Secret fields. You are now ready to test PayPal Payouts.

Important Notes

PayPal Payouts requires API access and the payouts feature to be enabled in your PayPal account, available to all business accounts. You can request access to the payouts feature at this link.

If you receive a “denied” receipt from PayPal after processing a payout, the affiliate’s account may be suspended, cannot receive your site’s currency, or cannot receive payments from your country.

Be sure to have enough funds in your PayPal balance prior to paying our your affiliates.

3. PayPal Payouts with MassPay

PayPal Payouts can process payments through PayPal’s Mass Pay API if your PayPal account has Mass Pay enabled. Mass Pay is an older PayPal technology that is not available to all accounts. If Mass Pay is not available to you, please use an API Application.

Connecting Your PayPal Account

Once PayPal Payouts is installed and activated, go to AffiliateWP » Settings » Commissions » PayPal MassPay Credentials and enter your API keys. The API keys can be found in your PayPal account by going to Profile » My Selling Tools » API Access. From this screen you can request API credentials, if you don’t have them already, or view your existing API credentials:

Copy these API keys and enter them in your AffiliateWP settings, under AffiliateWP » Settings » Commissions » PayPal MassPay Credentials.

If you wish to test PayPal Payouts, you can enable Test Mode and use API keys from a test account obtained from http://developer.paypal.com.

As soon as your PayPal API keys are entered, you will be able to pay your affiliates their commissions instantly.

4. PayPal Payouts – Error Codes

When processing payouts with PayPal, AffiliateWP will display an error message if something goes wrong. Error messages can be returned for a variety of reasons, such as insufficient account privileges, incorrect API credentials, or one of many other reasons.

If you are receiving an error when processing payouts, please use this guide as a reference for what the error means and how it can be resolved. It is highly recommended to turn on the option Enable Debug Mode in AffiliateWP » Settings » Advanced while troubleshooting.

All output from the PayPal API, including error codes, will be written to the debug log which can be viewed from AffiliateWP » Tools » Debug Assistant. The additional verbiage may contribute towards resolving any errors encountered.

When an error is returned, it will be displayed like this:

Error: 403 Forbidden

This error means one of two things:

• Your live API credentials have been entered incorrectly.
• Your PayPal account has not been fully approved to process payouts via the API.

If you have confirmed that your API credentials are entered correctly, you will need to contact PayPal support and ask them to tell you why your account is unable to process payouts.

Error: 422 Unprocessable Entity

This error means one of two things:

• Your PayPal account must have an adequate balance to cover the payouts it is attempting to process.  Unlike personal PayPal accounts that withdraw from a bank or credit card source, you must have a sufficient existing PayPal balance to cover the referrals you are attempting to pay out, or you will receive this error.  Also, know that your PayPal sandbox account has a separate balance than your live account, so make sure it is adequately funded as well prior to testing with a sandbox account.
• The currency code the funds are being sent in cannot be received by the recipient due to country or account regulations.

Error: 429 Too Many Requests

This error can occur when PayPal’s systems are under abnormal load. If this occurs, wait 30 minutes and then try again.

Error: 10001 Security Header Not Valid

This error is usually caused by one of two things:

• The credentials entered at AffiliateWP » Settings » Commissions » PayPal API Application Credentials are incorrect. Please check you have entered them correctly.
• You have entered the API certificate instead of an API Signature. Please check that you have entered the correct one.

Error: invalid_client Client Authentication failed

This error means the API credentials have been entered incorrectly. Please confirm you have copied the credentials properly from your PayPal account.