Note: An integration of Unzer is possible with the Unzer Enterprise module. Before you start with the setup please make sure that you have booked this module with Unzer. An integration with the booked module Unzer Direct can currently not be configured.
1. Configuration in your Unzer account
You have to set the following configuration in your Unzer account:
- Activate notifications using this URL as a receiver address: https://app.billwerk.com/PSPWebhooks/UnzerPushNotifications
You cannot change these settings yourself. Please contact the Unzer customer support to trigger the changes.
2. Configuration in your billwerk account
You can find the Unzer settings inside billwerk in "Settings > Payment settings > Unzer".
Note: In the settings you can select the billwerk API mode. Leave this setting on "Unzer". The value "Heidelpay" is only for compatibility with older connections.
3. Test data
To create successful signups, for test customers and real ones, you have to enter an email address and a full invoice address.
You must have Unzer enter the following URL as the receiving address for notifications for your test account: https://sandbox.billwerk.com/PSPWebhooks/UnzerPushNotifications
To test Unzer on the billwerk-Sandbox, select ''Test'' for Platform and ''Integrator Test'' for Transaction Mode.
|Expiry date||Any date in the future|
|3D secure password||secret3|
|Expiry date||Any date in the future|
|3D Secure password||secret3|
Direct debit Germany
If the test data should not work, please see here: https://dev.unzer.de/testumgebung/for current test data.
4. Special instructions for a technical integration
Success Callbacks / Unzer
The Unzer integration deviates from the standard integration of other payment providers due to technical necessity. The billwerk standard workflow provides for two different cases for handling payment data. Either the data can be transmitted directly to the payment provider (1) or in the order workflow, the data must be forwarded to the payment provider (2), who in turn calls up the specified providerReturnUrl at the end.
In case (1) without forwarding, e.g. with paySignupInteractive() the success callback is called and as a result of a successful order the ContractId and Customer Id are communicated. The order workflow ends here.
In case (2) with forwarding, e.g. with paySignupInteractive() the success callback is also called, but this time with a Provider Url to which the success callback must forward. If the provider then calls the providerReturnUrl again, Finalize() is called there, which in case of success calls the success callback and transfers the Contract Id and Customer Id.
In the case of Unzer, control of the payment data in billwerk must be transferred to Unzer with a POST request. Unzer then calls the providerReturnUrl which contains Finalize().
With Unzer, the Finalize success callback is called first in both cases, since for technical reasons a forwarding to Unzer must always take place internally. In the end it is more like case (2) (see Finalize Page in https://developer.billwerk.io/Docs/subscriptionJS_Introduction#getting-started), without the redirection taking place manually in the first success callback. The treatment in the success callback is the same in both cases, but for Unzer only in the finalize success callback.
Incorrect payment data
Normally incorrect entries are returned by the payment provider in the error callback when calling paySignupInteractive / payUpgradeInteractive / paymentChange and can be handled accordingly before a payment attempt is made. This is not possible with Unzer. It can happen that a payment attempt takes place with incorrect payment data, which then fails logically. Since the payment attempt failed, a new order must be created in such cases.
5. More hints
After a chargeback, the IBAN in question is automatically blacklisted by Unzer and subsequent debits are no longer possible via this IBAN.
Optionally, you can request Unzer in writing to waive the general use of the blacklist and its protective mechanisms. Please note, however, that this may result in multiple use of an already conspicuous means of payment, as well as an increase in the chargeback rate, which may result in additional chargeback fees on the part of the banks.