PayPal Basic
Contents
About this Module
For information on all of our PayPal integrations, see PayPal.
The PayPal Basic payment gateway module is available in WHMCS.
Supported Features
| Type | One Time | Recurring | Refunds | Reversals |
|---|---|---|---|---|
| 3rd Party | Yes | Yes | Yes |
Yes |
Adding the PayPal Basic Payment Gateway
Watch the video tutorial for this feature 
To set up the PayPal Basic payment gateway in WHMCS:
- Go to the appropriate location for your version of WHMCS:
- For WHMCS 8.0 and later, go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
- For WHMCS 7.10 and earlier, go to Setup > Products/Services > Payment Gateways and choose All Payment Gateways.
- Click PayPal Basic.
- Check Show on Order Form to display this payment method in the Client Area during checkout.
- Enter your PayPal Basic credentials.
- For PayPal Email, enter the email address associated with your PayPal account, this is the only required field and all others are optional. If you have more than one email address associated with your PayPal account, you may add as many of those as you like, comma-delimited. You must next configure Instant Payment Notifications.
- For Force One Time Payments, check to only allow clients to make one-time payments (subscriptions disabled). For recurring services they will be required to login and pay each invoice.
- For Force Subscriptions, check to only allow clients 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.
- For Require Shipping Address, check to 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.
- For Client Address Matching, check to ensure that the details the client provides in WHMCS upon ordering 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 or your staff can use the Profile tab.
- For API Username, API Password, and API Signature, enter the credentials from your PayPal account:
- Log in to your PayPal account.
- Go to Account Setting by hovering over your name in the top-right corner.
- Click Update next to API Access.
- Under NVP/SOAP API integration, click Manage API credentials.
- Choose Request API signature.
- Click Agree and Submit.
- This allows you to issue refunds from within WHMCS instead of logging in via PayPal.
- For more information refer to Automated Refunds
- Click Save Changes.
Sandbox Mode
You can use test mode to simulate payment processing without actually causing a transaction to occur. It does this by connecting to PayPal's sandbox environment. This can be useful to test your configuration.
- To use this, you must create a PayPal sandbox account.
- If your sandbox API credentials differ from your live account's, you must update them in your configuration and reset them when you finish testing.
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.
- Log in to your PayPal account.
- Click the settings icon (usually your name) at the top of your PayPal account page.
- Click Account Settings.
- Select Notifications on the left-hand menu.
- Click the Update link for the Instant Payment Notifications item.
- Click Choose IPN Settings (or Edit Settings if it is already enabled).
- Enter in your WHMCS System URL (e.g. https://www.example.com/whmcspath/).
- Select the Receive IPN messages (Enabled) option.
- Click Save.
Charset Configuration
PayPal defaults the charset used for most accounts to windows-1252. Whilst this is acceptable and will not cause an issue for most users, on occasion, accented characters can be returned incorrectly through the IPN causing the IPN Handshake Invalid message. Setting the charset in your PayPal account to match your WHMCS installation is a recommended setting to ensure this issue does not occur. The default value is UTF-8.
This is done via the Language Encoding page https://www.paypal.com/cgi-bin/customerprofileweb?cmd=_profile-language-encoding. Once here, click on More Options and choose your charset from the dropdown and ensure the radio option is set to Yes. Click on Save and your configuration is completed.
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 three 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, billable items or addons on their own won't create subscriptions)
- The 'Force One Time Payments' option is UNticked on the payment gateway configuration page.
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}
Automatic Subscription Management
If the Automatic Subscription Management feature is enabled on the installation, then WHMCS will attempt to automatically cancel PayPal subscriptions where applicable.
For details regarding the Automatic Subscription Management feature please refer to the Configuration section of the documentation.
Automated Refunds
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 Tools > All Tools > API credentials > NVP/SOAP API integration (Classic)
- Click Manage API Credentials - under the "NVP/SOAP API integration (Classic)" heading
- From there, you can generate a new set of credentials, view the current credentials, or remove them and create a new set
- 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.
Troubleshooting
Invalid Receiver Email
WHMCS validates the payment receiver email value against the details specified under Configuration () > System Settings > Payment Gateways or, prior to WHMCS 8.0, Setup > Payments > Payment Gateways, so this error means the two do not match. If multiple PayPal accounts are used to receive payment, or a single PayPal account has multiple email addresses associated with it ,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 Configuration () > System Settings > Currencies or, prior to WHMCS 8.0, 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.
IPN Handshake Invalid
Getting this message in your Gateway Log would mean that WHMCS is unable to verify that the callback occurring has come from PayPal. This is to stop any false payments being applied to your account, however, on occasion, some valid payments can generate this error. Follow the instructions above for setting the Charset of your IPN to stop this.
IPN Handshake Error
Getting this message in your Gateway Log indicates that whilst the IPN from PayPal was received, WHMCS was unable to verify the IPN data. The verification process involves connecting to PayPal's callback verification service at https://www.paypal.com/cgi-bin/webscr. This error will be observed if that connection fails. It can fail if the cURL connection made does not use the required protocols, transport Layer Security version 1.2 (TLS 1.2) and Hypertext Transfer Protocol version 1.1 (HTTP/1.1) are mandatory for communication with PayPal.
The WHMCS PayPal module does not specify a particular cryptographic protocol when communicating with PayPal. This means that cURL on your server should automatically negotiate the best protocol to use. Should you encounter the error above, it means your server is trying to negotiate a secure connection using one of the cryptographic protocols that PayPal no longer support. In that situation it would be necessary to work with your system administrator to ensure TLS 1.2 or greater is the default protocol on the server.
If the cURL test response is successful, it would be necessary to check a successful connection to PayPal's callback verification service at https://www.paypal.com/cgi-bin/webscr can be made.
This can again be checked using cURL from your servers command line, for example:
curl -I https://www.paypal.com/cgi-bin/webscrAny errors shown can again be referred to your server administrator to review and resolve.
Things don't appear to be working at the moment
Upon reaching the PayPal website, the error is displayed Things don't appear to be working at the moment. Please try again later.
This message indicates invalid details being sent to PayPal. It could be invalid client details (eg. address, postcode) or a misconfiguration in the WHMCS settings (eg. an invalid currency code - it should be a three letter ISO-4217 format from PayPal API's supported currency list).
Return to the client area invoice, view the page source and examine the PayPal payment button HTML code. Look for any variables which could be invalid. Then edit the client's profile or system settings to correct it.
If the currency_code value is not amongst PayPal API's supported currency list then the Convert to For Processing setting can be used to transparently convert the payment amounts into a currency which is supported by PayPal.
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