Difference between revisions of "PayPal Checkout"
(→Getting Started) |
(→Common Problems) |
||
| Line 69: | Line 69: | ||
This situation can arise if the ''Unlink PayPal Account'' button on the module configuration was used after the PayPal subscription was originally created. Once the unlink function is used, the subscription payments pre-dating 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. | This situation can arise if the ''Unlink PayPal Account'' button on the module configuration was used after the PayPal subscription was originally created. Once the unlink function is used, the subscription payments pre-dating 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'' will be displayed in the event that data in 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, the [[Troubleshooting_Module_Problems|Module Debug Log]] can be used. | ||
| + | #Examine the Request and Response data that is logged | ||
| + | #It should become apparent what data is missing or incomplete from the client's profile. For example: | ||
| + | '''Request:''' | ||
| + | <div class="source-cli"> | ||
| + | {"intent":"CAPTURE","purchase_units":[{"description":"Bronze Hosting - Invoice #123",<br/> | ||
| + | "amount":{"currency_code":"USD","value":"25.00"},"invoice_id":123}],"payer":{"name":<br/> | ||
| + | {"given_name":"WHMCS","surname":"Support"},"email_address":"email@example.com",<br/> | ||
| + | "address":{"address_line_1":"123 Test Street","postal_code":"ABC 123","country_code":""}}} | ||
| + | </div> | ||
| + | '''Response:''' | ||
| + | <div class="source-cli"> | ||
| + | {"name":"INVALID_REQUEST","message":"Request is not well-formed, syntactically incorrect,<br/> | ||
| + | or violates schema.","debug_id":"abc123","details":[{"field":"/payer/address/country_code",<br/> | ||
| + | "value":"","location":"body","issue":"INVALID_STRING_LENGTH","description":"<br/> | ||
| + | The value of a field is either too short or too long."}, | ||
| + | </div> | ||
| + | 4. In this case the Country Code value at the end of the Request is empty.<br/> | ||
| + | 5. To correct this, navigate to the client's '''Profile tab''' and ensure that a country is selected<br/> | ||
| + | 6. Then click ''Save Changes'' | ||
| + | |||
| + | If a Billing Contact is specified, make the change via the client's '''Contacts tab''' instead. | ||
Revision as of 12:34, 9 June 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 have One-Time payment items only will immediately see the Express Checkout buttons as described below. 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 checkout. Upon placing an order they will be redirected to PayPAl to create a subscription.
Express Checkout
With PayPal Checkout, users can elect to checkout using PayPal.
Clicking any of the checkout with PayPal buttons will launch a modal based payment authorization process.
Users will be asked to login to their PayPal account 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 within WHMCS will be displayed with their name, email and billing address prefilled to speed up the checkout process. For existing users, those not logged in will be presented with the login screen with their email address pre-filled to speed up sign-in.
Pictured below is the View Cart step of the order process, showing the PayPal Checkout options in addition to the default Checkout button.
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.
Getting Started
To activate and configure PayPal Checkout for use in WHMCS:
- Begin by logging in to the WHMCS admin area and navigating to Setup > Payment Gateways
- Click the Activate & Configure button in the PayPal section
- A popup will open and ask you to either login to your existing PayPal account or signup for a new one
- Upon logging in, you will be asked to confirm you give permission for the WHMCS application to access your account. Click Confirm to continue.
- API Credentials will be populated and saved in WHMCS 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
The Unlink PayPal Account button 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 servicing of 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.
- The Convert to for Processing option 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.
Common Problems
In the event a client pays an invoice and a completed payment is deposited into your PayPal account, but not recorded in WHMCS, begin troubleshooting by navigating to the Billing > Gateway Logs page. The explanation and resolution for common Results are itemised below:
Signature Verification Failed
A Signature Verification Failed Result 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 the notification originated from PayPal.
Seeing this Result typically indicates a subscription renewal payment was made through a different integration App to the one currently linked to your WHMCS installation.
This situation can arise if the Unlink PayPal Account button on the module configuration was used after the PayPal subscription was originally created. Once the unlink function is used, the subscription payments pre-dating 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 will be displayed in the event that data in 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, the Module Debug Log can be used.
- Examine the Request and Response data that is logged
- 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."},
4. In this case the Country Code value at the end of the Request is empty.
5. To correct this, navigate to the client's Profile tab and ensure that a country is selected
6. Then click Save Changes
If a Billing Contact is specified, make the change via the client's Contacts tab instead.