To unlock your live system, generate new credentials.
To do this, go through the PayPal registration process again with your PayPal merchant account details.
Administering existing PayPal or PayPal Plus orders
If you already use the PayPal or PayPal Plus module, note the following limitation:
To administer existing orders, both modules, PayPal Checkout and PayPal for example, must be active at the same time.
However, to prevent that, in our example, the PayPal payment method redundantly displayed in the frontend, you must deactivate the payment methodPayPal.
Procedure
We recommend the following procedure.
Tip
Scheduling a downtime
Schedule a short downtime for the step of deactivating the payment method belonging to PayPal or PayPal Plus.
Install PayPal Checkout.
Activate and configure PayPal Checkout as described below under Basic procedure.
Result: To administer your orders, under Administer Orders ‣ Orders you find separate tabs for PayPal Checkout and for PayPal or PayPal Plus (depending on which of the two modules you use).
Note
Administering orders in the PayPal merchant account
Nothing can go wrong if you disable PayPal or PayPal Plus as described below.
You can administer orders in your PayPal merchant account at any time.
Technical dependencies
On the separate tab for PayPal or PayPal Plus you can edit your old orders until you deactivate your previously used module.
Once you deactivate your previously used module, you can still view your old orders on the PayPal Checkout tab, but not edit them.
If you clean up your system after deactivating your previously used module and therefore also delete the module’s database, your old orders will also no longer be displayed on the PayPal Checkout tab.
After deleting the database, you will still be able to view and administer the old orders in your PayPal merchant account.
Identify the payment methods corresponding to PayPal or PayPal Plus:
PayPal (ID: oxidpaypal)
PayPal Plus (ID: payppaypalplus)
Hint
The ID is displayed in the lower left corner of the window when you hover over the payment type name.
Disable the payment type corresponding to PayPal or PayPal Plus.
To do this, on the Main tab, uncheck the Active checkbox.
Result: The PayPal or PayPal Plus module is still active, but the associated payment methods are no longer offered to your customers. Only the payment methods of PayPal Checkout are offered.
You can still edit existing orders as usual under Administer Orders ‣ Orders on the tab corresponding to the payment module.
Recommended: As soon as you are sure that existing orders will no longer require any actions (refunds, for example), under Extensions ‣ Modules disable PayPal or PayPal Plus.
Operating PayPal Checkout in subshops with the OXID eShop Enterprise Edition
You have the OXID eShop Enterprise Edition and run subshops for different countries?
In this case, note the order of the subshops for which you connect to PayPal (onboarding).
Background
For technical reasons restrictions of the onboarding in the first subshop apply to the onboarding in all further subshops.
Example
You have both a German and a Swiss PayPal merchant account.
You perform the onboarding first for your Swiss subshop with your Swiss PayPal merchant account.
This makes the PayPal Checkout payment methods available to you that PayPal offers worldwide (see Market coverage by country).
Then you perform the onboarding for your German subshop using your German PayPal merchant account.
In this case, the PayPal Checkout payment method Pay upon Invoice will not be available for your German subshop.
Reason: You can only offer the PayPal Checkout payment method Pay upon Invoice if you have a German PayPal merchant account.
You only have a German PayPal merchant account.
You perform the onboarding first for your German subshop and then for your Swiss subshop.
During onboarding, it appears that the PayPal Checkout payment method Pay upon Invoice is also available for your Swiss subshop.
But this is not the case. Your customers with a Swiss billing address will not be offered Pay upon Invoice.
Procedure
Proceed as follows:
You have a German PayPal merchant account?
Perform the onboarding for your German subshop first even if you have a non-German main store.
This will ensure that PayPal will also enable those PayPal Checkout payment methods for your German subshop that are not available for non-German PayPal merchant accounts.
You only have a non-German PayPal merchant account?
Perform the onboarding for your subshops.
For each subshop, check how important the restriction of PayPal Checkout payment methods for non-German PayPal merchant accounts is for you in that particular market.
If the restriction is critical for your business model, contact PayPal support to get an activation for the required PayPal Checkout payment method.
Activate the module.
The most important payment methods are automatically activated.
Go through the registration process with PayPal (onboarding).
Optional: Disable the express checkout feature of PayPal Checkout if needed.
If necessary, contact PayPal Customer Service to determine the best way for PayPal to handle 3D Secure authentication in your case (see Fig.: Configuring 3D Secure authentication).
Configure the payment methods provided by PayPal Checkout as payment methods in your eShop:
Enable the countries you want to cover.
Link the payment methods to your shipping methods and shipping rules.
Run test payments in the PayPal Checkout sandbox. and adjust the configuration until all payment processes works as you want.
Enable PayPal Checkout:
If you do not have a merchant account yet, create one for live operation.
Switch to Live operation mode.
If required: If you have particularly privacy-sensitive customers, implement a consent procedure, for example with Usercentrics.
Go through the registration process with PayPal (onboarding).
You use it to create access data (client ID and password), activate functions (e.g. payment methods or new functions such as PayPal Vaulting) and generate a webhook.
The webhook allows PayPal to contact your OXID eShop and provide real-time status messages, for example about completed transactions.
In the first step, you test the payment methods provided with PayPal Checkout with test access data in a sandbox.
Tip
To debug, let the shop track the incoming webhooks.
sandbox.paypal.com is a mirror system.
All functions and the API are identical to sandbox.paypal.com.
This means that any error you can create here will also exist in the live system.
Conversely, any error not generated will not occur in the production system either.
Therefore, test your PayPal Checkout integration with a sandbox system first.
Nothing can go wrong:
Test payments in the sandbox cost nothing.
You avoid chargebacks as they would be necessary with test payments with the live account.
Only when everything works as you want, use the credentials for live operation.
Prerequisites
On PayPal’s developer page, you have created a sandbox merchant account and a sandbox customer account.
For more information, see Generating PayPal sandbox accounts.
Your test environment has SSL.
If you are testing PayPal Checkout in a local development environment that is only accessible via http:// (i.e. without SSL via https://), then use, for example, NGROK to provide your test environment with temporary SSL.
For more information, see Setting up temporary SSL.
If you want to offer Google Pay, for test payments you have
a Google account
a credit card
If you make payments with your credit card in sandbox mode, your credit card will not be charged. Google will replace your real credit card number with a sample credit card number.
We describe the registration process (onboarding) using a sandbox account as an example. The live process is analogous.
Attention
Operating PayPal Checkout in subshops with the OXID eShop Enterprise Edition
You have the OXID eShop Enterprise Edition and run subshops for different countries?
In this case, note the order of the subshops for which you connect to PayPal (onboarding).
Background
For technical reasons restrictions of the onboarding in the first subshop apply to the onboarding in all further subshops.
Example
You have both a German and a Swiss PayPal merchant account.
You perform the onboarding first for your Swiss subshop with your Swiss PayPal merchant account.
This makes the PayPal Checkout payment methods available to you that PayPal offers worldwide (see Market coverage by country).
Then you perform the onboarding for your German subshop using your German PayPal merchant account.
In this case, the PayPal Checkout payment method Pay upon Invoice will not be available for your German subshop.
Reason: You can only offer the PayPal Checkout payment method Pay upon Invoice if you have a German PayPal merchant account.
You only have a German PayPal merchant account.
You perform the onboarding first for your German subshop and then for your Swiss subshop.
During onboarding, it appears that the PayPal Checkout payment method Pay upon Invoice is also available for your Swiss subshop.
But this is not the case. Your customers with a Swiss billing address will not be offered Pay upon Invoice.
Procedure
Proceed as follows:
You have a German PayPal merchant account?
Perform the onboarding for your German subshop first even if you have a non-German main store.
This will ensure that PayPal will also enable those PayPal Checkout payment methods for your German subshop that are not available for non-German PayPal merchant accounts.
You only have a non-German PayPal merchant account?
Perform the onboarding for your subshops.
For each subshop, check how important the restriction of PayPal Checkout payment methods for non-German PayPal merchant accounts is for you in that particular market.
If the restriction is critical for your business model, contact PayPal support to get an activation for the required PayPal Checkout payment method.
Attention
Reusing access data and webhook
In any case, make sure that all PayPal payment methods and functions are available to you.
Case 1: You have PayPal or PayPal Plus? – Go through the registration process again to regenerate access data and webhook to connect to PayPal Checkout.
Case 2: You have an earlier version of PayPal Checkout and are updating? – Go through the registration process again.
Otherwise, the payment methods and functions of the newer version of PayPal Checkout will not be available to you.
Case 3: You have already completed the registration process for the current version of PayPal Checkout and are moving your OXID eShop to another domain, for example? – In this case, you can reuse the access data and webhook.
If you want to use the payment methods Pay upon Invoice or credit card, under Activation for special payment methods has taken place (Fig.: Client ID/secret and webhook ID created, item 5), check whether the activation has been done.
Hint
Payment method fallback credit card.
If the activation did not happen automatically (credit card: No), contact your PayPal representative.
PayPal offers the payment method Purchase upon invoice only to store operators from Germany.
Result
Once you have given PayPal permission to connect your sandbox account to the PayPal test store, the API credentials are displayed, and the module is active (Fig.: Client ID/secret and webhook ID created, item 1).
Under Shop Settings ‣ Payment Methods, the payment method PayPal (technical name oscpaypal) is active (Fig.: Payment method PayPal active).
The payment methods “Credit card” and “Purchase upon invoice” are not available? Follow the instructions under troubleshooting:”Credit card” and “Purchase upon invoice” not available.
Hint
Generating a new webhook
Sometimes it may be necessary to delete the existing webhook and generate a new one.
Do the following:
To delete the webhook, delete the login data and choose Save.
To go through the registration process again and regenerate access data and webhook, chose the Signup Merchant Integration button.
Hint
Identifying issues with the connection to PayPal
If, for example, you experience connection problems, or payment transactions do not work as expected, switch on the debug mode and contact PayPal support.
Specify the domain name (the URL without the schema, e.g. https://) of your OXID e-shop (www.my-oxid-eshop.com, for example) (Fig.: Registering the domain name, item 1).
The system generates a domain association file which you use to proves that you are the owner of the website.
It is automatically saved in the root directory of your OXID eShop. The manual download and hosting of the file (Fig.: Registering the domain name, item 2) is therefore normally not necessary.
Optional: To check whether the domain association file is available, open the file via browser.
Decide if you want to offer the quick purchase feature of PayPal Checkout.
With the quick purchase feature, your customers skip logging into your eShop.
Example
Your customers typically have only one item in their shopping cart when they place an order?
In this case it makes sense to guide customers to their destination as quickly and barrier-free as possible and activate the quick purchase function.
Do you generate a significant portion of sales or margin from accessory items?
In this case it may make sense to delay payment and offer the PayPal buttons only in the shopping cart and checkout, for example.
So, you determine,
whether customers have to go through your checkout process and register in your eShop
or
whether customers can directly trigger the order without registering with their PayPal account (quick purchase).
By default, the Quick Purchase feature is active, and the PayPal button appears on the following pages:
Set customers to be automatically logged into your OXID eShop
if the email address of the PayPal account and the eShop account are identical
and
as soon as your customer is logged in to their PayPal account.
Benefit: You make the signup process more convenient for your customers.
Your customers will skip the login mechanism. Your customers log in to your OXID eShop without having to enter their password.
Disadvantages:
Often spouses, for example, use the same PayPal account.
One of the partners could thereby view the partner’s order history or other customer data in the OXID eShop.
So potentially there is a privacy risk.
If your customers do not have to log in to your eShop, you will lose customer order history data.
You could otherwise use such data for statistical analysis to target your customers.
If you do not enable Login with PayPal, the following happens:
If the customer’s PayPal email address is known, the PayPal payment process will be interrupted, and the customer will have to log in to your eShop.
The PayPal session is created, and your customer is logged into your eShop.
The customer’s identity is clearly established, and the current order is added to the customer’s order history.
If the customer’s PayPal email address is not known, your customer will complete the order using a guest account.
Your customer lands on the checkout page with the PayPal address data. The data is stored only once for the current order, no customer account is created in the eShop.
Procedure
Attention
The Login with PayPal function is enabled by default.
Check what can go wrong in the worst case if several users use the same PayPal account and can see each other’s data in your eShop.
There is no serious risk if your customers conveniently log in to your eShop automatically with their PayPal accounts?
Then leave the Automatically log in to shop during checkout checkbox selected.
Otherwise, deselect the checkbox.
For the PayPal payment type, specify whether payments are to be collected immediately, or whether payments should be deferred for a maximum of 30 days.
Example
Typically, the invoice amount is collected immediately.
However, in certain cases it makes sense that the payment is only triggered by the delivery:
You sell certain individualized products that you do not manufacture, commission, or order until the order is received.
You have an eShop for business customers. Here, the delivery quantities and payment amounts are larger than for private customers.
In the event of an error, returns management would be correspondingly more difficult.
That’s why you want to make sure that payment is only triggered when the goods are there or on their way to be shipped.
Important
If you choose deferred capture, you must deliver the product within 30 days and complete the transaction or find a solution together with the customer.
Background: By placing an order, PayPal is initially authorized to collect the money from your customer for 3 days. The authorization is automatically extended up to a maximum of 29 days after ordering.
After thirty days, the authorization expires, and PayPal can no longer collect the invoice amount.
To have payments always triggered directly, choose Directly.
To reserve the payment only and trigger it later, you have the following options:
automatically upon delivery: The payment is triggered as soon as you have set the ordered item to the status delivered in your eShop.
manually: The payment is triggered when you select the order under Administer Orders ‣ Orders and, on the PayPal Checkout tab, choose the Collect button.
Reservation is not possible for the Quick Purchase function of PayPal Checkout (payment method PayPal Express). The invoice amount is always collected immediately for PayPal Express payment method.
Make sure you have assigned the PayPal payment method only to the customized products in your eShop.
The delayed payment for PayPal Checkout payments will take effect for all items in your eShop to which you have assigned this payment method.
Reservation is not possible for the Fast Checkout feature of PayPal Checkout (payment method PayPal Express). For the PayPal Express payment method, the invoice amount is always collected immediately.
Assign the PayPal payment method to the customized products in your eShop.
It is technically not possible to assign certain payment methods exclusively to certain items. We suggest the following workaround:
Create a dedicated shipping cost rule and assign the items in question to it.
Make sure that the Quantity condition is correctly specified.
Create a dedicated shipping method and assign the PayPal payment method and shipping cost rule for individualized products to it.
Fig.: Choosing a dedicated shipping method in checkout
Result
In case of deferred money collection, under Administer orders ‣ Orders, collect the invoice amounts as follows (see Triggering reserved payments manually):
If you have chosen automatically upon delivery: You will trigger the payment as soon as you select the Ship Now button, setting the ordered item to the Delivered status.
If you have chosen manually: You trigger the payment by choosing the order under Administer Orders ‣ Orders and choosing the PayPal Checkout button on the Collect tab.
To meet the legal requirements for online payments with credit cards, use 3D Secure authentication.
With 3D Secure authentication, during the transaction, the issuing bank asks the customer to identify himself as the legitimate cardholder by entering a password.
This authentication by the issuing bank is mandatory throughout Europe in certain situations – for example, when depositing a credit card in an e-wallet (PayPal, for example) or for risky transactions.
Specify whether to delete incomplete orders automatically or manually.
Background
For technical reasons, PayPal creates orders even if the orders are not completed at the end.
This is the case when the customer chooses the Payment order button in the checkout, but then does not log in to PayPal and complete the payment process.
The automatic deletion is recommended, for example, if you sell low-priced bulk items.
It would be inconvenient for you to manually delete numerous incomplete orders one by one.
manual deletion may be useful, for example, if you sell high-priced goods with small sales volumes.
If customers bounce during the order process, manual deletion allows you to determine if there may be difficulties with certain PayPal payment methods.
To apply the existing PayPal banner advertising settings, choose the Apply settings from the classic PayPal module button.
The button appears only if the PayPal module is still activated.
If you want to take advantage of advertising PayPal installments, specify where you want the banners to appear, for example, on the home page, on the detail page of items, on category pages, in search results, and/or in the checkout process.
Fig.: Example: installment banner on a category page
Attention
Privacy
To let the banners appear, a permanent communication with the PayPal servers is necessary.
For this purpose, scripts are started with every page view, which observe user behavior and collect the information necessary for the PayPal payment process and transmit it to PayPal.
This communication may be undesirable, for example for reasons of
data protection
performance
In this case, make sure that the feature is disabled.
By default, the feature is turned on.
Procedure
To disable running scripts for PayPal banner ads, uncheck the Enable installment banners checkbox.
If you do not check the box, the scripts will not be executed.
If you allow running scripts for PayPal banner ads, specify on which pages the banner should appear.
To do this, choose the appropriate checkbox.
If you use a custom theme or a customized OXID theme, do the following:
Identify the CSS selector of the page behind which you want to place the banner.
Enter the CSS selector in appropriate input field.
Set the desired color of the banner under Select installment banner’s color.
By default, German and American English are configured as languages in which customers are asked to enter their credit card details, for example.
If you have configured additional languages under Master data ‣ Languages, make sure that you configure the appropriate variant (language abbreviation according to ISO 639-1 and country according to ISO 3166-1, for example fr_CA for Canadian French) for messages from PayPal Checkout.
Procedure
Under Master Settings ‣ Languages, check the languages that you have configured.
Under Locals, in the regional language settings field, enter the corresponding language abbreviations separated by commas in the <language abbreviation>_<country abbreviation> format.
Or adapt the default language abbreviations. Example: If your OXID eShop is aimed at customers in Great Britain, enter the language abbreviation for English in en_UK.
Fig.: Saving and managing payment information in the account
This speeds up the checkout process for regular customers and increases the user-friendliness of your OXID eShop. The payment button is labeled accordingly (Fig.: Paying with saved payment method, item 1).
PayPal Vaulting automatically creates a PayPal billing agreement with your customers. This allows you to charge the account in the future without your customers having to re-authenticate with PayPal or select a payment method from their wallet.
The function is practical, but you can deactivate it if required.
Adjusting pseudo shipping costs for PayPal Express
To enable payments with PayPal Express, use so-called pseudo shipping costs. In this way you ensure that the value of the shopping basket corresponds approximately to the value that is collected from the customer’s PayPal account at checkout.
The actual shipping costs are determined during the checkout process. The customer therefore does not pay the pseudo shipping costs, but the real costs.
Background
The pseudo shipping costs are only used for the moment of authorization (the customer cannot be logged in at that moment).
When a customer uses PayPal Express and adds an item to the shopping basket, they authorize a payment in the amount of the basket value plus a tolerance of approximately 5% for shipping costs.
In the case of low-priced items, the shipping costs may amount to more than 5% of the item price.
Example: The item price is 5 euros, the shipping costs are 4 euros. The tolerance is far exceeded.
If PayPal must permanently hold financial reserves because the real shipping costs permanently deviate from the shipping costs that PayPal estimates and that PayPal Express authorizes, then it may become difficult for PayPal to continue to provide you with the PayPal Express payment method.
To avoid this, bring the authorization price as close as possible to the final price.
Exceptions:
If the customer is already logged in, the system uses the real shipping costs for authorization from the outset.
If you have activated the Calculate default Shipping costs when ser is not logged in yet (in your OXID eShop under Master Settings ‣ Core Settings ‣ Settings ‣ Other Settings ), the shipping costs will be displayed accordingly and not the PayPal pseudo shipping costs.
If you have not activated the function (default setting), the PayPal pseudo shipping costs are displayed.
Under Pseudo shipping costs for PayPal Express, adjust the default value of 3.50 euros.
Specify a value for the standard shipping costs that corresponds to the shipping costs of typical purchases in your OXID eShop.
A value that covers more than 90% of purchases is ideal.
Optional: Configuring the country mapping of PayPal Checkout payment methods
Make sure that certain PayPal Checkout payment methods are only available in the countries you choose.
Background
With the initial installation, the PayPal Checkout payment methods are automatically assigned to the corresponding countries.
Most PayPal Checkout payment methods cover multiple countries. For example, the Credit Card payment method is available to customers worldwide, and the Pay Later payment method is available to your customers in countries in Europe, the USA, and Australia, for example.
The basic rule here is: A customer’s billing address, not the shipping address, determines whether a PayPal Checkout payment method is available for the customer.
Example: Only customers with a billing address in Poland will be offered the Przelewy24 payment method.
Procedure
To restrict the accessibility of a PayPal Checkout payment method to specific countries if needed, choose Shop Settings ‣ Payment Methods ‣ <payment method> ‣ Country ‣ Assign Countries.
Configure PayPal Checkout according to your needs and test the result.
Procedure
Under Master Settings ‣ Countries, make sure that the markets you want to cover are active.
Under Shop Settings ‣ Payment Methods, do the following:
Assign at least one user group to each of the desired PayPal Checkout payment methods (for example iDEAL (via PayPal).
On corresponding Master tab, make sure that you have set the desired minimum and maximum purchase value for the PayPal Checkout payment methods.
Example: The maximum purchase value for PayPal payment type is limited to €10,000 by default. The minimum purchase value is €10.
Under Shop Settings ‣ Shipping Methods, do the following:
Assign the desired PayPal Checkout payment methods to the respective shipping methods.
Make sure that at least one shipping method is created for payment with the PayPal payment method.
Typically, this is the default payment method.
For more information, see Payment methods of the OXID eShop user documentation.
If required, change the purchase value (€) in 0 to 99999.
