Unzer (formerly Heidelpay)


1. Configuration in your Unzer account

You have to set the following configuration in your Unzer account:

You cannot change these settings yourself. Please contact the Unzer customer support to trigger the changes. 

Remark: Support for 3D-Secure credit card payments with the Unzer integration is currently being implemented together with Unzer and should be available by the end of 2020.


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.

Credit card


Card numer 5453010000059543
Expiry date Any date in the future
CVV 123
3D secure password secret3


Card number 4711100000000000
Expiry date Any date in the future
CVV 123
3D Secure password secret3


Direct debit Germany

BLZ 37040044
Account number 5320130
IBAN DE89370400440532013000

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.

Was this article helpful?
1 out of 1 found this helpful