1. Home
  2. Developers
  3. Transaction Advice Service

Transaction Advice Service

Introduction

The Transaction Advice Service is a server-to-server message system which can be sent for any transaction type.

This can be used to allow your systems to be informed of events such as refunds or voids being processed.

You can select which transaction types you want to receive messages for. Any transaction which matches a selected type will be sent using the message service – this includes transactions processed through any payment processing API such as the Hosted Payment Pages or Remote, and also includes any transactions that are manually processed through the Merchant Administration System.

Each message is sent in the form of a HTTP POST 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)

transaction-advice-config

 

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.

Transaction types

TypeDetails
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.
ReleaseUsed 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.

Message format

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

FieldDescriptionNotes
tran_storeYour store ID
tran_typeTransaction typeSee the transcation type and class lists below
tran_classTransaction class
tran_testTest mode0 = Live transaction, 1 = Test
tran_refTransaction referenceAllocated by the Innovate Payments gateway for this
transaction
tran_prevrefReference for previous
transaction
For 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 sequence
In 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_currencyTransaction currencyThe 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_fnameForenames
bill_snameSurname
bill_addr1Street address – line 1
bill_addr2Street address – line 2
bill_addr3Street address – line 3
bill_cityCity
bill_regionRegion/State
bill_countryCountry2 character ISO code
bill_zipZip/Area/Postcode
bill_phone1Phone number
bill_emailEmail address
xtra_Extra data fieldsCopied from the purchase request

Transaction type codes

CodeTransaction type
saleSale
voidVoid
refundRefund
revrefundRefund Reversal
authAuth
releaseRelease
captureCapture
revcaptureCapture Reversal

Transaction class codes

CodeTransaction type
ecomE-Commerce
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 keytran_storetran_typetran_class
tran_testtran_reftran_prevreftran_firstref
tran_currencytran_amounttran_cartidtran_desc
tran_statustran_authcodetran_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.

Transaction status codes

StatusCodeMessage
ASet by issuerAuthorised
HSet by issuerAuthorised, but placed on hold. Manual inspection required
E01Invalid request
E02Transaction cost or currency not supplied
E03Cart ID not set
E04Invalid store ID
E05Transaction cost or currency not valid
E06Invalid transaction mode
E07Card expiry not supplied
E10Card number not supplied
E11Invalid card number
E12Card expired
E14Card type mismatch
E15Invalid card security code (CVV)
E16Card security code (CVV) not supplied
E17Name not valid/not supplied
E18Address not valid/not supplied
E19Country not valid/not supplied
E20IP address not valid/not supplied
E21Card/Currency/Class combination not supported
E22Invalid transaction reference
E23Amount differs from original
E24Currency differs from original
E25Original transaction not authorised
E26Original transaction already voided
E27Original transaction mismatch
E28Invalid start date
E29Amount greater than available balance
E30Card details differ from original
D31Not authorised
D32Original transaction cannot be voided
C33Transaction cancelled
D34No response
E35Unable to refund
E36Previous transaction is on hold
D37Blocked by acquirer
E38Invalid expiry date
E39Invalid expiry date
E40Invalid transaction type
D41Insufficient funds
D42Card security code (CVV) mismatch
E43Email not valid/not supplied
E44Phone number not valid/not supplied
E45Transaction mode differs from original
D463DSecure authentication not available for this card
D473DSecure authentication rejected
E48Description not set
D49Sold out
E50Card is for ATM use only
D51Transaction part 1 not authorised
D52Transaction part 2 not authorised
X53Authorisation expired
E54Transaction part not specified
E55Unable to access transaction part
E56Duplicate transaction
D57Continuous authority not available on referenced transaction
E58Error connecting to service provider
E59Request aborted
E60Verification failed
D61Not authorised
D62Not authorised
D63Address verification (AVS) mismatch
D64Card security code (CVV) and address (AVS) mismatch
D65Card is not enabled for e-commerce
D66Card cancelled
D67Transaction not permitted by issuer
D68No suitable account
D80Not authorised
Card Filter module. Message text can be changed
D90Not authorised
D91Not authorised
D92Not authorised
D93Card limits exceeded
D94Not authorised
D95Not authorised
D96Not authorised
E98Internal system error
E99Unknown error

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_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

 

Updated on August 25, 2016

Related Articles