Introduction

Transaction Advice Service is a server-to-server messaging system designed to facilitate communication regarding various transaction types. The service enables your systems to receive notifications about important events such as refunds or voids being processed.

You have the flexibility to choose the specific transaction types for which you want to receive messages. Once selected, the message service will deliver relevant information for matching transactions. This includes transactions processed through payment processing APIs like Hosted Payment Pages or Remote, as well as manually processed transactions through the Merchant Administration System.

Each message is transmitted as an HTTP POST request to a pre-configured URL.

Service configuration

From within the Merchant Administration System, select either the ‘Payment Page’ or ‘Security’ menu, and click on the ‘Transaction advice’ option.

This will display the configuration page, which allows you to select which transaction types you want to receive advice messages for. You can also choose to limit the advice messages to only transactions which have been authorised (transaction status A or H)

You will need to supply the URL that is to be used by the advice service. This URL must use either the HTTP or HTTPS protocol and must be on either port 80 or port 443. The connection that is made to the URL is a direct server-to-server connection, there is no browser involved in the request. The URL used must be accessible over the internet.

Message format

Transaction advice messages are sent using the HTTP POST method. Messages will contain the following fields:

Transaction types

In some situations, a transaction may be changed from a Sale to an Auth. If, for example, the original transaction request was for a Sale but the anti-fraud system has flagged the transaction for inspection then it may be converted into an Auth transaction which then requires a Capture in order to be completed.

If your system uses the Sale transaction method, then you should also allow for advice messages relating to Auth, Capture and Release transactions.

Transaction class codes

Data security

You can authenticate a transaction advice message by performing a SHA1 hash check on the tran_ fields, and comparing the result to the value provided in the tran_check field.

The configured secret key and the field values are concatenated, separated by the ‘:’ character. They must be used in the following order:

secret key

tran_store

tran_type

tran_class

tran_test

tran_ref

tran_prevref

tran_firstref

tran_order

tran_currency

tran_amount

tran_cartid

tran_desc

tran_status

tran_authcode

tran_authmessage

Message delivery

The transaction advice message will be generated as soon as the transaction processing has been completed. If there is an error whilst attempting to deliver the message, then there will be a short delay and a second attempt will be made. Up to 4 attempts in total will be made, with an increasing delay between each attempt.

Your systems must indicate successful receipt of the message by using the HTTP 200 OK response code. Other response codes will be treated as a failure and the message will be repeated.

Message authentication - PHP example

This is an example of authenticating a transaction advice message using the method described in the Data security section.

function SignData($post_data,$secretKey,$fieldList) {
  $signatureParams = explode(',', $fieldList);
  $signatureString = $secretKey;
	
  foreach ($signatureParams as $param) {

    if (array_key_exists($param, $post_data)) { 
      $signatureString .= ':' . trim($post_data[$param]);
    } else {
      $signatureString .= ':';
    } 
	}
	return sha1($signatureString); 
}

$secret_key='[Your Secret Goes Here]';

// Create a check value based on the secret key and the data received.
// To make the following more readable, the field list has been split over two lines
$check=SignData($_POST,$secret_key, 'tran_store,tran_type,tran_class,tran_test,tran_ref,tran_prevref,tran_firstref,tran_order,tran_currency,tran_amount,tran_cartid,tran_desc,tran_status,tran_authcode,tran_authmessage'

// Check that the signature in the message matches the expected value
if (strcasecmp($_POST['tran_check'],$hash_check)!=0) {
	// Hash check does not match. Data may have been tampered with. 
  die('Check mismatch');
}
                
// Hash check OK, use details supplied in POST data to determine what action to take 
// tran_status:
// A = Authorised, H = Authorised but on hold, any other character = not authorised