Need help?

Transaction advice


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:

tran_storeYour store ID
tran_typeTransaction typeSee the transcation type and class lists below
tran_classTransaction class
tran_testTest mode (0 = Live transaction, 1 = Test)0 = Live transaction, 1 = Test
tran_refTransaction referenceAllocated by the Telr gateway for this transaction
tran_prevrefReference for previous transactionFor transactions which are a follow-up transaction, such as a void, this contains the transaction reference of the transaction being voided. For an initial transaction, such as a sale or auth, this will be the same as the tran_ref
tran_firstrefReference for the first transaction in a sequencen a multi-transaction sequence, such as a refund being performed on a capture transaction, this will contain the reference to the initial auth transaction.
tran_orderOrder ReferenceThis parameter is relevant whenever the payment link is generated using the 'order.json' API. This field is optional, configuration should be enabled if its required on the message.
tran_currencyTransaction currency (3 character ISO code for the currency)The 3 character ISO code for the currency
tran_amountTransaction amount
tran_cartidCart IDThe cart ID and description that were provided with the original sale/auth transaction.
tran_descPurchase description
tran_statusTransaction status‘A’ or ‘H’ indicate an authorised transaction. Any other value indicates that the request could not be processed. Transactions with status H have been authorised but are on hold.
tran_authcodeAuthorisation codeIf the transaction was authorised, this contains the authorisation code from the acquirer. Otherwise it contains an error code. See the response codes section for more details.
tran_authmessageAuthorisation message
tran_checkData signature checkSee the section on data security below.
bill_titleTitle (Mr, Mrs, etc)
bill_addr1Street address – line 1
bill_addr2Street address – line 2
bill_addr3Street address – line 3
bill_countryCountry2 character ISO code
bill_phone1Phone number
bill_emailEmail address
xtra_Extra data fieldsCopied from the purchase request

Transaction types

SaleA standard online transaction. If authorised the relevant amount will be debited from the customers’ card.
VoidA method used to cancel a sale transaction. This can only be done within a short time after the sale transaction was processed. The void amount is always the same as the original sale amount.
RefundUsed to credit an amount back to the customer. The refund amount may be the same as or less than the original Sale amount.
Refund ReversalThis can be used to cancel a refund, and can only be done within a short time after the refund was processed. Not all acquirers support this transaction type.
AuthA pre-authorisation transaction. This is similar to a sale, but the amount is not immediately debited from the customers’ card. Instead the amount is reserved on that card, and can then be debited at a later date using a capture transaction. Until the capture transaction is processed, no funds will be debited. Release Used to release any funds that have previously been reserved by an auth transaction. No funds are debited from the card, and the capture option can no longer be used.
CaptureUsed to debit funds that have been previously reserved using an auth transaction. This completes the transaction processing.
Capture ReversalThis can be used to cancel a capture transaction, and can only be done within a short time after the capture was processed. Not all acquirers support this transaction type.

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

CodeTransaction Type
motoMail Order / Telephone Order
contContinuous Authority

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
















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