PayPal
Contents
Supported Features
| Type | One Time | Recurring | Refunds | Reversals |
|---|---|---|---|---|
| 3rd Party | Yes | Yes | Yes |
No |
PayPal is one of the most popular and widely recognised online payment processors.
Setup
Begin by activating the payment gateway under Setup > Payments > Payment Gateways and choose PayPal from the Available Gateways dropdown.
Once activated, you can then enter the configuration details explained below. By default clients can chose between one-time and subscriptions payments and enter their own billing details on the PayPal site, the following options allow this behaviour to be changed.
PayPal Email
Enter the email address associated with your PayPal account, this is the only required field and all others are optional. You must next configure Instant Payment Notifications.
Force One Time Payments
When ticked clients will only be able to make one-time payments (subscriptions disabled). For recurring services they will be required to login and pay each invoice.
Force Subscriptions
When enabled clients will only be able to make subscription payments when applicable (one-time payments disabled). This means future payments will be sent automatically without the need for manual intervention. There are some caveats explained below.
Require Shipping Address
Ticking this option will require clients to provide a shipping address on the PayPal website and will be associated with their payment at PayPal, useful when selling physical products and for PayPal's Seller Protection.
Client Address Matching
The details the client provides in WHMCS upon ordering (name, address, phone number etc) will be used associated with their payment at PayPal, they will not be given the opportunity to provide different details on the PayPal website. Clients can update their profile via the WHMCS client area, your staff can use the Profile tab.
API Fields
Used for issuing refunds within WHMCS (saving the need to login at PayPal). For more information refer to Automated Refunds
Instant Payment Notification (IPN)
For PayPal invoices to be automatically marked paid when you receive a payment you need to enable IPN inside your PayPal account. This is done in the My Account > Profile > My Selling Preferences > Instant payment notifications. It's not important what URL you use so set it to your system url eg. http://www.yourdomain.com/whmcspath/ Then select the "Enabled" option.
PayPal Subscriptions/Recurring Billing
Unless disabled in the PayPal gateway config, when a user views an invoice for a recurring product or service they will be shown a PayPal Subscribe button. This allows the user to subscribe so that their payment for that product or service is sent to you automatically each month/quarter/etc... and automatically applied to the appropriate renewal invoices by WHMCS.
There are two conditions that must be met for the PayPal subscribe button to appear:
- The invoice's Due Date must be in the future
- The invoice must contain at least 1 recurring product (ie. domains and billable items on their own won't create subscriptions)
If an invoice contains both a product, and addons or domains, then any which match the products billing cycle will also be included as part of the subscription. For example, if an invoice contained a product, an addon & a domain, all of which recur on an annual basis, then the PayPal subscription that gets created by WHMCS would be for the total amount of all 3 items so that the subscription would cover everything and pay the renewal invoice in full automatically. What isn't possible however is to create a subscription that has different amounts recurring on different recurring terms, ie. $x Monthly + $Y Annually. PayPal doesn't offer an option for that at the current time.
Customising Invoice Emails for Subscriptions
When a subscription is created, the Subscription ID number that gets issued by PayPal is stored by WHMCS in the Subscription ID field for the product. Similarly when a subscription is cancelled the Subscription ID gets removed again. Therefore it is possible to use that ID value to determine if a subscription exists and therefore customise the text shown to the customer in the invoice related emails based on that.
For example, one might customise the "Invoice Created" email template to show different instructions to the customer if a subscription exists (meaning no manual action is required), compared with if one doesn't (meaning the client needs to login and pay the invoice manually), for example:
{if $invoice_subscription_id}
As you have a PayPal Subscription setup, payment will be taken automatically within the
next few days. Please ensure you have enough funds in your PayPal account to cover it.
{else}
You can login to your client area to view and pay the invoice at {$invoice_link}
{/if}
Automated Refunds
As of version 4, you can issue refunds for PayPal payments directly from within WHMCS. Before you can do this however, you need to setup PayPal API access. The steps for doing this are as follows:
- Login to PayPal
- Go to Profile > API Access
- Choose Option 2 - Request API credentials to create your own API username and password.
- Choose Option 1 - Request API Signature and click Agree and Submit
- Copy the username, password and signature that get provided and then click Done
- Enter the details from the previous step into the WHMCS Payment Gateways config screen where requested
You will now be able to enter a refund and have it sent from PayPal at the same time from within the WHMCS admin area invoice management screen.
Error Messages
Invalid Receiver Email
WHMCS validates the payment receiver email value against the details specified under Setup > Payments > Payment Gateways so this error means the two do not match. If multiple PayPal accounts are used to receive payment they must all be listed in a comma separated list eg. email1@mycompany.com,email2@mycompany.com. The first email you specify will then be the email used for new payments, but any email in the field will be accepted as an invoice payment.
Not Supported
This Result will appear when an action occurs that does not require any action on WHMCS' behalf, for example a txn_type value of "subscr_failed" mean a subscription payment failed or "subscr_eot" means End of Subscription Term. You will see these entries under normal operation and is not a problem.
Unrecognised Currency
This error in the Gateway Log means an invalid currency code has been entered under Setup > Payments > Currencies. A currency code must use the ISO 4217 standard as explained on the Currencies page. For example EURO is not valid, but EUR is valid.
This could also be caused by a blank space at the beginning or end of the currency code, so edit the code to ensure there are none.
Server Modules
cPanel/WHM - DirectAdmin - Plesk - Helm 3 - Helm 4 - Ensim - InterWorx - WebsitePanel - Cloudmin
Lxadmin - Virtualmin Pro - XPanel - HyperVM - SolusVM - Cloudmin - WHMSonic - VPS.Net
CentovaCast - SCPanel - MediaCP - GameCP - TCAdmin - Reseller Central - Auto Release - Heart Internet
Registrar Modules
Enom - ResellerClub - Nominet - OpenSRS - ResellOne - OnlineNIC - PlanetDomain - Affordable Domains
TPP Wholesale - TPPInternet - Stargate - Namecheap - NetEarthOne - Bizcn - InternetBS - GMO Internet
12Register - Registercom - DotDNS - WebNIC - Dot.TK - HexoNet - Realtime Register - Registereu
RRPProxy - ResellerCamp - TransIP - Heart Internet - IPMirror - NetRegistry - OVH - VentraIP Wholesale
Email - 101Domain
Fraud Modules
MaxMind - VariLogiX FraudCall - Telesign
Gateway Modules
2CheckOut - AsiaPay - Auth.net Echeck - Authorize.net - Authorize.net CIM - Bank Transfer - BidPay
BluePay - BluePay Echeck - BluePay Remote - Boleto - CashU - CC Avenue - ChronoPay - Direct Debit
EMatters - E-Path - eProcessingNetwork - eWAY Tokens - F2B - Finansbank - GarantiBank - Gate2Shop
Inpay - InternetSecure - IP.Pay - Kuveytturk - Modulo Moip - Mail In Payment - Merchant Partners
Merchant Warrior - IDEALMollie - Moneris - Moneris Vault - Skrill 1-Tap - NaviGate - NETbilling
Netregistry Pay - NoChex - Offline Credit Card - Optimal Payments - PagSeguro - Payflow Pro - Pay Junction
Paymate AU and NZ - Payment Express - PayPal - PayPal Card Payments - PayPal Express Checkout
PayPal Payments - PayPal Payments Pro - PayPoint.net (SecPay) - Payson - Planet Authorize - ProtX VSP Form
PSIGate - Quantum Gateway - Quantum Vault - SagePay - SagePay Tokens v2 - SecurePay
SecurePay AU - Secure Trading - TrustCommerce - USA ePay - WorldPay - WorldPay Invisible