Transaction advice

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)

📘

In case "Only include authorised transactions (status 'A' or 'H')" option is not selected, then decline transaction data will also be sent along with authorised entries.

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.

Card codes

Transaction class codes

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.

Data security

To authenticate a transaction advice message, a SHA1 hash check can be done using key transaction, card, and billing information fields. The process includes these steps:

1. Concatenate Field Values: Combine the values of the specified fields using the secret key, separating each value with a colon (:). Make sure not to include the labels.

<secretkey>:<tran_store>:<tran_type>:<tran_class>:<tran_test>:<tran_ref>:<tran_prevref>:<tran_firstref>:<tran_currency>:<tran_amount>:<tran_cartid>:<tran_desc>:<tran_status>:<tran_authcode>:<tran_authmessage>

<secretkey>:<card_code>:<card_payment>:<bin_number>:<card_issuer>:<card_country>

<secretkey>:<bill_title>:<bill_fname>:<bill_sname>:<bill_addr1>:<bill_addr2>:<bill_addr3>:<bill_city>:<bill_region>:<bill_country>:<bill_zip>:<bill_email>:<bill_phone1>

• If any field value is missing, use an empty value in its place in the concatenated string.
• Convert any percent-encoded characters (e.g., %20) to their corresponding characters.

2. Generate the SHA1 Hash: After concatenating the values, create the SHA1 hash of the resulting string.
3. Compare Hashes: Match the generated hash with the ones in the tran_check, card_check, or bill_check fields respectively. This confirms the transaction’s integrity and authenticity.

📘

'tran_order' is not sent by default. If you need the order reference in the response, please send a request to [email protected]. If 'tran_order' is enabled, then its value needs to be placed like <tran_firstref>:<tran_order>:<tran_currency>

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