Difference between revisions of "PayPal Checkout"
m (→Supported Payment Types) |
|||
| Line 1: | Line 1: | ||
| − | <div class="docs-alert-info"><i class="fa fa-info-circle"></i> PayPal Checkout is a new PayPal module available in WHMCS 7.9 and later.</div> | + | <div class="docs-alert-info"><i class="fa fa-info-circle"></i>PayPal Checkout is a new PayPal module that's available in WHMCS 7.9 and later.</div> |
| − | + | ||
| − | The latest PayPal module leverages PayPal Checkout and PayPal's Smart Button technology which PayPal describes as follows: | + | The latest PayPal module leverages PayPal Checkout and PayPal's Smart Button technology, which PayPal describes as follows: |
| − | + | ||
| − | + | PayPal Checkout with Smart Payment Buttons gives your buyers a simplified and secure checkout experience. PayPal intelligently presents the most relevant payment types to your shoppers, automatically, making it easier for them to complete their purchase using methods like Pay with Venmo, PayPal Credit, credit card payments, iDEAL, Bancontact, Sofort, and other payment types." | |
| − | + | ||
==Supported Payment Types== | ==Supported Payment Types== | ||
| − | + | ||
* One-Time Payments | * One-Time Payments | ||
* Subscriptions | * Subscriptions | ||
| − | + | ||
| − | Carts that have '''One-Time | + | Carts that only have '''One-Time Payment''' items will immediately include '''Express Checkout''' buttons. For carts that contain at least one recurring item, the client can proceed through the standard WHMCS checkout routine and select ''PayPal'' as the payment method. Upon placing an order, they will be redirected to PayPal to create a subscription. |
| − | + | ||
==Express Checkout== | ==Express Checkout== | ||
| − | + | ||
| − | With PayPal Checkout, users can elect to | + | With PayPal Checkout, users can elect to check out using PayPal. |
| − | + | ||
| − | Clicking any | + | Clicking any '''Checkout with PayPal''' button will launch a modal-based payment authorization process. |
| − | + | ||
| − | Users will be asked to | + | Users will be asked to log in to their PayPal accounts and confirm they approve payment before being returned to the WHMCS shopping cart to complete the checkout process. |
| − | + | ||
| − | For new customers who are placing an order for the first time, upon completing the PayPal | + | For new customers who are placing an order for the first time, upon completing the PayPal Checkout workflow, the registration form will pre-fill the name, email and billing address to speed up the checkout process. For existing users, those who are not logged in will see the login screen with their email address pre-filled. |
| − | + | ||
| − | + | Below is the '''View Cart''' step of the order process, showing the PayPal Checkout options in addition to the default '''Checkout''': | |
| − | + | ||
[[File:Paypal-checkout-cart-buttons.png]] | [[File:Paypal-checkout-cart-buttons.png]] | ||
| − | + | ||
Users who elect to use the express checkout options of PayPal Checkout will not see a payment method choice during checkout post authorization of payment by PayPal. They will instead see a message indicating they have pre-approved payment with PayPal. | Users who elect to use the express checkout options of PayPal Checkout will not see a payment method choice during checkout post authorization of payment by PayPal. They will instead see a message indicating they have pre-approved payment with PayPal. | ||
| − | + | ||
==SSL Requirement== | ==SSL Requirement== | ||
| − | PayPal Checkout requires an HTTPS secured connection to create the link between WHMCS and PayPal correctly. | + | |
| − | + | PayPal Checkout requires an HTTPS secured connection to create the link between WHMCS and PayPal correctly. If the your WHMCS installation's domain does not have a valid SSL certificate, the payment return will not work. | |
| − | To update your | + | |
| − | + | To update your system URL to <tt>https</tt>, navigate to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > General Settings''' and update the '''WHMCS System URL''' setting to ''https://'' accordingly. | |
| − | If you need to purchase an SSL | + | |
| − | + | If you need to purchase an SSL certificate, you can do so [https://www.whmcs.com/ssl-certificates www.whmcs.com/ssl-certificates here]. | |
| + | |||
==Getting Started== | ==Getting Started== | ||
| − | + | ||
| + | [[File:Paypal activate.png|thumb|PayPal Activate & Configure]][[File:Paypal activate2.png|thumb|PayPal Configuration Complete]] | ||
| + | |||
To activate and configure PayPal Checkout for use in WHMCS: | To activate and configure PayPal Checkout for use in WHMCS: | ||
| − | + | * Log in to the WHMCS admin area and navigate to '''Configuration (<i class="fa fa-wrench" aria-hidden="true"></i>) > System Settings > Payment Gateways'''. | |
| − | * | + | * Click '''Activate & Configure''' in the PayPal section. |
| − | * Click | + | * When the system prompts you, log in to your existing PayPal account or sign up for a new one. |
| − | * | + | * When the system prompts you, confirm permission for the WHMCS application to access your account. Click '''Confirm''' to continue. |
| − | * | + | |
| − | + | API credentials will populate and WHMCS will save them automatically. The page will refresh and, once you see the green success notification, you have completed the setup process. | |
| − | + | ||
You can now begin using the PayPal Checkout module. | You can now begin using the PayPal Checkout module. | ||
| − | + | ||
<div class="docs-alert-danger"> | <div class="docs-alert-danger"> | ||
<span class="title">Unlink PayPal Account</span><br /> | <span class="title">Unlink PayPal Account</span><br /> | ||
| − | + | '''Unlink PayPal Account''' will irreversibly remove the link to your PayPal account. Subscription payments will no longer be recorded in WHMCS. Do '''not''' use this option if there are PayPal subscriptions you wish to keep. | |
</div> | </div> | ||
<div class="docs-alert-info"> | <div class="docs-alert-info"> | ||
<span class="title">Migrating from PayPal Basic?</span><br /> | <span class="title">Migrating from PayPal Basic?</span><br /> | ||
| − | Refer to to the [[PayPal_Checkout_Migration_Guide|PayPal Checkout Migration Guide]] for uninterrupted | + | Refer to to the [[PayPal_Checkout_Migration_Guide|PayPal Checkout Migration Guide]] for uninterrupted service for legacy subscriptions. |
</div> | </div> | ||
| − | + | ||
==Limitations/Restrictions== | ==Limitations/Restrictions== | ||
| − | + | ||
The following limitations and restrictions apply to PayPal Checkout: | The following limitations and restrictions apply to PayPal Checkout: | ||
| − | + | ||
* Users who choose to use one of the PayPal Checkout express checkout options within the view cart step of the shopping cart workflow will not be asked to select a payment gateway in the checkout step. | * Users who choose to use one of the PayPal Checkout express checkout options within the view cart step of the shopping cart workflow will not be asked to select a payment gateway in the checkout step. | ||
* The option to apply credit during checkout for existing customers who have a credit balance is not displayed during express checkout to avoid conflicts with the pre-authorized amount at PayPal. | * The option to apply credit during checkout for existing customers who have a credit balance is not displayed during express checkout to avoid conflicts with the pre-authorized amount at PayPal. | ||
* MarketConnect Upsells will not be displayed after payment has been pre-authorized with PayPal to avoid changes being made to the cart total after authorization of the payment amount with PayPal. | * MarketConnect Upsells will not be displayed after payment has been pre-authorized with PayPal to avoid changes being made to the cart total after authorization of the payment amount with PayPal. | ||
| − | * | + | * '''Convert to for Processing''' is not offered in the module configuration. Payments will be made in the client's selected currency. |
| − | * Clients will be offered the subscription option if ordering a recurring product. An option to force only one-time payments is not offered in the module configuration. | + | * Clients will be offered the subscription option if they are ordering a recurring product. An option to force only one-time payments is not offered in the module configuration. |
| − | + | ||
==Common Problems== | ==Common Problems== | ||
| − | + | If a client pays an invoice and a completed payment is deposited into your PayPal account, but not recorded in WHMCS, you can troubleshoot this by navigating to '''Billing > Gateway Logs'''. | |
| − | The | + | |
| − | + | The explanations and resolutions for common problems are listed below: | |
| + | |||
===Signature Verification Failed=== | ===Signature Verification Failed=== | ||
| − | + | ||
| − | + | ''Signature Verification Failed'' indicates a problem in the payment notification anti-spoof verification. When a payment notification is received from PayPal, WHMCS makes an API request to PayPal confirming that the notification originated from PayPal. | |
| − | Seeing this | + | |
| − | + | Seeing this typically indicates that a subscription renewal payment was made through a different [https://developer.paypal.com/docs/integration/admin/manage-apps/# integration app] from the one currently linked to your WHMCS installation. | |
| − | This situation can arise if | + | |
| − | + | This situation can arise if '''Unlink PayPal Account''' on the module configuration was used after the PayPal subscription was originally created. Once the unlink function is used, the subscription payments that pre-date it can no longer be recorded in WHMCS. Such subscriptions will need to be cancelled via the PayPal website. Clients can then create a new subscription under the current integration app linked to your WHMCS installation when their next invoice is due. | |
| + | |||
===An unknown error occurred. Please try again=== | ===An unknown error occurred. Please try again=== | ||
| − | + | ||
| − | + | ''unknown error occurred'' will be displayed if data saved by the PayPal payment button is invalid, such as the amount, client's name, email address, postal address, postal code, or country code. | |
| − | + | ||
| − | + | To capture more details, use the [[Troubleshooting_Module_Problems|Module Debug Log]]. Examine the logged request and response data. It should become apparent what data is missing or incomplete from the client's profile. For example: | |
| − | + | ||
'''Request:''' | '''Request:''' | ||
<div class="source-cli"> | <div class="source-cli"> | ||
| Line 90: | Line 95: | ||
"address":{"address_line_1":"123 Test Street","postal_code":"ABC 123","country_code":""}}} | "address":{"address_line_1":"123 Test Street","postal_code":"ABC 123","country_code":""}}} | ||
</div> | </div> | ||
| + | |||
'''Response:''' | '''Response:''' | ||
<div class="source-cli"> | <div class="source-cli"> | ||
| Line 97: | Line 103: | ||
The value of a field is either too short or too long."}, | The value of a field is either too short or too long."}, | ||
</div> | </div> | ||
| − | + | ||
| − | + | In this case, the '''Country Code''' at the end of the request is empty. To correct this, go to '''Profile''' for the client and ensure that a country is selected. Then, click '''Save Changes'''. | |
| − | + | ||
| − | + | If a '''Billing Contact''' is specified, make the change via '''Contacts''' instead. | |
| − | If a Billing Contact is specified, make the change via | ||
Revision as of 12:38, 4 August 2020
The latest PayPal module leverages PayPal Checkout and PayPal's Smart Button technology, which PayPal describes as follows:
PayPal Checkout with Smart Payment Buttons gives your buyers a simplified and secure checkout experience. PayPal intelligently presents the most relevant payment types to your shoppers, automatically, making it easier for them to complete their purchase using methods like Pay with Venmo, PayPal Credit, credit card payments, iDEAL, Bancontact, Sofort, and other payment types."
Contents
Supported Payment Types
- One-Time Payments
- Subscriptions
Carts that only have One-Time Payment items will immediately include Express Checkout buttons. For carts that contain at least one recurring item, the client can proceed through the standard WHMCS checkout routine and select PayPal as the payment method. Upon placing an order, they will be redirected to PayPal to create a subscription.
Express Checkout
With PayPal Checkout, users can elect to check out using PayPal.
Clicking any Checkout with PayPal button will launch a modal-based payment authorization process.
Users will be asked to log in to their PayPal accounts and confirm they approve payment before being returned to the WHMCS shopping cart to complete the checkout process.
For new customers who are placing an order for the first time, upon completing the PayPal Checkout workflow, the registration form will pre-fill the name, email and billing address to speed up the checkout process. For existing users, those who are not logged in will see the login screen with their email address pre-filled.
Below is the View Cart step of the order process, showing the PayPal Checkout options in addition to the default Checkout:
Users who elect to use the express checkout options of PayPal Checkout will not see a payment method choice during checkout post authorization of payment by PayPal. They will instead see a message indicating they have pre-approved payment with PayPal.
SSL Requirement
PayPal Checkout requires an HTTPS secured connection to create the link between WHMCS and PayPal correctly. If the your WHMCS installation's domain does not have a valid SSL certificate, the payment return will not work.
To update your system URL to https, navigate to Configuration () > System Settings > General Settings and update the WHMCS System URL setting to https:// accordingly.
If you need to purchase an SSL certificate, you can do so www.whmcs.com/ssl-certificates here.
Getting Started
To activate and configure PayPal Checkout for use in WHMCS:
- Log in to the WHMCS admin area and navigate to Configuration () > System Settings > Payment Gateways.
- Click Activate & Configure in the PayPal section.
- When the system prompts you, log in to your existing PayPal account or sign up for a new one.
- When the system prompts you, confirm permission for the WHMCS application to access your account. Click Confirm to continue.
API credentials will populate and WHMCS will save them automatically. The page will refresh and, once you see the green success notification, you have completed the setup process.
You can now begin using the PayPal Checkout module.
Unlink PayPal Account
Unlink PayPal Account will irreversibly remove the link to your PayPal account. Subscription payments will no longer be recorded in WHMCS. Do not use this option if there are PayPal subscriptions you wish to keep.
Migrating from PayPal Basic?
Refer to to the PayPal Checkout Migration Guide for uninterrupted service for legacy subscriptions.
Limitations/Restrictions
The following limitations and restrictions apply to PayPal Checkout:
- Users who choose to use one of the PayPal Checkout express checkout options within the view cart step of the shopping cart workflow will not be asked to select a payment gateway in the checkout step.
- The option to apply credit during checkout for existing customers who have a credit balance is not displayed during express checkout to avoid conflicts with the pre-authorized amount at PayPal.
- MarketConnect Upsells will not be displayed after payment has been pre-authorized with PayPal to avoid changes being made to the cart total after authorization of the payment amount with PayPal.
- Convert to for Processing is not offered in the module configuration. Payments will be made in the client's selected currency.
- Clients will be offered the subscription option if they are ordering a recurring product. An option to force only one-time payments is not offered in the module configuration.
Common Problems
If a client pays an invoice and a completed payment is deposited into your PayPal account, but not recorded in WHMCS, you can troubleshoot this by navigating to Billing > Gateway Logs.
The explanations and resolutions for common problems are listed below:
Signature Verification Failed
Signature Verification Failed indicates a problem in the payment notification anti-spoof verification. When a payment notification is received from PayPal, WHMCS makes an API request to PayPal confirming that the notification originated from PayPal.
Seeing this typically indicates that a subscription renewal payment was made through a different integration app from the one currently linked to your WHMCS installation.
This situation can arise if Unlink PayPal Account on the module configuration was used after the PayPal subscription was originally created. Once the unlink function is used, the subscription payments that pre-date it can no longer be recorded in WHMCS. Such subscriptions will need to be cancelled via the PayPal website. Clients can then create a new subscription under the current integration app linked to your WHMCS installation when their next invoice is due.
An unknown error occurred. Please try again
unknown error occurred will be displayed if data saved by the PayPal payment button is invalid, such as the amount, client's name, email address, postal address, postal code, or country code.
To capture more details, use the Module Debug Log. Examine the logged request and response data. It should become apparent what data is missing or incomplete from the client's profile. For example:
Request:
{"intent":"CAPTURE","purchase_units":[{"description":"Bronze Hosting - Invoice #123",
"amount":{"currency_code":"USD","value":"25.00"},"invoice_id":123}],"payer":{"name":
{"given_name":"WHMCS","surname":"Support"},"email_address":"email@example.com",
"address":{"address_line_1":"123 Test Street","postal_code":"ABC 123","country_code":""}}}
Response:
{"name":"INVALID_REQUEST","message":"Request is not well-formed, syntactically incorrect,
or violates schema.","debug_id":"abc123","details":[{"field":"/payer/address/country_code",
"value":"","location":"body","issue":"INVALID_STRING_LENGTH","description":"
The value of a field is either too short or too long."},
In this case, the Country Code at the end of the request is empty. To correct this, go to Profile for the client and ensure that a country is selected. Then, click Save Changes.
If a Billing Contact is specified, make the change via Contacts instead.