Difference between revisions of "PayPal Payments"
From WHMCS Documentation
(→Refresh Merchant Status) |
|||
| (8 intermediate revisions by one other user not shown) | |||
| Line 1: | Line 1: | ||
== About this Module == | == About this Module == | ||
| − | + | ||
<div class="docs-alert-success"> | <div class="docs-alert-success"> | ||
| − | + | We added this payment gateway in WHMCS 8.9 and '''strongly''' recommend it for '''all''' new PayPal® merchants. | |
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
</div> | </div> | ||
| − | + | <div class="docs-alert-warning">If you enabled this module while using the Beta release of WHMCS 8.9, you '''must''' reactivate the module before using it with WHMCS 8.9 Release Candidate or later. If you do not do this, you may experience problems with some payment methods.</div> | |
| − | When you use PayPal Payments, | + | |
| + | '''PayPal Payments''' uses PayPal’s latest secure tokenization system. It ensures the security of your customers’ stored payment details with merchant-level vaulting through PayPal Vault, now available for PayPal merchant accounts in [[#Vaulting|PayPal-supported countries]]. | ||
| + | |||
| + | When you use '''PayPal Payments''', clients can make one-click payments, including payment with credit and debit cards, during checkout and on invoices. Activating '''PayPal Payments''' also activates the '''[[PayPal Card Payments]]''' module, giving you the choice to display a separate unbranded option that accepts credit and debit cards using PayPal Advanced Checkout. | ||
{{gateways | {{gateways | ||
| + | | type = token | ||
| onetime = yes | | onetime = yes | ||
| recurring = yes | | recurring = yes | ||
| refunds = yes | | refunds = yes | ||
| + | | reversals = yes | ||
| + | | deletecc = yes | ||
| + | | 3dsecure = yes | ||
}} | }} | ||
| − | + | ||
| − | |||
| − | |||
| − | |||
| − | |||
== Adding the PayPal Payments Payment Gateway == | == Adding the PayPal Payments Payment Gateway == | ||
| − | + | ||
| − | To set up the PayPal Payments payment gateway in WHMCS: | + | To set up the '''PayPal Payments''' payment gateway in WHMCS: |
| − | + | ||
# Ensure that your WHMCS installation uses an HTTPS-secured connection with a valid [https://www.whmcs.com/ssl-certificates SSL certificate]. If it does not, this module will not function correctly. | # Ensure that your WHMCS installation uses an HTTPS-secured connection with a valid [https://www.whmcs.com/ssl-certificates SSL certificate]. If it does not, this module will not function correctly. | ||
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''. | # Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > Apps & Integrations''' or '''Addons > [[Apps and Integrations|Apps & Integrations]]'''. | ||
| − | # Click '''Activate & Configure''' for '''PayPal Payments'''. | + | # Choose the '''Payments''' category. |
| − | # Click '''Link PayPal Account'''. | + | # Click '''Activate & Configure''' for '''PayPal Payments'''.<div class="docs-alert-success">This will also activate '''[[PayPal Card Payments]]'''.</div> |
| − | # Log in to your | + | # Click '''Link PayPal Account''' to begin accepting payments with PayPal. <div class="docs-alert-info">To configure a PayPal Sandbox account for testing purposes, see [[#Test_Mode|Test Mode]] below.</div> |
| − | + | # Log in to your chosen PayPal account or sign up for a new one. API credentials will populate, WHMCS will save them automatically, and the page will refresh. | |
| − | + | # Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.<div class="docs-alert-info">You '''cannot''' disable '''Show on Order Form''' for '''PayPal Payments''' if '''Show on Order Form''' is enabled for '''[[PayPal Card Payments]]'''.</div> | |
| − | # Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.<div class="docs-alert-info">You '''cannot''' disable '''Show on Order Form''' for '''PayPal Payments''' if '''Show on Order Form''' is enabled for '''PayPal Card Payments'''.</div> | ||
# Optionally, enter a new display name for '''Display Name'''. | # Optionally, enter a new display name for '''Display Name'''. | ||
| − | #* By default, this module uses <tt> | + | #* By default, this module uses <tt>PayPal</tt> as the Client Area display name. |
| − | #* You will see the name that you enter here when you configure the payment gateway at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]'''. | + | #* You will see the name that you enter here when you configure the payment gateway at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]'''. |
| − | # | + | # Uncheck '''Test Mode'''. <div class="docs-alert-success">We enable '''[[#Test_Mode|Test Mode]]''' by default for this payment gateway.</div> |
| − | # | + | # Click '''Save Changes'''. |
| − | + | ||
| + | For a step-by-step walkthrough of the setup process, see [https://help.whmcs.com/m/payments/l/1782848-start-using-paypal-payments Start Using PayPal Payments]. | ||
| + | |||
=== Test Mode === | === Test Mode === | ||
| − | + | ||
| − | You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful for testing your configuration. Using test mode requires linking a separate PayPal | + | You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful for testing your configuration. Using test mode requires linking a separate PayPal Sandbox account to your WHMCS installation in addition to your live PayPal merchant account. |
| − | + | ||
To do this: | To do this: | ||
| − | + | ||
# Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]'''. | # Go to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > [[Payment Gateways]]'''. | ||
# Find the '''PayPal Payments''' module and click '''Link Sandbox Account'''. | # Find the '''PayPal Payments''' module and click '''Link Sandbox Account'''. | ||
| Line 52: | Line 51: | ||
# Confirm permission for the WHMCS application to access your account. | # Confirm permission for the WHMCS application to access your account. | ||
# Click '''Confirm''' to continue. API credentials will populate and WHMCS will save them automatically. | # Click '''Confirm''' to continue. API credentials will populate and WHMCS will save them automatically. | ||
| − | + | # Check '''Test Mode'''. | |
| + | # Click '''Save Changes'''. | ||
| + | |||
=== PayPal Card Payments === | === PayPal Card Payments === | ||
| − | + | ||
| − | PayPal | + | When you activate '''PayPal Payments''', WHMCS also automatically activates '''[[PayPal Card Payments]]'''. This module augments '''PayPal Payments''', allowing you an unbranded option for credit and debit card payments that is visually separate from the PayPal checkout experience. |
| − | + | ||
| − | This module uses the PayPal account settings that you configure for the '''PayPal Payments''' module | + | * This module uses the PayPal account settings that you configure for the '''PayPal Payments''' module. |
| − | + | * You '''cannot''' display the unbranded credit and debit card options that '''PayPal Card Payments''' offers on your order form without also displaying the PayPal option from the '''PayPal Payments''' module. | |
| − | * You | + | |
| − | |||
| − | |||
| − | |||
To set up the PayPal Card Payments payment gateway in WHMCS: | To set up the PayPal Card Payments payment gateway in WHMCS: | ||
| − | + | ||
# Activate and configure the '''PayPal Payments''' module (above). | # Activate and configure the '''PayPal Payments''' module (above). | ||
| − | + | # Find the '''PayPal Card Payments''' module in the list of active gateways. By default, this module uses <tt>Credit/Debit Cards</tt> as the display name here and in the Client Area. | |
| − | # Find the '''PayPal Card Payments''' module in the list of active gateways. By default, this module uses <tt> | ||
# Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.<div class="docs-alert-info">You cannot enable '''Show on Order Form''' for this module without first enabling '''Show on Order Form''' for the '''PayPal Payments''' module.</div> | # Check '''Show on Order Form''' to display this payment method in the Client Area during checkout.<div class="docs-alert-info">You cannot enable '''Show on Order Form''' for this module without first enabling '''Show on Order Form''' for the '''PayPal Payments''' module.</div> | ||
# Click '''Save Changes'''. | # Click '''Save Changes'''. | ||
| + | |||
| + | == Vaulting == | ||
| − | + | In PayPal-supported countries, the '''PayPal Payments''' and '''PayPal Card Payments''' modules ensure the security of your customers’ stored payment details with merchant-level vaulting through PayPal Vault. | |
| − | + | * When clients pay using '''PayPal Payments''', PayPal will attempt to store the pay method automatically. | |
| + | * When clients pay using '''PayPal Card Payments''', a '''Save card for faster checkout in future''' option will display while entering credit card details. | ||
| + | ** Selecting this option causes PayPal to attempt to add the card to PayPal Vault. | ||
| + | ** This option is '''not''' available in the Admin Area. | ||
| + | * Unlike previous PayPal payment gateways, this module stores encrypted vaulted data locally. | ||
| − | + | After PayPal successfully stores a payment method, it will be available for the client when they pay an invoice manually. | |
| + | |||
| + | <div class="docs-alert-info"> | ||
| + | If PayPal does not support PayPal Vault for your country or region, you can still use these payment gateways for one-time payments. However, your clients will '''not''' be able to store their payment method. | ||
| + | </div> | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
=== Supported Merchant Countries === | === Supported Merchant Countries === | ||
| − | + | ||
| − | PayPal currently enables | + | PayPal currently enables PayPal Vault for merchants in the United States, Canada, the United Kingdom, Australia, and the following EU countries: |
| − | + | ||
Belgium, Bulgaria, The Republic of Cyprus, Czech Republic, Germany, Denmark, Estonia, Spain, Finland, France, Greece, Hungary, Italy, Lithuania, Luxembourg, Latvia, Malta, Netherland, Poland, Portugal, Romania, Sweden, Slovenia, and Slovakia. | Belgium, Bulgaria, The Republic of Cyprus, Czech Republic, Germany, Denmark, Estonia, Spain, Finland, France, Greece, Hungary, Italy, Lithuania, Luxembourg, Latvia, Malta, Netherland, Poland, Portugal, Romania, Sweden, Slovenia, and Slovakia. | ||
| − | + | ||
== Unlink PayPal Account == | == Unlink PayPal Account == | ||
| − | + | ||
<div class="docs-alert-warning">Unlinking your account prevents WHMCS from interacting with PayPal.</div> | <div class="docs-alert-warning">Unlinking your account prevents WHMCS from interacting with PayPal.</div> | ||
| − | + | ||
Click '''Unlink PayPal Account''' to irreversibly remove the link to your PayPal account for both modules. | Click '''Unlink PayPal Account''' to irreversibly remove the link to your PayPal account for both modules. | ||
| − | + | ||
| − | == Refresh | + | == Refresh PayPal Account == |
| − | + | ||
| − | + | If a PayPal feature is unavailable or an error occurs, a '''Refresh PayPal Account''' option will display, allowing you to check your PayPal account’s status. You may wish to do this if, for example, you or PayPal have made changes to your merchant account. | |
| − | + | ||
| − | + | The system will check: | |
| − | + | ||
| + | * Whether you are able to receive payments to your linked PayPal accounts | ||
| + | * Whether you have verified your email address. | ||
| + | * Your access to PayPal features like PayPal Vault. | ||
| + | |||
| + | A checkmark in the displayed results indicates that you are in good standing and able to receive payments ('''Payments Receivable'''), your email is verified ('''Email Verified'''), or you can use a specific PayPal feature. | ||
| + | |||
| + | If the system detects problems, it instead displays a warning icon and, if applicable, logs the error to the '''Activity Log''' at '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Logs'''. | ||
== Disputes == | == Disputes == | ||
| − | + | ||
You can manage disputes for this module from within WHMCS at '''Billing > [[Disputes]]'''. | You can manage disputes for this module from within WHMCS at '''Billing > [[Disputes]]'''. | ||
| − | + | ||
== Payment Gateway Balances == | == Payment Gateway Balances == | ||
| − | + | ||
You can view your PayPal merchant account balance directly within the WHMCS Admin Area at '''Billing > [[Transactions]]'''. You can view balances in the transaction list and in the transaction details for individual transactions. | You can view your PayPal merchant account balance directly within the WHMCS Admin Area at '''Billing > [[Transactions]]'''. You can view balances in the transaction list and in the transaction details for individual transactions. | ||
| − | + | ||
== Troubleshooting == | == Troubleshooting == | ||
| − | + | ||
If your WHMCS installation’s URL has changed because you moved it, you must update the webhook URL in PayPal. | If your WHMCS installation’s URL has changed because you moved it, you must update the webhook URL in PayPal. | ||
| − | + | ||
| − | You can find information about most other payment gateway-related errors in the logs at '''Billing > Gateway Log'''. | + | You can find information about most other payment gateway-related errors in the logs at '''Billing > Gateway Log''' and in the '''Module Log'''. |
| − | + | ||
=== Updating the PayPal Webhook URL === | === Updating the PayPal Webhook URL === | ||
| − | + | ||
If your WHMCS installation's URL has changed because you moved it, you must update the webhook URL in PayPal. This will allow WHMCS to continue to record transactions. | If your WHMCS installation's URL has changed because you moved it, you must update the webhook URL in PayPal. This will allow WHMCS to continue to record transactions. | ||
| − | + | ||
To update the PayPal webhook URL: | To update the PayPal webhook URL: | ||
| − | + | ||
# Log in to [https://developer.paypal.com/developer/applications the PayPal developer portal]. | # Log in to [https://developer.paypal.com/developer/applications the PayPal developer portal]. | ||
# Click '''Live''', which will then display the WHMCS app. | # Click '''Live''', which will then display the WHMCS app. | ||
| Line 136: | Line 136: | ||
# Update '''Webhook URL''' to the correct address, ending with <tt>/modules/gateways/callback/paypal_ppcpv.php</tt>. | # Update '''Webhook URL''' to the correct address, ending with <tt>/modules/gateways/callback/paypal_ppcpv.php</tt>. | ||
# Click '''Save'''. | # Click '''Save'''. | ||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
| − | |||
Latest revision as of 14:00, 5 April 2024
Contents
About this Module
We added this payment gateway in WHMCS 8.9 and strongly recommend it for all new PayPal® merchants.
If you enabled this module while using the Beta release of WHMCS 8.9, you must reactivate the module before using it with WHMCS 8.9 Release Candidate or later. If you do not do this, you may experience problems with some payment methods.
PayPal Payments uses PayPal’s latest secure tokenization system. 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.
When you use PayPal Payments, clients can make one-click payments, including payment with credit and debit cards, during checkout and on invoices. Activating PayPal Payments also activates the PayPal Card Payments module, giving you the choice to display a separate unbranded option that accepts credit and debit cards using PayPal Advanced Checkout.
Supported Features
| Type | One Time | Recurring | Refunds | 3D Secure |
|---|---|---|---|---|
| Token | Yes | Yes | Yes | Yes |
| Remote Update Card | Remote Delete Card | AddPayMethod API |
|---|---|---|
| No | Yes | No |
Adding the PayPal Payments Payment Gateway
To set up the PayPal Payments payment gateway in WHMCS:
- Ensure that your WHMCS installation uses an HTTPS-secured connection with a valid SSL certificate. If it does not, this module will not function correctly.
- Go to Configuration () > Apps & Integrations or Addons > Apps & Integrations.
- Choose the Payments category.
- Click Activate & Configure for PayPal Payments.This will also activate PayPal Card Payments.
- Click Link PayPal Account to begin accepting payments with PayPal. To configure a PayPal Sandbox account for testing purposes, see Test Mode below.
- Log in to your chosen PayPal account or sign up for a new one. API credentials will populate, WHMCS will save them automatically, and the page will refresh.
- Check Show on Order Form to display this payment method in the Client Area during checkout.You cannot disable Show on Order Form for PayPal Payments if Show on Order Form is enabled for PayPal Card Payments.
- Optionally, enter a new display name for Display Name.
- By default, this module uses PayPal as the Client Area display name.
- You will see the name that you enter here when you configure the payment gateway at Configuration () > System Settings > Payment Gateways.
- Uncheck Test Mode. We enable Test Mode by default for this payment gateway.
- Click Save Changes.
For a step-by-step walkthrough of the setup process, see Start Using PayPal Payments.
Test Mode
You can use test mode to simulate payment processing without actually causing a transaction to occur. This can be useful for testing your configuration. Using test mode requires linking a separate PayPal Sandbox account to your WHMCS installation in addition to your live PayPal merchant account.
To do this:
- Go to Configuration () > System Settings > Payment Gateways.
- Find the PayPal Payments module and click Link Sandbox Account.
- Log in to your existing PayPal sandbox account or create a new PayPal sandbox account.
- Confirm permission for the WHMCS application to access your account.
- Click Confirm to continue. API credentials will populate and WHMCS will save them automatically.
- Check Test Mode.
- Click Save Changes.
PayPal Card Payments
When you activate PayPal Payments, WHMCS also automatically activates PayPal Card Payments. This module augments PayPal Payments, allowing you an unbranded option for credit and debit card payments that is visually separate from the PayPal checkout experience.
- This module uses the PayPal account settings that you configure for the PayPal Payments module.
- You cannot display the unbranded credit and debit card options that PayPal Card Payments offers on your order form without also displaying the PayPal option from the PayPal Payments module.
To set up the PayPal Card Payments payment gateway in WHMCS:
- Activate and configure the PayPal Payments module (above).
- Find the PayPal Card Payments module in the list of active gateways. By default, this module uses Credit/Debit Cards as the display name here and in the Client Area.
- Check Show on Order Form to display this payment method in the Client Area during checkout.You cannot enable Show on Order Form for this module without first enabling Show on Order Form for the PayPal Payments module.
- Click Save Changes.
Vaulting
In PayPal-supported countries, the PayPal Payments and PayPal Card Payments modules ensure the security of your customers’ stored payment details with merchant-level vaulting through PayPal Vault.
- When clients pay using PayPal Payments, PayPal will attempt to store the pay method automatically.
- When clients pay using PayPal Card Payments, a Save card for faster checkout in future option will display while entering credit card details.
- Selecting this option causes PayPal to attempt to add the card to PayPal Vault.
- This option is not available in the Admin Area.
- Unlike previous PayPal payment gateways, this module stores encrypted vaulted data locally.
After PayPal successfully stores a payment method, it will be available for the client when they pay an invoice manually.
If PayPal does not support PayPal Vault for your country or region, you can still use these payment gateways for one-time payments. However, your clients will not be able to store their payment method.
Supported Merchant Countries
PayPal currently enables PayPal Vault for merchants in the United States, Canada, the United Kingdom, Australia, and the following EU countries:
Belgium, Bulgaria, The Republic of Cyprus, Czech Republic, Germany, Denmark, Estonia, Spain, Finland, France, Greece, Hungary, Italy, Lithuania, Luxembourg, Latvia, Malta, Netherland, Poland, Portugal, Romania, Sweden, Slovenia, and Slovakia.
Unlink PayPal Account
Unlinking your account prevents WHMCS from interacting with PayPal.
Click Unlink PayPal Account to irreversibly remove the link to your PayPal account for both modules.
Refresh PayPal Account
If a PayPal feature is unavailable or an error occurs, a Refresh PayPal Account option will display, allowing you to check your PayPal account’s status. You may wish to do this if, for example, you or PayPal have made changes to your merchant account.
The system will check:
- Whether you are able to receive payments to your linked PayPal accounts
- Whether you have verified your email address.
- Your access to PayPal features like PayPal Vault.
A checkmark in the displayed results indicates that you are in good standing and able to receive payments (Payments Receivable), your email is verified (Email Verified), or you can use a specific PayPal feature.
If the system detects problems, it instead displays a warning icon and, if applicable, logs the error to the Activity Log at Configuration () > System Logs.
Disputes
You can manage disputes for this module from within WHMCS at Billing > Disputes.
Payment Gateway Balances
You can view your PayPal merchant account balance directly within the WHMCS Admin Area at Billing > Transactions. You can view balances in the transaction list and in the transaction details for individual transactions.
Troubleshooting
If your WHMCS installation’s URL has changed because you moved it, you must update the webhook URL in PayPal.
You can find information about most other payment gateway-related errors in the logs at Billing > Gateway Log and in the Module Log.
Updating the PayPal Webhook URL
If your WHMCS installation's URL has changed because you moved it, you must update the webhook URL in PayPal. This will allow WHMCS to continue to record transactions.
To update the PayPal webhook URL:
- Log in to the PayPal developer portal.
- Click Live, which will then display the WHMCS app.
- Click on the app name.
- Scroll to the Live Webhooks section and click the edit (pencil) icon.
- Update Webhook URL to the correct address, ending with /modules/gateways/callback/paypal_ppcpv.php.
- Click Save.