1. Configuration in your Heidelpay account

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

  • Activate notifications using this URL as a receiver address: https://app.billwerk.com/PSPWebhooks/HeidelpayPushNotifications
  • Activate the setting, so customers don't come on a blacklist, when there was a return debit note.

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


- The integration does currently not support 3D Secure

2. Configuration in your billwerk account

You can find the Heidelpay settings inside billwerk in "Settings > Payment settings > Heidelpay".


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 Heidelpay enter the following URL as the receiving address for notifications for your test account: https://sandbox.billwerk.com/PSPWebhooks/HeidelpayPushNotifications

To test Heidelpay 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.heidelpay.de/testumgebung/ for current test data.


4. Special instructions for a technical integration

Success Callbacks / Heidelpay

The Heidelpay 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 Heidelpay, control of the payment data in billwerk must be transferred to Heidelpay with a POST request. Heidelpay then calls the providerReturnUrl which contains Finalize().

With Heidelpay, the Finalize success callback is called first in both cases, since for technical reasons a forwarding to Heidelpay 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 Heidelpay 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 Heidelpay. 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