Notifications

❗️

Important

Using notifications is mandatory.

Why should you use notifications?

It is possible that your system does not receive a result (for example, the final redirect is not performed). This happens because of the asynchronous nature of the payment process and the information being passed through the consumer's computer/web browser. As a result, the consumer may be charged without receiving the goods. You can constantly poll the Payment Gateway using the GETTXSTATUS call to get a final result. This is suboptimal for the following reasons:

Timing: You may query a locked transaction, resulting in delayed responses.

Performance: While a single GETTXSTATUS call is negligible, the performance impact of many clients querying the system is noticeable.

Concurrency: GETTXSTATUS calls add to your maximum concurrency. This limits the concurrent processing capacity.

Sending notifications

The Payment Gateway sends notifications whenever the state of a transaction changes to either SUCCEEDED or FAILED. These notifications are transmitted to a script running on your web server using an HTTP(S) POST request. The Payment Gateway expects a response which verifies that you received the complete notification without errors. In case of a transmission failure, The Payment Gateway retransmits the notifications in defined intervals for a determined maximum number of retries.

After a successful receipt, call GETTXSTATUS to get the transaction status.

The process

The protocol

Notification

The notification is sent as a standard HTTP POST (urlencoded) request, containing the following fields:

FieldDescription
txidThe Payment Gateway transaction id
finaltimestampThe timestamp (ISO8601) when the transaction reached a final status
sha256hashThe hash used to verify that the request is valid. The algorithm to create this hash is:
sha256(sha256(txid+"."+finaltimestamp)+"."+notificationsecret)

The notification secret is provided by the account manager.

Response

📘

Information

If a notification cannot be delivered, the Payment Gateway retries every 15 minutes, up to 192 times.

Notification receiver example (PHP)

The following script receives notifications and replies accordingly. Please note that message processing is client-specific and not shown here.

<html>
    <body> 
        Access denied     
        
        <?php
          $secret = "mysecret";
          if ($_post["sha256hash"] ==
            hash('sha256',
                hash('sha256', $_POST["txid"].".".$_POST["finaltimestamp"]).
                    ".".$secret))
           {
             if (write_information_to_persistent_store() == OK)
             {
                print "RECEIVED OK";
              }
           }
          ?>
    </body>
</html>

Notifications FAQ

Why is there no transaction status in the notification?

Notifications only contain basic information, protected by sha256hash . You must always call GETTXSTATUS to get the current status. We recommend queueing these calls, since notifications may come in bulk, for example, upon PPRO processing a bank's or payment scheme's financial reconciliation.

Can I have a transaction status in the notification?

No. Not having the status in the notification is a conscious design decision. Providing it would mislead programmers to use (and trust) it to avoid the extra GETTXSTATUS call.

Why am I receiving the same notification over and over again?

Make sure you meet the protocol requirements as defined in The protocol. Make sure you meet the 30 seconds requirement. This means you must separate the receiving and processing of the message.

Why am I not receiving a notification, even though I am expecting to receive one?

As the notification service is a highly available key component of the Payment Gateway, this usually indicates a problem on your side.

Common reasons:

  • There is nothing to notify about, e.g. the state change in question doesn’t trigger a notification.
  • Your firewall doesn’t allow the Payment Gateway to access the notification URL. Please whitelist all Payment Gateway notification IPs to allow access. You can also avoid whitelisting overall since no sensitive data is provided in notifications.
  • You’re using a local IP address or hostname that can’t be resolved (such as 127.0.0.1, 10.10.1.1, localhost, mydomain.local) as a notification URL. Please use a hostname that points to a routed IP address and can be resolved using a public DNS server.