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