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
Activate the module.
Under Access Data, create the connection to your Unzer merchant account.
If you use Apple Pay, do the following:
Generate the necessary certificates locally.
Sign the certificates in your Apple developer account.
To make your Apple Pay credentials known to Unzer, under Options for Apple Pay, enter the signed certificates and upload them to Unzer.
Optional: if required, under Additional options … configure that payments should be triggered with a delay (for example, for business customers).
Check if your eShop theme uses jQuery.
If it does not, under Other, include jQuery.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.Test Unzer in the Unzer sandbox and adjust the configuration until all payment processes work as you want.
When you have finished your tests, under Operation mode switch to Production.
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
Choose
.Choose the module Unzer Payment Module for OXID and choose .
Result
Under Unzer Payment for OXID module are marked as active.
, the payment method covered by theActive are automatically those payment method that match the countries you marked as active in Fig.: Automatically activated payment methods).
(Example
You have marked the Netherlands as active. This makes the payment method iDEAL available.
![Automatically activated payment methods](_images/oxdamc01.png)
Fig.: Automatically activated payment methods
Configuring Unzer
Start the configuration.
Procedure
Choose
.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
Under Fig.: Registering a webhook, item 1).
, enter the keys provided by Unzer into the corresponding fields (Choose Save.
Under Create Webhooks button (Fig.: Registering a webhook, item 2).
, choose the
The button is active only if you havehttps
.
![Registering a webhook](_images/oxdamc02.png)
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
Choose
.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.
Repeat step 2 under
.Save your settings.
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
Create an Apple Pay merchant ID (see Creating an Apple Pay merchant ID).
Create an Apple signed payment processing certificate and associated payment processing private key in PKCS#8 format (see: Generating a payment certificate).
Choose
.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 exampleapple_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.
Choose the Transfer payment certificates button.
Generate an Apple-signed merchant certificate and the corresponding private key in PKCS#8 format (see: Creating an Apple Pay merchant ID).
Choose
.In the Merchant Identifier field, enter the merchant ID you created in your Apple developer account (see Creating an Apple Pay merchant ID).
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 examplemerchant_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.
In the Company field, enter your company name.
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.
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.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
Under
, 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).
Save your settings.
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
, make sure that you have configured the desired currencies.![Entering key pairs for Unzer Invoice (Paylater)](_images/oxdamc04.png)
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.
![Specifying the date of birth and company form](_images/oxdamc05.png)
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
Check the currencies that your store supports:
Choose
.On the Settings tab, expand the Other Settings section.
In the input field for currencies, check whether you want to add or remove currencies.
To ensure a clean configuration, do the following:
Under Country tab.
, for the respective payment type, choose theMake 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
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.
Choose
.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
Optional: To generate logs during testing, activate the checkbox under Enable debug mode.
activate
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 directorysource/log/unzer
.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.
After you have configured and tested the functions of the module, under
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.
Under Operation mode, choose Production and choose Save.
If you use Apple Pay, do the following:
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
)
Choose Transfer payment certificates (Production).
To avoid unnecessary memory consumption, under Operating mode make sure that the debug mode is disabled in live mode.
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
On your dedicated test system, do the following:
Choose
.Under Webhook settings, choose Delete Webhooks (Fig.: Creating webhooks and displaying the IDs, item 1).
Repeat step 1 on your production system.
Under Access Data, re-enter your Unzer access data (Fig.: Registering a webhook, item 1) and choose Save.
If you use Apple Pay, under enter the certificates and keys you created in your Apple developer account and stored locally (see Creating Apple Pay access data).
If you use Unzer Invoice (Paylater), enter the required keys (see Entering access data for Unzer Invoice (Paylater).
Choose the Create Webhooks button (Fig.: Creating webhooks and displaying the IDs, item 2).
![Creating webhooks and displaying the IDs](_images/oxdamc03.png)
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.