Online Payment Notifications Handling (IPN v2)

Notification Structure

Signature Calculation

Signatures are generated by concatenating the values of the type field, notification_id, all received parameters (except signature) to the API in the order from the tables below, separating them with the separator | and adding the key available in the Client Panel for the service at the end. Hashing must be done using sha256.

The basic string to be hashed should look like this:

type|notification_id|date|data_value1|data_value2|data_valueN|key

Example method of generating a signature for the following sample data:

• type = example:type
• notification_id = 0196bf93-aca4-7253-8a2d-0941a037f25b
• date = 2025-05-20T16:36:07Z
• data has fields:
  • status = transaction_paid
  • amount (object)
    • amount.currency = PLN
    • amount.value = 5.25
  • transaction_id = 123123123123
  • meta = test
• key = keyFromPanel

Joining all elements correctly will look like this:

example:type|0196bf93-aca4-7253-8a2d-0941a037f25b|2025-05-20T16:36:07Z|transaction_paid|PLN|5.25|123123123123|test|keyFromPanel

If any field in the documentation informs us that it may not occur if e.g. it was not passed during payment initiation, we completely skip this element when generating the signature.

Looking at the example, let's assume that the meta field may not occur and actually does not occur. In this case, the concatenation of elements will look like this:

example:type|0196bf93-aca4-7253-8a2d-0941a037f25b|2025-05-20T16:36:07Z|transaction_paid|PLN|5.25|123123123123|keyFromPanel

This prepared string is passed to the sha256 hashing function. SimPay sends the signature as a lower-case string.

Example of generating signature value in selected languages and SDK:

<?php

class SimPaySignatureValidator
{
    public function isValid(): bool
    {
        $payload = json_decode(@file_get_contents('php://input'), true);
        if (empty($payload)) {
            return false;
        }

        $data = $this->flattenArray($payload);
        $data[] = 'SERVICE_IPN_KEY';

        $signature = hash('sha256', implode('|', $data));

        return hash_equals($signature, $payload['signature']);
    }

    private function flattenArray(array $array): array
    {
        unset($array['signature']);

        $return = [];

        array_walk_recursive($array, function ($a) use (&$return) {
            $return[] = $a;
        });

        return $return;
    }
}

$validator = new SimPaySignatureValidator();
if(!$validator->isValid()) {
  http_response_code(403);
  echo 'INVALID_SIGNATURE';
  die();
}

// rest of ipn

Available Global Data Types:

1. TransactionStatusEnum - Enum(transaction_new, transaction_confirmed, transaction_generated, transaction_paid, transaction_failed, transaction_expired, transaction_canceled, transaction_refunded)
2. RefundStatusEnum - Enum(refund_new, refund_pending, refund_completed, refund_rejected, refund_failed)

Available Values in type Field:

transaction:status_changed - transaction status change

Data in the data field:

Example sent event (for ipn key = UwSkKiIwlxIeOMF8MIq9iDkQWBTtjoJQ):

{
  "type": "transaction:status_changed",
  "notification_id": "0196fec6-7a61-7219-9458-bcc45237c252",
  "date": "2025-05-23T22:12:22+02:00",
  "data": {
    "id": "dbc87423-b121-4ad4-977f-b63c3d3831e8",
    "payer_transaction_id": "Q68KLAKN",
    "service_id": "e65c7519",
    "status": "transaction_failure",
    "amount": {
      "final_currency": "PLN",
      "final_value": "8.00",
      "original_currency": "PLN",
      "original_value": "8.00",
      "commission_system": "0.06",
      "commission_partner": "7.94",
      "commission_currency": "PLN"
    },
    "control": "3e63e31d-f08d-4942-a223-3bad2dce8096",
    "payment": {
      "channel": "blik",
      "type": "blik"
    },
    "customer": {
      "country_code": null
    },
    "created_at": "2024-08-10T15:41:50+02:00"
  },
  "signature": "095a7be5d77c4bab667dbd0f35d9b1cb0c9cec50d8af42842cc37a95b233925e"
}

transaction:refund_status_changed - refund status change

Data in the data field:

Example sent event (for ipn key = UwSkKiIwlxIeOMF8MIq9iDkQWBTtjoJQ):

{
  "type": "transaction_refund:status_changed",
  "notification_id": "0196ff00-376d-7399-a457-d166c9adf073",
  "date": "2025-05-23T23:15:26+02:00",
  "data": {
    "id": "0194837c-69df-71dd-adff-4b3058f3fb58",
    "service_id": "e65c7519",
    "status": "refund_completed",
    "amount": {
      "currency": "PLN",
      "value": "1.00",
      "wallet_currency": "PLN",
      "wallet_value": "1.00"
    },
    "transaction": {
      "id": "e568d9ba-a85a-444c-87c4-3b1e431428d1",
      "payment_channel": "paysafecard",
      "payment_type": "paysafe"
    }
  },
  "signature": "835819c5720c74f01b8d10a58b2dc43185f05379ea26f25a15158061f3bce10c"
}

ipn:test - test notification

This notification can be sent from the Client Panel.

Data in the data field:

Example sent event (for ipn key = UwSkKiIwlxIeOMF8MIq9iDkQWBTtjoJQ):

{
  "type": "ipn:test",
  "notification_id": "0196fece-c3e7-71ba-ac8a-ac64056d7d6b",
  "date": "2025-05-23T22:21:25+02:00",
  "data": {
    "service_id": "e65c7519",
    "nonce": "01JVZCXGZ77DJTM08WMSX34ETQ"
  },
  "signature": "02df1a420def7e5de9b316d2bd1ef70796f50abc461561a85bb1243f0a08984d"
}