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)

 

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

Type	Details
Sale	A standard online transaction. If authorised the relevant amount will be debited from the customers’ card.
Void	A 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.
Refund	Used to credit an amount back to the customer. The refund amount may be the same as or less than the original Sale amount.
Refund Reversal	This 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.
Auth	A 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.
Capture	Used to debit funds that have been previously reserved using an auth transaction. This completes the transaction processing.
Capture Reversal	This 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:

Field	Description	Notes
tran_store	Your store ID
tran_type	Transaction type	See the transcation type and class lists below
tran_class	Transaction class
tran_test	Test mode	0 = Live transaction, 1 = Test
tran_ref	Transaction reference	Allocated by the Innovate Payments gateway for this transaction
tran_prevref	Reference 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_firstref	Reference 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_currency	Transaction currency	The 3 character ISO code for the currency
tran_amount	Transaction amount
tran_cartid	Cart ID	The cart ID and description that were provided with the original sale/auth transaction.
tran_desc	Purchase description
tran_status	Transaction 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_authcode	Authorisation code	If 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_authmessage	Authorisation message
tran_check	Data signature check	See the section on data security below.
bill_title	Title (Mr, Mrs, etc)
bill_fname	Forenames
bill_sname	Surname
bill_addr1	Street address – line 1
bill_addr2	Street address – line 2
bill_addr3	Street address – line 3
bill_city	City
bill_region	Region/State
bill_country	Country	2 character ISO code
bill_zip	Zip/Area/Postcode
bill_phone1	Phone number
bill_email	Email address
xtra_	Extra data fields	Copied from the purchase request

Transaction type codes

Code	Transaction type
sale	Sale
void	Void
refund	Refund
revrefund	Refund Reversal
auth	Auth
release	Release
capture	Capture
revcapture	Capture Reversal

Transaction class codes

Code	Transaction type
ecom	E-Commerce
moto	Mail Order / Telephone Order
cont	Continuous 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	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

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

Status	Code	Message
A	Set by issuer	Authorised
H	Set by issuer	Authorised, but placed on hold. Manual inspection required
E	01	Invalid request
E	02	Transaction cost or currency not supplied
E	03	Cart ID not set
E	04	Invalid store ID
E	05	Transaction cost or currency not valid
E	06	Invalid transaction mode
E	07	Card expiry not supplied
E	10	Card number not supplied
E	11	Invalid card number
E	12	Card expired
E	14	Card type mismatch
E	15	Invalid card security code (CVV)
E	16	Card security code (CVV) not supplied
E	17	Name not valid/not supplied
E	18	Address not valid/not supplied
E	19	Country not valid/not supplied
E	20	IP address not valid/not supplied
E	21	Card/Currency/Class combination not supported
E	22	Invalid transaction reference
E	23	Amount differs from original
E	24	Currency differs from original
E	25	Original transaction not authorised
E	26	Original transaction already voided
E	27	Original transaction mismatch
E	28	Invalid start date
E	29	Amount greater than available balance
E	30	Card details differ from original
D	31	Not authorised
D	32	Original transaction cannot be voided
C	33	Transaction cancelled
D	34	No response
E	35	Unable to refund
E	36	Previous transaction is on hold
D	37	Blocked by acquirer
E	38	Invalid expiry date
E	39	Invalid expiry date
E	40	Invalid transaction type
D	41	Insufficient funds
D	42	Card security code (CVV) mismatch
E	43	Email not valid/not supplied
E	44	Phone number not valid/not supplied
E	45	Transaction mode differs from original
D	46	3DSecure authentication not available for this card
D	47	3DSecure authentication rejected
E	48	Description not set
D	49	Sold out
E	50	Card is for ATM use only
D	51	Transaction part 1 not authorised
D	52	Transaction part 2 not authorised
X	53	Authorisation expired
E	54	Transaction part not specified
E	55	Unable to access transaction part
E	56	Duplicate transaction
D	57	Continuous authority not available on referenced transaction
E	58	Error connecting to service provider
E	59	Request aborted
E	60	Verification failed
D	61	Not authorised
D	62	Not authorised
D	63	Address verification (AVS) mismatch
D	64	Card security code (CVV) and address (AVS) mismatch
D	65	Card is not enabled for e-commerce
D	66	Card cancelled
D	67	Transaction not permitted by issuer
D	68	No suitable account
D	80	Not authorised Card Filter module. Message text can be changed
D	90	Not authorised
D	91	Not authorised
D	92	Not authorised
D	93	Card limits exceeded
D	94	Not authorised
D	95	Not authorised
D	96	Not authorised
E	98	Internal system error
E	99	Unknown 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