Logging and Debugging

The SDK provides error and debug information which you can catch and write to your log.


The SDK throws a heidelpayPHP\Exceptions\heidelpayApiException whenever an error is returned by the API.

The exceptions are thrown in the following cases:

  • there has been an error connecting to the API or to the payment core
  • there has been an error executing a request

In order to find out what error occurred you should catch this exception and write it to your error log as well as show the clientMessage to your customer. Please refer to the following sections for details on the exception information and how to use it. General information on errors can be found here.

// Catch heidelpayApiException

try {
    // your call to the api
} catch (\heidelpayPHP\Exceptions\HeidelpayApiException $ex) {
    //  write $ex->getMessage(), $ex->getCode() and $ex->getErrorId() to your error log
    //  redirect your customer to a failure page and show $ex->getClientMessage()

Please refer to the annotations of the SDK methods you are using in order to find out whether it throws the heidelpayPHP\Exceptions\heidelpayApiException and you have to add the try catch block.

// Example throws annotation

 * @throws heidelpayApiException


The message should be written to your error log (together with the code) because this is a specific message telling you exactly what the problem is. This will help with the debugging of potential errors. You can access it by calling getMerchantMessage() on the exception.


The clientMessage contains an error message you should show to the client e. g.on the failure page. You can access it by calling getClientMessage() on the exception.


The code is a specific error code which helps to identify the error you are experiencing and is very useful for our support team. This should also be written to your error log in combination with the exception message. You can access it by calling getCode() on the exception.


The errorId is a unique identifier of this specific error situation. It can help our support team to find the error within our logs.

Runtime Exceptions

In some cases the SDK throws a RuntimeException. This is the case when there is an error using the SDK, e. g. the key has the wrong format or is not the private-key or when a necessary resource does not exist.

We recommend you to catch those exceptions and handle them by writing them to your error-log and showing a generic error-message to the customer.

// Catch \RuntimeException

try {
    // your call to the api
} catch (\RuntimeException $ex) {
    //  write $ex->getMessage() to your error log
    //  redirect your customer to a failure page and show a generic message

Debug log

You can enable debug mode on your heidelpay object in order to visualize the HTTP requests performed to to the API as well as the raw responses. In order to use this functionality please do the following.

  1. Enable debug mode
  2. Create your own debug handler class implementing the heidelpayPHP\Interfaces\DebugHandlerInterface
  3. and inject it into the heidelpay object

You can use this to write into your debug log.

// Implement your own debug handler

namespace Your<br>amespace;
use heidelpayPHP\Interfaces\DebugHandlerInterface;

class TestDebugHandler implements DebugHandlerInterface
    public function log ($message) {
        // write the message to your log
// Enable Debug Mode and inject your debug handler

$heidelpay = new \heidelpayPHP\Heidelpay('s-priv-xxxxxxxxxx');

$heidelpay->setDebugHandler(new \Your\Namespace\TestDebugHandler());
Keep in mind that keeping a debug log can cause a significant amount of data over time.
Make sure to disable debug mode if you are done debugging.

Verbose Curl output

In order to enable verbose curl output you can set the environment variable heidelpay_MGW_CURL_VERBOSE to true.