Skip to main content

Transform Help Center

Best Practice evaluating payment issues

This article shall provide an overall guide how to evaluate, understand as well as solve a payment issue within the billwerk application.


Note: billwerk provides a connection with several different payment service providers (PSP). Each one has it's own error messages in regards to payment issues so not all specific cases can be handled here. To evaluate such specific error messages, please refer to the documentation of the integrated PSP in addition.

Payment has not been triggered

You have a customer who received an invoice and you expect a payment to be triggered as well, but in the contract ledger of that customer you are not able to find a corresponding payment transaction?


Please check the following details that are mandatory to perform a transaction:

1. Payment method is selected with the needed payment data in the contract

If that does not apply, please set the payment data within the contract details. You can either do that manually within the billwerk application or provide the SelfService URL to the customer and request the customer to update his payment data.


Note: Credit Card details can not be entered by you within the billwerk application, this needs to be done by the customer. As soon as the payment data is set, a payment transaction should be triggered automatically.


2. There is an open receivable in the contract ledger with a balance >0

Please check the contract balance within the contract ledger. The actual balance can be found in the contract ledger on the top of column "Running Total". If the balance is <=0 the customer has a balanced account or even a credit. In this case no payment will be triggered as there is no open debt to be settled. Wait for the next invoice to be created and check again if there is something to be debited.


3. Recurring Payments are switched on

Please check if the switch button for recurring payments is switched to On. It is only visible if you have added payment data to the contract. Recurring payments can be switched off manually via UI but there are also cases where this functionality is switched off by the system automatically. Those cases will be mentioned in the following sections of this article. To trigger payments automatically please make sure to switch recurring payment to on.



Note: Preauth and failed transactions will not show in the contract ledger. To check if a transaction has been triggered even if nothing is shown in the contract ledger please investigate the transaction within the payment logs for further details. In the contract details you have a direct link to the payment logs with a filter set to this contract.


Payment failed

If a payment has been triggered but fails this can cause several workflows being processed within billwerk, e.g.:

  • An order fails as well and new contract or up-/ downgrades are not performed

  • according to the error level billwerk will apply different retry strategies

    • renewed attempt to collect money

    • recurring payments will be switched off

    • automatic billing will be switched off

  • escalation process might be triggered as soon as according invoice is overdue

Like mentioned in the previous section please be aware that failed payments are not registered in the contract ledger of a customer. To investigate why a payment has failed please navigate to the payment logs and have a closer look into the payment log details. Here you can set filters to search for payments of a specific contract or set a filter regarding the payment status (e.g. Failed) and a specify time range.


There are several reasons why a payment has failed. Also each PSP has it's own error messages and details provided. To view them please open the details of the payment log of a payment transaction and look up the PSP error details provided. In the following example you can see a failed payment due to missing data. So to resolve the issue you will need to add this data to the customer details and try to debit the customer again.


Unfortunately sometimes the error messages given by the PSP are not very self-explaining. Especially if you find a PSP Error Message stating "Unmapped error". In this case please refer to the documentation of the PSP and look up the PSP Error Code given in the billwerk payment log details. Usually the documentations of the PSPs have an own article where you can look up the error code and get a description of the error that occurred. If also that description doesn't help, you may need to contact the PSP directly and ask them for further help and details. If available you can reference to the PSP Transaction ID stated in the billwerk payment transaction log details.

Payment is not being confirmed

If a payment has been triggered by billwerk you might notice that payments are at first in status "unconfirmed". This means that a payment has been initiated and corresponding data has been transmitted to the processing PSP but the money hasn't been collected from the customer yet. A payment will be set to "confirmed" status in billwerk as soon as the PSP notified billwerk that the money collection has been successfully performed with the full amount to be debited. This can take a few days to be done. The status of the payment has several effects within billwerk.

1. Reporting

In regards to reporting please note that only when a payment is shown as confirmed in billwerk, the system has received the information that the payment has really been made. This also affects the results of the billwerk reports, such as the financial accounting report or the open items report. Thus, an unconfirmed payment will still be displayed in the open items report and not in the accounting export. Only when the payment is displayed as confirmed in billwerk does the behavior change and the payment no longer appears in the open items report, but instead in the financial accounting export.

2. Cancellation of payments

Payments can be cancelled by the customer as long as the status of the payment is unconfirmed at that time. As soon as the status switches to confirmed status, the customer is not able to cancel a payment but only to trigger a charge-back which will be mentioned in the following sections.

3. Refunding

Also performing refunds is depending on the status of a payment. Refunds can only be triggered if a payment has already been confirmed. If this logic wouldn't apply you would run into a problem - refunding a payment where money hasn't been collected from the customer yet and he decides to cancel the payment. By that you would have refunded money that the customer has never payed which will result in a credit.

Refunds are not being performed


Note: Refunds are never triggered automatically.

In billwerk you have two options to register a refund.

If a credit note is created this will decrease the amount of receivables in a contract ledger or even result in a credit. If you do not actively trigger a refund the contract balance will remain in a credit until it is charged with the next invoice. Also be aware of the difference between the functionality of a refund and an external refund which are described below.


You can perform a refund where the payment is triggered in billwerk and processed by the PSP automatically. Preconditions to be able to perform such a refund can be found in our Help Center article How can I refund money to a customer?

If a refund via a PSP has been processed you can recognize that in the related contract ledger entry. As those refunds always refer to a payment transaction that has been settled via the PSP you will see the related payment transaction id in the description column of the triggered refund.


If a refund as mentioned above is not possible you can also register an external refund. When triggering an external refund you are able to set manually a description that will show in the the description column of the refund in the contract ledger instead.


With an external refund the amount to be refunded must be carried out outside billwerk, e.g. directly via the payment provider's merchant portal or via your own online banking.


Note: The external refund does not trigger a transaction but only balances the contract ledger in billwerk.

The following section will discuss refunds performed via a PSP and what issues might occur and what to take into account to evaluate and solve these:

  1. Check the time period between the last payment transaction and refund

  2. Check the contract ledger balance where refund shall be performed

  3. Check if payment data has changed between the last payment transaction and refund

  4. Check workflows on how refund was tried to be performed via Audit Logs

In several cases you might have tried to perform a refund but in the UI it is stated that the currently available credit amount is 0.00 EUR or less than the amount you actually try to refund. In any case, if you see that the button "Refund" is greyed out you are not even able to trigger the refund and by that don't have the possibility to check for errors in the payment logs. As this system behavior can have multiple reasons please check for the actual issue the following cases.


If a refund cannot be performed in a customers contract please check when the correlating payment transaction you are trying to refund has been triggered. There are two reasons regarding the time period when performing a refund that can cause issues.

First one is if you're trying to trigger a refund too early. Let's make an example for that case. Your customer has the payment method direct debit set and a transaction to debit his account was triggered just yesterday. In this case you should notice that the payment might still be in status unconfirmed as the payment has not yet been received in your bank account. To refund this transaction please wait a few days until the payment has been confirmed in the billwerk account and try again.

Second to consider is that you might have tried to refund a really old payment transaction. Refunds via a PSP are only possible over a certain period of time. This period is specified by the PSP and cannot be influenced by billwerk. If the last payment transaction is classified too old to perform a refund please make an external refund instead.

You will also run into issues if you try to refund a customer that has a contract ledger balance >=0. This means that you are trying to refund a customer that doesn't even have a credit and by that this doesn't make sense in an accounting perspective. If you still want to refund money to the customer please create a credit note with the intended amount first.


Another reason that you are not able to refund the desired amount, even if the customer has the according credit in his contract ledger is that all payment transactions that have been registered as successful before have been processed with different customer payment data than set as a payment bearer in the customers contract at the time you try to rigger a refund. Please note that a refund can only ever be made on the original payment method. If the payment method has been changed in the meantime, the money will not be refunded to the new payment method. Also the amount of the refund may not exceed the amount of the payment transaction carried out via the PSP.

Apart from the blocking reasons to trigger a refund you may have also come across the following error message when trying to trigger a refund:


In that case you have an available credit in the customers contract ledger and are able to trigger a refund by clicking the "Refund" Button. But you also see given the error message on top of the screen that the refund failed. For further investigation why the refund failed, please take a closer look into the payment log details to that refund. Here you should see the transaction listed where billwerk tried to perform the refund. Open the transaction log details to also see the triggered refunds details.


In the details you can see that there have been 2 attempts to refund the amount of 3.39 EUR and both of them failed. To get further details on the refund itself please click the according ID to open the detailed logs and find further error details.


In the detailed Logs of the refund you should have an error message provided. Please, try to evaluate the description and if given also look up the error code. In this example the refund couldn't be performed due to wrong parameters and because a status change of the payment transaction is not possible. Reason here for was actually case 3.


Interpreting the error message might not always be easy and self-explaining. In a lot of cases looking up the error code in the documentation of the PSP (in this example error code 950) provides more help on how to proceed. If this is also not the case please also try to contact the PSP directly and provide the ID of the payment and refund transaction as well as the error code and ask for further help.

To get the whole picture of what has been changed within the customers contract and see the relation of what might have caused any payment issue it is always helpful to have a look into the audit logs and set a filter on the customer and/ or contract Id in addition. By that you see the whole history of what happened and get a conclusion.