Logging and Debugging

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

API Errors

The SDK throws a UnzerSDK\Exceptions\UnzerApiException whenever an error is returned by the API.

The exceptions are thrown in the following cases:

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

To identify the error, you should catch this exception and write it to your error log as well as show the clientMessage to your customer. To learn more about the exception information and how to use it, go to the error code reference page.

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

Refer to the annotations of the SDK methods you are using in order to find out whether it throws the UnzerSDK\Exceptions\UnzerApiException and you have to add the try catch block.

 * @throws UnzerApiException


This 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.


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


This 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 ID is a unique identifier of this specific error situation. It helps our support team to find the error within our logs. In addition it is possible to fetch the specific error at a later time (this feature is not yet available in the PHP-SDK).

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.

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 Unzer 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. Create your own debug handler class implementing the UnzerSDK\Interfaces\DebugHandlerInterface
  2. Inject it into your Unzer object
  3. Enable debug mode on your Unzer object

You can handle the message in the log method of your debug handler and write it into your debug log.

namespace Your\Namespace;
use UnzerSDK\Interfaces\DebugHandlerInterface;

class TestDebugHandler implements DebugHandlerInterface
    public function log ($message) {
        // write $message to your log
$unzer = new UnzerSDK\Unzer('s-priv-xxxxxxxxxx');

$unzer->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

To enable verbose curl output, you can set the environment variable UNZER_PAPI_CURL_VERBOSE to true.