Difference between revisions of "PayPal"

From WHMCS Documentation

m (→‎Instant Payment Notification (IPN))
 
(46 intermediate revisions by 9 users not shown)
Line 1: Line 1:
−
{{gateways
+
According to PayPal® research, 49% of PayPal users abandon their purchases if PayPal isn’t a payment option. WHMCS’s supported payment gateway modules include several options for accepting payments through PayPal, helping you maximize your business and offer the options that your customers want most.
−
| onetime = yes
+
−
| recurring = yes
+
You can enable payment gateways, including the PayPal options below, at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > [[Apps_and_Integrations|Apps & Integrations]]''' (in WHMCS 8.6 and later) or '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]''' (in WHMCS 8.5 and earlier).
−
| refunds = yes
+
−
}}
+
== PayPal Gateway Comparison ==
−
 
+
−
[http://paypal.com PayPal] is one of the most popular and widely recognised online payment processors.
+
Each PayPal payment gateway includes features to help you accept and manage payments:
−
 
+
−
==Setup==
+
<table class="table table-striped table-condensed">
−
[[File:Videotutorial.png‎|center|link=http://www.youtube.com/watch?v=sJdqCuJXbRE|Watch Video Tutorial]]
+
    <tr>
−
 
+
      <th>Feature</th>
−
 
+
      <th>PayPal Payments</th>
−
Begin by activating the payment gateway under '''Setup > Payments > Payment Gateways''' and choose PayPal from the Available Gateways dropdown.
+
      <th>PayPal Card Payments</th>
−
 
+
      <th>PayPal Checkout</th>
−
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.
+
      <th>PayPal Basic</th>
−
 
+
      <th>PayPal Pro Reference Payments</th>
−
===PayPal Email===
+
      <th>PayPal Website Payments Pro</th>
−
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_Notification_.28IPN.29|Instant Payment Notifications]].
+
      <th>PayFlow Pro</th>
−
 
+
    </tr>
−
===Force One Time Payments===
+
    <tr>
−
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.
+
      <td>Recommended for New PayPal Merchants</td>
−
 
+
      <td>✓</td><td>✓</td><td>✖️</td><td>✖️</td><td>✖️</td><td>✖️</td><td>✖️</td>
−
===Force Subscriptions===
+
    </tr>
−
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 [[#PayPal_Subscriptions.2FRecurring_Billing|caveats explained below]].
+
    <tr>
−
 
+
      <td>Gateway Type</td>
−
===Require Shipping Address===
+
      <td>''Token''</td><td>''Token''</td><td>''Third-Party''</td><td>''Third-Party''</td><td>''Token''</td><td>''Merchant''</td><td>''Merchant''</td>
−
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.
+
    </tr>
−
 
+
    <tr>
−
===Client Address Matching===
+
      <td>One-Time<br/>Payments</td>
−
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.
+
      <td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td>
−
 
+
    </tr>
−
===API Fields===
+
    <tr>
−
Used for issuing refunds within WHMCS (saving the need to login at PayPal). For more information refer to [[#Automated_Refunds|Automated Refunds]]
+
      <td>Recurring<br/>Payments</td>
−
 
+
      <td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td>
−
 
+
    </tr>
−
==Instant Payment Notification (IPN)==
+
    <tr>
−
 
+
      <td>PayPal<br/>Subscriptions</td>
−
[[File:paypalipn2.png|thumb|PayPal IPN Setup]]
+
      <td>✖️</td><td>✖️</td><td>✓</td><td>✓</td><td>✖️</td><td>✖️</td><td>✖️</td>
−
 
+
    </tr>
−
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/
+
    <tr>
−
Then select the "Enabled" option.
+
      <td>Refunds</td>
−
 
+
      <td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td><td>✓</td>
−
===Charset Configuration===
+
    </tr>
−
 
+
    <tr>
−
[[File:paypalcharset.png|thumb|PayPal Charset Configuration]]
+
      <td>Reversals<br/>(in WHMCS)</td>
−
 
+
      <td>✓</td><td>✓</td><td>✖️</td><td>✓</td><td>✖️</td><td>✖️</td><td>✖️</td>
−
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.
+
    </tr>
−
This is done in '''My Account > Profile > My Selling Preferences > PayPal button language encoding '''(at the very bottom of the page). 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 complete.
+
    <tr>
−
 
+
      <td>Disputes<br/>(in WHMCS)</td>
−
==PayPal Subscriptions/Recurring Billing==
+
      <td>✓</td><td>✓</td><td>✓</td><td>✖️</td><td>✖️</td><td>✖️</td><td>✖️</td>
−
 
+
    </tr>
−
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.
+
    <tr>
−
 
+
      <td>3D Secure</td>
−
There are two conditions that must be met for the PayPal subscribe button to appear:
+
      <td>N/A</td><td>✓</td><td>✖️</td><td>✖️</td><td>✓</td><td>✓</td><td>✓</td>
−
 
+
    </tr>
−
# The invoice's Due Date must be in the future
+
    <tr>
−
# The invoice must contain at least 1 recurring product (ie. domains and billable items on their own won't create subscriptions)
+
      <td>View Balances<br/>(in WHMCS)</td>
−
 
+
      <td>✓</td><td>✓</td><td>✖️</td><td>✖️</td><td>✓</td><td>✓</td><td>✓</td>
−
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.
+
    </tr>
−
 
+
</table>
−
===Customising Invoice Emails for Subscriptions===
+
−
 
+
== Our PayPal Gateways ==
−
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.
+
−
 
+
We support the following PayPal payment gateways and ship them by default for all supported installations:
−
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:
+
−
 
+
=== PayPal Payments ===
−
  {if $invoice_subscription_id}
+
−
As you have a PayPal Subscription setup, payment will be taken automatically within the
+
<div class="docs-alert-info">
−
next few days. Please ensure you have enough funds in your PayPal account to cover it.
+
We '''strongly''' recommend the PayPal Payments module to all new PayPal merchants. For steps to activate and configure '''PayPal Payments''', see [https://help.whmcs.com/a/1782848 Start Using PayPal Payments].
−
{else}
+
</div>
−
You can login to your client area to view and pay the invoice at {$invoice_link}
+
−
{/if}
+
'''PayPal Payments''' uses PayPal’s latest secure tokenization system and lets your clients make payments with PayPal, including credit and debit card transactions. It ensures the security of your customers’ stored payment details with merchant-level vaulting through PayPal Vault, now available for PayPal merchant accounts in [[PayPal_Payments#Vaulting|PayPal-supported countries]]. It also supports [[Disputes|disputes]], and you can view your current merchant account balance at '''Billing > [[Transactions]]'''.
−
 
+
−
 
+
When you activate '''PayPal Payments''', the system also activates '''PayPal Card Payments''' (below). This module augments PayPal Payments, allowing you the option to visually separate the PayPal checkout experience from credit and debit card payments.
−
==Automated Refunds==
+
−
 
+
For more information, see [[PayPal Payments]].
−
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:
+
−
 
+
=== PayPal Card Payments ===
−
[[File:Pp_api1.png‎|thumb|PayPal Refunds Step 1]]
+
−
*Login to PayPal
+
'''PayPal Card Payments''' works with the '''PayPal Payments''' module to add an unbranded credit and debit card option that uses PayPal Advanced Checkout. When you activate '''PayPal Payments''', the system automatically activates '''PayPal Card Payments''' with it, with both modules using the account details that you configure for '''PayPal Payments'''.
−
*Go to Profile > My Selling Tools > API Access
+
−
*Choose '''Option 2''' - Request API credentials to create your own API username and password.
+
Display '''PayPal Card Payments''' on your Client Area order form to visually separate the PayPal checkout experience from credit and debit card payments. Like '''PayPal Payments''', '''PayPal Card Payments''' also supports [Disputes|disputes]], and you can view your current merchant account balance at '''Billing > [[Transactions]]'''.
−
*Choose '''Option 1''' - Request API Signature and click Agree and Submit
+
   
−
[[File:Pp_api2.png‎|thumb|PayPal Refunds Step 2]]
+
For more information, see [[PayPal Card Payments]].
−
*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
+
=== PayPal Checkout ===
−
 
+
−
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.
+
'''PayPal Checkout''' gives your customers a simplified and secure checkout experience, with the option to use '''Express Checkout''' to complete the transaction. '''Express Checkout''' appears automatically as a payment option for any product that uses a ''One-Time'', ''Biennial'', or ''Triennial'' billing cycle.
−
 
+
   
−
==Error Messages==
+
'''PayPal Checkout''' allows you to accept one-time and recurring payments through PayPal (including PayPal Subscriptions), process refunds, and handle [[Disputes|disputes]] from within WHMCS.
−
===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.
+
For more information, see [[PayPal Checkout]].
−
 
+
−
===Not Supported===
+
=== PayPal Basic ===
−
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.
+
−
 
+
'''PayPal Basic''' allows you to accept one-time and recurring payments through PayPal (including PayPal Subscriptions), process refunds, and handle payment reversals. In WHMCS 8.2 and later, you can view payment gateway balances for '''PayPal Basic''' at '''Billing > [[Transactions]]''' in the WHMCS Admin Area. This lets you check your financial details sooner and stay aware of trends and changes.
−
===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.
+
For more information, see [[PayPal Basic]].
−
 
+
−
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.
+
=== PayPal Pro Reference Payments ===
−
 
+
−
===IPN Handshake Invalid===
+
'''PayPal Pro Reference Payments''' allows you to store cards with a secure tokenization system for better PCI compliance. It can process one-time and recurring payments and send refunds.
−
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.
+
This module does '''not''' support adding or updating card data via the Admin Area. Instead, you can do this by paying an invoice on behalf of a client.
−
Follow the instructions above for setting the Charset of your IPN to stop this.
+
−
 
+
For more information, see [[Payflow_Pro|PayPal Pro Reference Payments]].
−
{{modules}}
+
 +
=== PayPal Website Payments Pro ===
 +
 +
'''PayPal Website Payments Pro''' allows you to accept one-time and recurring payments with locally-stored credit cards, process refunds, and handle payment reversals.
 +
 +
For more information, see [[PayPal Website Payments Pro]].
 +
 +
=== PayFlow Pro ===
 +
 +
'''Payflow Pro''' includes one-time and recurring payments with locally-stored credit cards and process refunds. You will need to enable the PayFlow Pro API in order to use this payment gateway.
 +
 +
For more information, see [[Payflow Pro]].

Latest revision as of 20:15, 22 March 2024

According to PayPal® research, 49% of PayPal users abandon their purchases if PayPal isn’t a payment option. WHMCS’s supported payment gateway modules include several options for accepting payments through PayPal, helping you maximize your business and offer the options that your customers want most.

You can enable payment gateways, including the PayPal options below, at Configuration () > Apps & Integrations (in WHMCS 8.6 and later) or Configuration () > System Settings > Payment Gateways (in WHMCS 8.5 and earlier).

PayPal Gateway Comparison

Each PayPal payment gateway includes features to help you accept and manage payments:

Feature PayPal Payments PayPal Card Payments PayPal Checkout PayPal Basic PayPal Pro Reference Payments PayPal Website Payments Pro PayFlow Pro
Recommended for New PayPal Merchants ✓✓✖️✖️✖️✖️✖️
Gateway Type TokenTokenThird-PartyThird-PartyTokenMerchantMerchant
One-Time
Payments		 ✓✓✓✓✓✓✓
Recurring
Payments		 ✓✓✓✓✓✓✓
PayPal
Subscriptions		 ✖️✖️✓✓✖️✖️✖️
Refunds ✓✓✓✓✓✓✓
Reversals
(in WHMCS)		 ✓✓✖️✓✖️✖️✖️
Disputes
(in WHMCS)		 ✓✓✓✖️✖️✖️✖️
3D Secure N/A✓✖️✖️✓✓✓
View Balances
(in WHMCS)		 ✓✓✖️✖️✓✓✓

Our PayPal Gateways

We support the following PayPal payment gateways and ship them by default for all supported installations:

PayPal Payments

We strongly recommend the PayPal Payments module to all new PayPal merchants. For steps to activate and configure PayPal Payments, see Start Using PayPal Payments.

PayPal Payments uses PayPal’s latest secure tokenization system and lets your clients make payments with PayPal, including credit and debit card transactions. It ensures the security of your customers’ stored payment details with merchant-level vaulting through PayPal Vault, now available for PayPal merchant accounts in PayPal-supported countries. It also supports disputes, and you can view your current merchant account balance at Billing > Transactions.

When you activate PayPal Payments, the system also activates PayPal Card Payments (below). This module augments PayPal Payments, allowing you the option to visually separate the PayPal checkout experience from credit and debit card payments.

For more information, see PayPal Payments.

PayPal Card Payments

PayPal Card Payments works with the PayPal Payments module to add an unbranded credit and debit card option that uses PayPal Advanced Checkout. When you activate PayPal Payments, the system automatically activates PayPal Card Payments with it, with both modules using the account details that you configure for PayPal Payments.

Display PayPal Card Payments on your Client Area order form to visually separate the PayPal checkout experience from credit and debit card payments. Like PayPal Payments, PayPal Card Payments also supports [Disputes|disputes]], and you can view your current merchant account balance at Billing > Transactions.

For more information, see PayPal Card Payments.

PayPal Checkout

PayPal Checkout gives your customers a simplified and secure checkout experience, with the option to use Express Checkout to complete the transaction. Express Checkout appears automatically as a payment option for any product that uses a One-Time, Biennial, or Triennial billing cycle.

PayPal Checkout allows you to accept one-time and recurring payments through PayPal (including PayPal Subscriptions), process refunds, and handle disputes from within WHMCS.

For more information, see PayPal Checkout.

PayPal Basic

PayPal Basic allows you to accept one-time and recurring payments through PayPal (including PayPal Subscriptions), process refunds, and handle payment reversals. In WHMCS 8.2 and later, you can view payment gateway balances for PayPal Basic at Billing > Transactions in the WHMCS Admin Area. This lets you check your financial details sooner and stay aware of trends and changes.

For more information, see PayPal Basic.

PayPal Pro Reference Payments

PayPal Pro Reference Payments allows you to store cards with a secure tokenization system for better PCI compliance. It can process one-time and recurring payments and send refunds.

This module does not support adding or updating card data via the Admin Area. Instead, you can do this by paying an invoice on behalf of a client.

For more information, see PayPal Pro Reference Payments.

PayPal Website Payments Pro

PayPal Website Payments Pro allows you to accept one-time and recurring payments with locally-stored credit cards, process refunds, and handle payment reversals.

For more information, see PayPal Website Payments Pro.

PayFlow Pro

Payflow Pro includes one-time and recurring payments with locally-stored credit cards and process refunds. You will need to enable the PayFlow Pro API in order to use this payment gateway.

For more information, see Payflow Pro.

Retrieved from "http://3.17.75.209/index.php?title=PayPal&oldid=34499"