Configuration

Make Unzer Payment for OXID ready to use.

Basic procedure

Configure and test Unzer. Then switch on live operation.

Prerequisites

• You have agreed on the conditions with Unzer, opened a merchant account and received the access data from Unzer.

Procedure

1. Activate the module.

2. Under Access Data, create the connection to your Unzer merchant account.

3. If you use Apple Pay, do the following:

   1. Generate the necessary certificates locally.

   2. Sign the certificates in your Apple developer account.

   3. To make your Apple Pay credentials known to Unzer, under Options for Apple Pay, enter the signed certificates and upload them to Unzer.

4. Optional: if required, under Additional options … configure that payments should be triggered with a delay (for example, for business customers).

5. Check if your eShop theme uses jQuery.
   If it does not, under Other, include jQuery.

6. Link the payment methods provided by Unzer to your shipping methods and shipping rules and run test payments in the Unzer sandbox.
   The Sandbox mode is set by default after activation.

7. Test Unzer in the Unzer sandbox and adjust the configuration until all payment processes work as you want.

8. When you have finished your tests, under Operation mode switch to Production.

9. If you have run the tests on a dedicated test system and then move your eShop to the production system, regenerate the webhooks for the production system URL.

Activating Unzer

Activate Unzer in each subshop where you want to use the module.

Procedure

1. Choose Extensions ‣ Modules.

2. Choose the module Unzer Payment Module for OXID and choose Overview ‣ Activate.

Result

Under Shop Settings ‣ Payment Methods, the payment method covered by the Unzer Payment for OXID module are marked as active.

Active are automatically those payment method that match the countries you marked as active in Master Settings ‣ Countries (Fig.: Automatically activated payment methods).

Example

You have marked the Netherlands as active. This makes the payment method iDEAL available.

Fig.: Automatically activated payment methods

Configuring Unzer

Start the configuration.

Procedure

1. Choose Extensions ‣ Modules.

2. Choose the Unzer Payment Module for OXID module and choose Settings.

Access Data: Generating a webhook

Register a webhook to connect your eShop with Unzer.

Prerequisites

• You have the following data ready, which Unzer provided you with when you set up your merchant account:

  • Sandbox Public-Key

  • Sandbox Private-Key

  • Production Public-Key

  • Production Private-Key

For more information about authenticating with Unzer, see docs.unzer.com/server-side-integration/api-basics/authentication.

Procedure

1. Under Setting ‣ Access Data, enter the keys provided by Unzer into the corresponding fields (Fig.: Registering a webhook, item 1).

2. Choose Save.

3. Under Webhook Settings, choose the Create Webhooks button (Fig.: Registering a webhook, item 2).
   The button is active only if you have https.

Fig.: Registering a webhook

Result

The ID of your registered shop webhook is displayed (Fig.: Registering a webhook, item 3). Your store is connected to Unzer.

Credit card/PayPal options

Specify whether payments are to be collected immediately for the eShop, or whether payments are only to be reserved.

---

Example

Typically, the money is collected immediately.

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.
  So, in case of an error returns management would be more difficult.
  Therefore, you want to make sure that the payment is only triggered when the goods are there or on their way to be shipped.

---

Procedure

1. Choose Settings ‣ additional options for credit cards.

2. You have the following options:

   • To trigger payments directly, choose direct Capture.

   • To reserve the payment only and trigger it later, choose Authorize & later Capture.

3. Repeat step 2 under Settings ‣ additional options for PayPal.

4. Save your settings.

5. Make sure that you have assigned only the appropriately configured PayPal or Cards payment method to the customized products in your eShop.
   Delayed payment for payment by PayPal or Cards takes effect for all items in your eShop to which you have assigned these payment methods.

Result

The order has the status pending (see Fig.: Unzer order state: pending in chapter Operation).

If you have chosen Authorize for payment by PayPal or card payment, the delayed payment will be triggered,

• as soon as you set the ordered item to the status Delivered in your eShop

• when you request the payment using Unzer Insights (at insights.unzer.com)

For all other payment methods supported by Unzer, the payment is triggered immediately with the order.

Options for Apple Pay: Entering your credentials

If you use Apple Pay, connect to Apple separately.

To do this, generate the following Apple Pay credentials, have them signed in your Apple developer account, and upload them to Unzer:

• Merchant ID

• Payment processing certificate

• Payment processing certificate private key

• Merchant certificate

• Merchant certificate private key

Prerequisites

• You have connected your OXID eShop to Unzer (see Access Data: Generating a webhook).

Procedure

1. Create an Apple Pay merchant ID (see Creating an Apple Pay merchant ID).

2. Create an Apple signed payment processing certificate and associated payment processing private key in PKCS#8 format (see: Generating a payment certificate).

3. Choose Settings ‣ additional options for Apple Pay.

4. In the appropriate input fields, enter payment certificate and key.
   Make sure to include the prefix and suffix (-----BEGIN PRIVATE KEY-----, for example).

   • Open the pem file with the payment processing certificate (in our example apple_pay.pem) and copy the content into the payment processing certificate field.

   • Open the text file with the private key for payment processing (in our example privatekey.key) and copy the content into the Private key for payment processing field.

5. Choose the Transfer payment certificates button.

6. Generate an Apple-signed merchant certificate and the corresponding private key in PKCS#8 format (see: Creating an Apple Pay merchant ID).

7. Choose Settings ‣ additional options for Apple Pay.

8. In the Merchant Identifier field, enter the merchant ID you created in your Apple developer account (see Creating an Apple Pay merchant ID).

9. Enter the merchant certificate and key in the appropriate input fields (including prefix and suffix):

   • Open the pem file containing the merchant certificate (in our example merchant_id.pem) and copy the contents into the Payment Processing Certificate field.

   • Open the text file with the private key to the merchant certificate (in our example merchant_id.key) and copy the content into the Private key for payment processing field.

10. In the Company field, enter your company name.

11. Under Supported credit cards, activate the credit card company whose credit card is associated with your Apple Pay account.

    Attention

    Conversion at risk

    Which credit card companies you can choose as supported depends on your agreement with Unzer.

    If you mark credit card companies that differ from your agreement with Unzer, no checkout is possible, and your customer will probably reject your shop.

    Test all payment methods extensively in the sandbox.

12. Optional: Under Supported payment types, choose the card type you want to allow :

    • Checkbox Credit Card: Allow credit card payments.

    • Check box Debit Card: Allow debit card payments.

    By default, both card types are active. Both card types are active even if you check neither of the two checkboxes.
    Debit card payments are used less frequently than credit card payments. For example, if you consider credit cards more reliable, choose this card type as the only one allowed.

13. Save your settings.

Entering access data for Unzer Invoice (Paylater)

If you want to use the Unzer Invoice (Paylater) payment method, enter the public and private keys provided by Unzer.

Prerequisites

• Depending on the combination of currency and customer type you have agreed on with Unzer, you have the following data ready, which Unzer has provided you with when you set up your merchant account:

  • Sandbox Public-Key

  • Sandbox Private-Key

  • Production Public-Key

  • Production Private-Key

Procedure

1. Under Settings ‣ Additional Options for Unzer Invoice (Paylater), in the appropriate fields, enter the keys provided by Unzer.

   Make sure that you enter the key pair for both currencies (EUR and CHF) (Figure: Entering key pairs for Unzer Invoice (Paylater), item 1 and 2) for each customer type (in our example only B2C).

2. Save your settings.

3. To ensure that payment information is sent back from Unzer to your OXID eShop, under Webhook settings, choose the Create Webhooks button.

Note

Match currencies and credentials.

The payment method Unzer Invoice (Paylater) will only be offered in the checkout if you have

• configured the currency that matches the key pair (EUR or CHF)

• entered the key pairs tat match the configured currencies

Under Master Settings ‣ Core Settings ‣ Settings ‣ Other settings, make sure that you have configured the desired currencies.

Figure: Entering key pairs for Unzer Invoice (Paylater)

Result

Under Webhook Settings, the webhooks for the payment methods are displayed (Fig.: Creating webhooks and displaying the IDs, item 3).

In the checkout, an additional query for the date of birth (Figure: Specifying the date of birth and company form, item 1) appears automatically for private customers (B2C).

Business customers (B2B) are automatically recognized by the system by an entry in the company name input field. In addition to the date of birth, a business customer must specify the legal form of his company.

From the information about the customer, Unzer calculates a credit rating of the customer.

Figure: Specifying the date of birth and company form

Recommended: Ensuring correct currency settings

Make sure that the currencies that your OXID eShop supports match the currencies that a payment method supports.

However, nothing can go wrong: For currencies that a payment method does not support, only the respective button for the payment method is not displayed in the checkout.

Procedure

1. Check the currencies that your store supports:

   1. Choose Master Settings ‣ Core Settings.

   2. On the Settings tab, expand the Other Settings section.

   3. In the input field for currencies, check whether you want to add or remove currencies.

2. To ensure a clean configuration, do the following:

   1. Under Shop Settings ‣ Payment Methods, for the respective payment type, choose the Country tab.

   2. Make sure that only those countries are assigned whose currency is supported by the payment type.

Other: Ensuring optimum performance

Unzer uses jQuery for validating form inputs.

However, to avoid affecting the performance of your OXID eShop, make sure that jQuery is not installed twice.

Example

You use one of the two OXID themes Wave or Fluid.

Both OXID themes have jQuery already integrated.

To avoid interference, make sure that jQuery is not included again separately for Unzer Payment for OXID.

Procedure

1. Verify if the theme of your OXID eShop uses jQuery:

   • Ask your web front-end developer.

   • Alternatively: Inspect the HTML code of your eShop’s front page.

2. Choose Settings ‣ Other.

3. Do the following:

   • If your theme uses jQuery, make sure the Include jQuery via the module checkbox is deactivated.

   • If your theme does not use jQuery, make sure the Include jQuery via the module checkbox is activated.

Operation mode: Testing the eShop and activating live operation

Test Unzer Payment for OXID in the Unzer sandbox and adjust the configuration until all payment processes work as you want them to.

To do this, run test payments in the Unzer sandbox.

The operating mode Sandbox is set by default.

Recommendation: Use a dedicated test system for testing. In this case, follow the instructions in Switching from a test system to the production system.

Prerequisites

• To start live operation, you have created an Unzer Insights account (https://insights.unzer.com/signin).

  For more information, see the Go-live checklist.

Procedure

1. Optional: To generate logs during testing, activate the checkbox under Settings ‣ Operation mode activate Enable debug mode.
   Typically, you turn on logging only on request: When the Unzer support asks you to debug a problem.
   You find the log files in the directory source/log/unzer.

2. Configure the payment methods provided by Unzer Payment for OXID as payment methods in your eShop:

   • Enable the countries you want to cover.

   • Link the payment methods to your shipping methods and shipping rules.

   • Avoid duplication of payment methods.
     Background: Unzer Direct Debit (SEPA Direct Debit) can be offered in European countries including Germany, Unzer Direct Debit (SEPA Direct Debit) (secured with Unzer) however only in Germany.
     Configure these invoice types so that Unzer Direct Debit (SEPA Direct Debit) (secured with Unzer) is assigned to German user groups only and Unzer Direct Debit (SEPA Direct Debit) is assigned to non-German user groups only.

3. After you have configured and tested the functions of the module, under Settings ‣ Access Data make sure that you have entered the following data that you received from Unzer:

   • In the Live public key field is the Production public key.

   • In the Live private key field is the Production Private-Key.

4. Under Operation mode, choose Production and choose Save.

5. If you use Apple Pay, do the following:

   1. Under additional options for Apple Pay, re-enter key and certificates.
      You have created the certificates and keys in your Apple developer account and saved them locally (see Creating Apple Pay access data).

      • Payment processing certificate (file apple_pay.pem).

      • Private key for payment processing (file privatekey.key).

      • Shop operator certificate (file merchant_id.pem)

      • Private key to store operator certificate (file merchant_id.key)

   2. Choose Transfer payment certificates (Production).

6. To avoid unnecessary memory consumption, under Operating mode make sure that the debug mode is disabled in live mode.

7. Save your settings.

Switching from a test system to the production system

If you have installed Unzer on a dedicated test system first, regenerate the webhook for the production system URL.

Otherwise, you will not receive any status messages on your production system, and you will not be able to process your customers’ orders.

Also, make sure that you delete the webhook on your test system.

In this way, you maximize the performance of your Unzer connection.

Delete and regenerate a webhook also in case you have changed the URL of your OXID eShop for other reasons.

Background

If the webhook is still active on your test system even when you are not using the test system, the status messages that Unzer sends to their production system will also be sent to your test system.

This creates an unnecessary system load on the Unzer system that is connected to your webhook. This can decrease the performance of your Unzer connection.

Procedure

1. On your dedicated test system, do the following:

   1. Choose Extensions ‣ Modules ‣ Unzer Payment Module for OXID ‣ Settings.

   2. Under Webhook settings, choose Delete Webhooks (Fig.: Creating webhooks and displaying the IDs, item 1).

2. Repeat step 1 on your production system.

3. Under Access Data, re-enter your Unzer access data (Fig.: Registering a webhook, item 1) and choose Save.

4. If you use Apple Pay, under Settings ‣ additional options for Apple Pay enter the certificates and keys you created in your Apple developer account and stored locally (see Creating Apple Pay access data).

5. If you use Unzer Invoice (Paylater), enter the required keys (see Entering access data for Unzer Invoice (Paylater).

6. Choose the Create Webhooks button (Fig.: Creating webhooks and displaying the IDs, item 2).

Fig.: Creating webhooks and displaying the IDs

Result

The webhook IDs of your OXID eShop and your registered payment methods are displayed (Fig.: Creating webhooks and displaying the IDs, item 3).

Your production system receives status reports from Unzer about your customers’ payment transactions.
You can view the transaction data. For more information, see Operation.