PayPal Payouts Installation and Usage

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

Looking to streamline your affiliate payout process and save valuable time? PayPal Payouts has you covered, freeing up more time for you to concentrate on growing your business. Promptly compensating your affiliates not only fosters trust but also encourages continued promotion of your website, knowing that referral commissions are delivered promptly. Whether it’s handling individual referrals or processing payouts in bulk, PayPal Payouts ensures efficient payment delivery directly to your affiliate’s PayPal account.

This article will guide you through the process of configuring your PayPal Business account for bulk payouts, as well as transferring that information to the applicable settings page in AffiliateWP.

---

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 addon plugin in AffiliateWP » Addons.

Access the PayPal Developer Dashboard

The first step is to login to your PayPal Developer Dashboard with your regular PayPal username and password. While the word “developer” is used, don’t worry, you will not be required to read or write code. The objective is simply to create a set of API credentials that you will copy and paste into your AffiliateWP – PayPal Payout settings.

Create the PayPal API Application

After you login, you will be presented with the PayPal Developer Dashboard screen. You will have the option of Sandbox or Live mode . Our screenshots will show that the Sandbox mode is active. We recommend this starting out as it provides the ability to do test payouts without using real currency. The slider in the top-right corner allows you toggle between Sandbox and Live mode.

If you do not have a set of Sandbox credentials, you can read more information on how to create those in PayPal’s sandbox testing guide. The steps below will be identical whether you are in Sandbox mode or Live mode.

Next, you’ll want to click on the Apps & Credentials button on the menu.

There are two payout methods possible with PayPal, however, we’re focusing on the API Application. This is the preferred method as it utilizes PayPal’s REST API, whereas PayPal MassPay is an older PayPal technology that is no longer available for new accounts. If your account already has MassPay enabled, then you’ll know where to access your credentials to apply in the AffiliateWP settings. Otherwise, you’ll want to proceed with the API Application setup method which is covered here.

On the next screen, you’ll want to click the Create App button.

On the Create App screen, all you’ll need to populate is the App name field with your preferred name. Leave the default Type selection as Merchant, and change your Sandbox/Live Business Account email if needed. When finished, click on the Create App button.

The next screen will show the completed App API with your new credentials. In the Features section, note the Payouts checkbox is already selected which is what is required. There are no other changes needed here, you can click to go back to your main dashboard page.

That is it, you have created your new PayPal API app!

Enter the PayPal API Credentials

Next, you’ll click on the copy icon for your Client ID and Secret API credentials to enter in your PayPal API Application Credentials section you’ll find by navigating to AffiliateWP » Settings » Commissions.

Check the box for PayPal Payouts in the Payout Methods selection if you haven’t already.

After selecting the PayPal Payouts checkbox, a new section will open up where you will enter your API credentials in the applicable section for your Live or Sandbox app created. The sandbox API credentials will go on the Test Client ID and Test Secret fields as shown below, and also note the Test Mode option is checked as well.

Click to Save Changes at the bottom of the screen, and now you are ready to process payouts with PayPal Payouts!

Processing Payouts with PayPal Payouts

Once you have entered your API credentials, all Unpaid referral commission entries 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 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, next click Preview Payout to see a list of all referrals that have been selected to payout.

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

Understanding PayPal API Error Codes

When processing payouts with PayPal, AffiliateWP will log an error message if something goes wrong, however it may not always be visible on the screen. Error messages can be returned for a variety of reasons, such as insufficient account privileges or account balance, or incorrect API credentials entered in the settings.

If you are receiving an error when processing payouts, or you’ve clicked to pay an affiliate and the referral remains Unpaid, please use this guide as a reference for what the error code means, and most importantly, how it can be resolved.

First, you’ll need to check the box to Enable Debug Mode in AffiliateWP » Settings » Advanced while troubleshooting.

All output from the PayPal API, including any error codes that may occur, will be written to the debug log. This log can be viewed and downloaded from AffiliateWP » Tools » Debug Assistant. 

The additional verbiage may contribute towards resolving any errors encountered from the list below.

Error: 403 Forbidden

This error means one of two things:

• Your PayPal account has not been fully approved to process payouts via the API. This is the most common reason for this error. If this is the first time you have enabled bulk payouts in your account, know that payouts are not enabled for PayPal Business accounts by default. New accounts and those with limited transaction history will need approval by PayPal merchant support. Please contact PayPal developer support to enable, and to learn more details about this process.
• Your live API credentials have been entered incorrectly.

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 are incorrect. Please triple 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 exactly from your PayPal API app page.

Frequently Asked Questions