Configuration

Make the PayPal Checkout module operational for your OXID eShop.

You already have PayPal or PayPal Plus?

Ensure a smooth transition to the new PayPal Checkout module.

To do this, note the following two restrictions:

Re-running the registration for PayPal Checkout

If you have PayPal Plus, please note the following:

The credentials and registration process of PayPal Checkout are outwardly similar to PayPal Plus.

However, do not let this tempt you to reuse the credentials from PayPal Plus.

This would lead to the following undesirable behaviors:

  • Webhooks are not activated correctly, information is not transmitted correctly, but without the errors being immediately apparent.

  • Payment methods such as installment purchase are not available, payment by credit card is not enabled.

Procedure

Do the following:

  1. Test PayPal Checkout in the PayPal sandbox with test accounts as described in Configuring PayPal Checkout.

  2. 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, please 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 method PayPal.

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.

  1. Install PayPal Checkout.

  2. 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.

  3. Enable PayPal Checkout for live operation as described under Activating PayPal Checkout.

  4. Select Shop Settings ‣ Payment Methods.

  5. 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.

  6. 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.

  7. 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.

Basic procedure

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?

    1. Perform the onboarding for your subshops.

    2. 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.

    3. If the restriction is critical for your business model, contact PayPal support to get an activation for the required PayPal Checkout payment method.

  1. Activate the module.
    The most important payment methods are automatically activated.

  2. Connect to PayPal via a webhook.

    Attention

    • Do not use the credentials for PayPal Plus to establish the connection.

    • Test PayPal Plus in the PayPal sandbox first.

  3. Optional: Disable the express checkout feature of PayPal Checkout if needed.

  4. Optional: Specify if you want to offer PayPal installment payment (see Figure: Example: installment banner on a category page) to your customers.

  5. If necessary, contact PayPal Customer Service to determine the best way for PayPal to handle 3D Secure authentication in your case (see Figure: Configuring 3D Secure authentication).

  6. 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.

  7. Run test payments in the PayPal Checkout sandbox. and adjust the configuration until all payment processes works as you want.

  8. Enable PayPal Checkout:

    1. If you do not have a merchant account yet, create one for live operation.

    2. Switch to Live operation mode.

Activating PayPal Checkout

Ensure PayPal Checkout is activated in each subshop where you want to use the module.

Procedure

  1. Choose Extensions ‣ Modules.

  2. Choose the PayPal Checkout for OXID module and choose Overview ‣ Activate.

Result

Under Shop Settings ‣ Payment Methods, the payment methods PayPal as well as important additional payment methods, are marked as active.

To actually use a certain country-specific payment method, you must have marked the respective country as active under Master Settings ‣ Countries.

Example

To be able to offer iDEAL, you must have made sure that you have set the Netherlands as active under Master Settings ‣ Countries.

Configuring PayPal Checkout

To start the configuration, choose PayPal ‣ Configuration.

Note

In order to be able to configure the module, it must first be activated. After activation, the new menu item PayPal appears on the left navigation menu.

API Credentials

Register a webhook to connect your eShop with PayPal.

The webhook allows PayPal to contact your OXID eShop and provide real-time status messages about, for example, completed transactions.

Hint

It’s possible to let the shop track the incoming webhooks by setting the config parameter $this->sLogLevel in the file config.inc.php to debug. After that, the webhook calls by PayPal are written to the file oxideshop.log.

In the first run, you test the payment methods provided with PayPal Checkout with test credentials in a sandbox.

Hint

What does testing in the sandbox do for me?

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.

Procedure

We describe the process 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?

    1. Perform the onboarding for your subshops.

    2. 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.

    3. If the restriction is critical for your business model, contact PayPal support to get an activation for the required PayPal Checkout payment method.

  1. To log in to the sandbox, under API credentials choose the Start Merchant Integration (Sandbox) in a new window button.

  2. Select Sign Up Merchant Integration (Sandbox).

  3. Go through the registration process with the sandbox merchant account email address.

    1. Log in with your (sandbox) merchant account (Figure: Starting the registration of the sandbox merchant account), and confirm the prompts.

      Starting the registration of the sandbox merchant account

      Figure: Starting the registration of the sandbox merchant account

    2. Finally, choose Back to John Doe`s Test Store (Figure: Completing the registration of the merchant account).

      Completing the registration of the merchant account

      Figure: Completing the registration of the merchant account

      A message indicates success (Figure: Message onboarding successful).

      Message onboarding successful

      Figure: Message onboarding successful

  4. Switch back to your OXID eShop.

    The webhook is created.

    The client ID and the webhook ID are displayed (Figure: Webhook created).

    Webhook created

    Figure: Webhook created

  5. If you want to use the payment methods Pay upon Invoice or credit card, under Activation for special payment methods has taken place (Figure: Webhook created) check whether the activation has been done.
    If the activation did not happen automatically, contact your PayPal representative.

Hint

Credit card payment method.

If the credit card payment method has not been activated automatically, the payment method will appear as a separate credit card button below the PayPal button.

Payment method credit card not activated

Once the activation is done, your customer sees the PayPal button, and the credit card payment method is available in the Shipping & Payment Method checkout step.

Payment method credit card activated

Hint

Payment method Pay upon Invoice

PayPal offers the payment method Pay upon Invoice only to show owners 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 (Figure: Webhook created).

Under Shop Settings ‣ Payment Methods, the payment method PayPal (technical name oscpaypal) is active (Figure: Payment method PayPal active).

Payment method PayPal active

Figure: Payment method PayPal active

Hint

Generating a new webhook.

Sometimes it may be necessary to delete the existing webhook and generate a new one.

To delete a webhook, delete the credentials and select Save.

The Register Merchant PayPal Integration button appears and you can regenerate the webhook.

Button placement settings: Quick purchase

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:

So, your customers can use their PayPal account to trigger the order at any time.

If you want your customers to have to register in your eShop, disable the quick purchase feature.

Mini shopping cart and Pay Later

Abb.: Mini shopping cart and Pay Later

Procedure

  1. To disable the express checkout feature, uncheck Product details page, Basket, and Mini-Basket (Fig.: Controlling the display of PayPal buttons, item 1).

  2. Save your settings.

Controlling the display of PayPal buttons

Fig.: Controlling the display of PayPal buttons

Result

The PayPal button appears only on the checkout page.

Button placement settings: Pay later

Decide whether you want to offer the Pay Later feature (Abb.: Mini shopping cart and Pay Later, pos. 2).

Pay Later means, for example, that PayPal offers customers in Germany the “Pay after 30 days” or PayPal installments options.

For more information about country coverage and country-specific features of the Pay Later feature, see developer.paypal.com/docs/checkout/pay-later/en.

Procedure

  1. To offer your customers Pay Later features, choose the “Show Pay Later” button? checkbox (Fig.: Controlling the display of PayPal buttons, item 2).

  2. Save your settings.

Login with PayPal

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.

  1. 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.

  2. 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.

  3. Save your settings.

Configuring money collection

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

You need to deliver the product within 30 days and complete the transaction or work with the customer to find a solution.

Background: By placing an order PayPal is initially authorized for 3 days to collect the money from your customer. 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.

Procedure

  1. Under PayPal Standard - Money Collection (Figure: Configuring delayed payment), you have the following options:

    • To have payments always triggered directly, choose Directly.

    • To reserve the payment only and trigger it later, you have the following options:

      • Automatically on delivery: The payment is triggered as soon as you have set the ordered item to the Delivered status in your eShop.

      • Manually: Payment is triggered when you go to Administer Orders ‣ Orders, select the order, and, on the PayPal Checkout tab, choose the Collect button.

  2. Save your settings.

  3. 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.

Configuring delayed payment

Figure: Configuring delayed payment

Configuring 3D Secure for debit and credit cards

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.

For more information about 3D Secure authentication, see paypal.com/en/webapps/mpp/3dsecure-faqs.

You have the following options:

  • For the highest possible security, enforce a 3D Secure query for every credit card transaction.

  • Have PayPal ensure that 3D Secure is only used when necessary.
    PayPal ensures that the majority of your customers can shop undisturbed.

  • Disable 3D Secure result evaluation: To learn in which cases this setting may be useful for you, contact PayPal Customer Service at paypal.com/en/webapps/helpcenter/helphub/home/.

Procedure

  1. If needed: To determine the best setting for your purposes, contact PayPal Customer Service at paypal.com/en/webapps/helpcenter/helphub/home.

  2. Choose the desired setting (Figure: Configuring 3D Secure authentication).

  3. Save your settings.

Configuring 3D Secure authentication

Figure: Configuring 3D Secure authentication

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.

For more information about the country coverage of each PayPal Checkout payment method, see Market coverage by payment methods.

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.

Testing PayPal Checkout

Configure PayPal Checkout according to your needs and test the result.

Procedure

  1. Under Master Settings ‣ Countries, make sure that the markets you want to cover are active.

  2. Under Shop Settings ‣ Payment Methods, do the following:

    1. Assign at least one user group to each of the desired PayPal Checkout payment methods (for example iDEAL (via PayPal).

    2. 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.

  3. Under Shop Settings ‣ Shipping Methods, do the following:

    1. Assign the desired PayPal Checkout payment methods to the respective shipping methods.

    2. 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.

Unlocking PayPal Checkout

Unlock PayPal Checkout after testing.

Attention

Do not use PayPal Plus credentials

You already have PayPal Plus? In this case do not use the credentials for PayPal Checkout.

Generate the credentials for PayPal Checkout with your PayPal merchant account again, as described below.

Prerequisites

You have configured the desired payment methods and tested them successfully with test payments in the PayPal sandbox (see Testing PayPal Checkout).

Procedure

  1. Under API credentials choose the Live operating mode.

  2. Choose the Start Merchant Integration (Live) button.
    A dialog box for logging in to PayPal appears.

  3. Log in with your existing PayPal merchant account. If you don’t have a live login yet, create a new PayPal merchant account.

  4. Save your settings.

  5. If you use PayPal or PayPal Plus, follow the recommendations under Administering existing PayPal or PayPal Plus orders.

Result

The PayPal API credentials are inserted.

The PayPal Checkout module is active and ready for orders from your customers.