Ensuring End To End Transaction Integrity

Transaction integrity can be seen as ensuring that all players within an individual iVeri transaction agree on its outcome. When a Card Holder gets his statement from his Issuer, it must correspond to his instruction to the merchant for a corresponding transaction. When transaction integrity is compromised either willfully (fraud) or unintentionally, it can result in a disputed transaction with legal impacts.

 

Individual transactions

 

Void

A “Void” of a previous transaction request is a command to ignore (i.e. cancel the effects of) a previous (recently submitted) transaction request. When a merchant receives a successful response for a transaction request, and thereafter “something goes wrong”, then the Merchant has the option to “void” the transaction.


Examples of “something goes wrong” are:

  1. communications error between merchant and cardholder
  2. printer could not print the invoice
  3. problem accessing merchant database



A merchant can also call “void” when s/he does not know whether a response was received from the iVeri Gateway (for example a power failure). A successful void (cancellation) typically results in the transaction not being shown on the merchant nor the cardholders’ statements.Transaction sets are settled as a group at predefined periods (cycle cut off time).


A “Void” can only be successful if the transaction being cancelled has not passed its cut off time. Therefore, when a void is required, it should be done as soon as possible (particularly since cycle cut off time is out of the control of a merchant). If the void request is submitted too late, then the void request will fail, and a separate reversal transaction would be required.


Enterprise users call Void with the syntax like:    

enterprise.prepare("Transaction", "Void", applicationID, mode);

A Void request must set one of the following parameters: OriginalMerchantTrace or OriginalRequestID, for example:

enterprise.setTag("OriginalRequestID", requestID)

Result Code

Result Description

Action

0

Void successful

Transaction successfully voided.

13

Void unsuccessful

Too late to void the transaction.

1

Timeout

Void can be automatically retried a minute later

\9

Unable to process

Void can be automatically retried a minute later

255

General Error (Exception)

Void can be retried a minute later after the problem given in the ResultDescription is fixed (which may require manual intervention)


A Void has one of the following responses


If the iVeri Gateway receives a Void request referring to a MerchantTrace or RequestID that it has no knowledge of, then “Void successful” is replied.

A merchant implementing “Void” command requires a void repeat mechanism which only ends upon receiving a “Void successful” or “Void unsuccessful” response.


If you intend to resubmit the transaction, then you can either:

  • Submit it immediately using a new MerchantReference, and have a separate process or thread to manage the sending of Voids (which may only be sent a few minutes later)
  • Implement a mechanism where the transaction is only sent after the void process for the transaction is completed.
  • Implement a retry mechanism discussed below without using a Void.


Retry 

A merchant may want to retry a transaction after receiving an unsuccessful response.


If a merchant is not sure what the iVeri Gateway replied previously, then they might even want to retry after a receiving a successful response. Typically, a retry is relevant after receiving one of the following results on a transaction request:

Result Code

Result Description

Action

1

Timeout

Transaction can be automatically retried a minute later

9

Unable to process

Transaction can be automatically retried a minute later

255

General Error (Exception)

Transaction can be retried a minute later after the problem given in the ResultDescription is fixed (which may require manual intervention)




A retry is relevant after the above responses because then one would expect a different result code. Nevertheless, a retry is supported after other result codes (eg Successful / Denied / Hot card / Black card) for when there is some change that could cause the transaction to be approved, or when the original reply is unknown to the merchant.

The following shows three different approaches to retries. A retry is only recommended in using the first approach, however all these approaches are supported.


Retry with client recorded Merchant Trace

A merchant records transaction information in their database before they send a transaction request to the iVeri Gateway. The database index of this request is given as the MerchantTrace (to uniquely identify an individual transaction request).


The merchant retries a previous transaction with the same MerchantTrace, MerchantReference, Command, Amount, PAN parameters as previously.


The possible responses are:

  1. If the previous attempt was successful, a successful result is returned.
  2. If the previous attempt was unsuccessful, the transaction request is retried.
  3. If the previous attempt is in process, then “Transaction in process” (ResultCode 9 : Unable to process transaction) is returned. The retry can then be reattempted a minute later.

If the merchant is only performing debits, and there is a database table where the unique identifier corresponds to the reference number given to a card holder, then it may make sense for the MerchantReference and MerchantTrace to be the same.


NB. The NedbankBICISO provider does not allow a follow-up debit to be Voided. If a transaction cannot be Voided and no response is received from the iVeri Gateway, the transaction has to be retried instead. For this, all transactions done with the ApplicationID has to be with MerchantTrace. Once a response is received for the follow-up debit, a follow-up credit has to be performed to undo the debit if it was successful.


Retry without Merchant Trace

It is not recommended to retry a transaction without a MerchantTrace.

Nevertheless, if the same Command, Amount, PAN, and MerchantReference as a previous transaction are specified (with no Merchant Trace given), then the possible responses are:

  • If the previous attempt was successful, then "A transaction with the same MerchantReference was successful" (Result Code 255: Duplicate MerchantReference).
  • If the previous attempt was unsuccessful, the transaction request is retried.
  • If the previous attempt is in process, then “Transaction in process” (Result Code 9 : Unable to process transaction) is returned. The retry can then be reattempted a minute later.

Retry with irrelevant Merchant Trace (or irrelevant Merchant Reference)

A merchant may be tempted to bypass the various checking mechanisms within the iVeri Gateway and just send the current date time stamp as the value for the MerchantTrace or MerchantReference. In this manner there is more chance that a transaction request will be successful. However, there is also more chance that the card holder will be double debited!


For merchants who cannot store an individual request identifier before sending the request to the iVeri Gateway, see section 9.3.3 on “Recurring transaction checking”.


Enquiry

A merchant with a doubt of the current status of a transaction can determine its status by:

  1. Performing a “Transaction lookup” within iVeri BackOffice
  2. Download a “Reconciliation file” (can be automated with iVeri FileTransfer) and compare records.
  3. Check an immediate notification mechanism (such as email for iVeriBatch clients, and SMS for iVeri Voice clients)
  4. Look in the logs for an exception message containing details of a misconfiguration or a coding error.


Conclusion

The Void Retry and Enquiry mechanisms discussed above help to either fix an individual transaction integrity or resolve the doubt around what the current state is. A merchant should automate at least one of these mechanisms. If a Void is unsuccessful, or the current state does not correctly correspond to the corresponding transfer of goods or services, then a follow up reversal transaction may be required.

Duplicate transactions

 

A problem of a duplicate transaction can occur if a merchant submits a previously successful transaction in a new request. A duplicate transaction of this nature is typically due to a user's unintentional mistake, e.g. pressing the “Submit” button twice, or submitting the same batch twice. It is responsibility of the merchant to ensure that a single transaction request is not submitted successfully more than once.

Nevertheless, the iVeri Gateway provides three mechanisms to protect against duplicate transactions. Specifying a unique MerchantTrace is a client-side configuration, while the latter to require contacting your local distributor.


Specify a unique Merchant Trace for each step in a Transaction Sequence

As mentioned in section 8.2, a MerchantTrace is a unique identifier for each request sent to the gateway and is an optional parameter. The MerchantTrace corresponds to a database index that was generated by the merchant before a request was sent to the gateway. In short, the MerchantTrace refers to a particular step in the transaction sequence.


The recommended way to control duplicate transactions is to always specify a MerchantTrace.  This has two benefits

  • If a merchant does not receive a reply to a request, then they have the choice of either voiding (9.2.1) or retrying (9.2.2) the transaction by using the same MerchantTrace.
  • A merchant can re-use a MerchantReference with different MerchantTraces for the same TransactionIndex.

Merchant Reference validity period

  • A MerchantReference is a unique identifier allocated by the merchant for a transaction sequence.
  • The MerchantReference validity period is a mechanism to protect merchants against undesired double debiting.
  • When performing an initial transaction request (i.e. no TransactionIndex provided), then if the last use of that MerchantReference (within a time period) was a successful, then a new Transaction is not performed.
  • When performing a follow up transaction (i.e. TransactionIndex provided), then if the last use of the MerchantReference (within a time period) of the same transaction type was successful, then a new Transaction is not performed. [Assuming the Transaction Type Repetition option has not been activated].
  • The default time period (Merchant Reference validity period) discussed above is 6 months. This can be changed to a minimum of 3 days.


Recurring transaction checking

The Recurring transaction checking period is an additional mechanism to protect merchants against undesired double debiting. By default, recurring transaction checking is disabled.When enabled, if a transaction is attempted with the same PAN, Amount, Command combination, but a different MerchantReference as a previously successful transaction done within a period, then the subsequent transaction request will fail.


If a Merchant explicitly requests this to be enabled, a time period (in seconds / minutes / hours) should be specified. This is typically 5 minutes.If a Merchant uses MerchantTrace to uniquely assign each individual transaction before submission to the iVeri Gateway, then this option should not be needed.This option is recommended for merchants who are forced to have poor state handling - for example those that generate a merchant’s reference in memory and only write to the database after sending a request to the iVeri Gateway.


Note that even when this option is disabled, an acquirer or issuer “downstream” may have their equivalent option enabled.

Specialized Techniques

 

Ping

The Ping command is primarily used to determine if the connection between the Merchant and the Acquirer is down. If the connection is down, then a Ping can be used to poll the iVeri Gateway to see when the status is back up.


The Ping command checks that:

  1. the merchant is communicating with the iVeri Gateway, and
  2. the merchant configuration is active, and
  3. the iVeri Gateway is online, and
  4. the iVeri Gateway is communicating with the acquirer.

This is different to checking network connectivity to the iVeri Gateway, where a network ping should be employed. The Ping takes an ApplicationID as a mandatory input parameter and is sometimes referred to as an ApplicationID Ping. As mentioned previously, an iVeri transaction involves communication between the following players:


Card Holder > Merchant > iVeri Gateway > Acquirer > Association > Issuer


An Acquirer can route a transaction to many different Associations, and an Association can route a transaction to many different https://issuers.an/ individual Transaction may reply to with a ResultCode of 1 or 9, meaning something is wrong between the Merchant and the card issuer. However, in such a case the merchant does not know if the problem was between the Acquirer and an Issuer (due to the routing of the PAN), or between the Merchant and the Acquirer. Although the individual transaction can be automatically retried, the Merchant may have some business rules for the case when the connection between the Merchant and the Acquirer is down, such as:

  1. go into Store and Forward mode
  2. notify a certain person
  3. show a different website page upon checkout


The Ping code of conduct:

  • The Ping command should be used only when a merchant needs to know the connection status between the Merchant and the Acquirer after either:
    • A service startup or a Transaction result code 1 or 9 (in doubt)
    • A Ping result code 1 or 9 (connection down)
  • A merchant should assume that the system is up. A Ping should not be used when the merchant thinks that the connection is up and the above conditions do not hold (i.e it should not be used to indiscriminately repeatedly poll the iVeriGateway)
  • When polling to see if the status is back up, a Ping may not be more frequent than every 20 seconds.
  • As a note, a merchant abusing the Ping command may have their use of it suspended


Ping Flow

The following is a diagram showing how a Ping can be effectively used.

“S&F” refers to “Store and Forward”, otherwise known as an Offline transaction.



Mod-10 Checking

PANs are checked for validity using the Luhn check-digit algorithm (also known as “Mod-10 checking”). If the iVeri Gateway receives a transaction that fails Mod-10 checking, then “Invalid Card Number” (ResultCode 14) if returned.

A merchant may perform Mod-10 checking up front before sending the transaction to the iVeriGateway.


The steps of the algorithm are described below (however there are many Mod-10 algorithms available for download on the Internet):

  1. Exclude the right-most digit from the calculation as this is the actual check-digit to be examined for validity.
  2. Starting with the 2nd to the last digit and moving right to left, alternatively multiply each successive digit by 2 and 1 respectively.
  3. Sum the integers comprising the product obtained from each of the calculations
  4. Subtract the resulting sum from the next higher multiple of ten (10). The resulting value is the desired account number check-digit.


The following example uses the PAN of: 4287 9478

Step

Description

Example

1

Example account number

 4     2     8     7     9     4     7     (8)

2

Multiplier

Products

x2    x1    x2    x1    x2    x1    x2

3

Sum the integers

 8  +  2 + (1+6) + 7 + (1+8) + 4 + (1+4) = 42

4

Derive the Check Digit

50 – 42 = 8


Card Number Checking

A merchant can perform multiple other checks on the PAN before initiating an iVeri Gateway transaction request.


This can be achieved by using the contents of files downloaded with the Commands:

  • HotCard
  • BINLookup
  • BINManagement
  • BlackCard

Transaction Terminology

 

An iVeri transaction is the combination of a transaction request (command: Authorisation, AuthorisationReversal, Debit, Credit, Void), and its corresponding response. A transaction sequence relates to the complete set of movement of goods and services and can include many related transactions.

An iVeri transaction involves communication between the following players:

Card Holder .>Merchant > iVeri Gateway > Acquirer > Association > Issuer


Unique Identifiers 

The players in an iVeri transaction generate the following fields to identify an individual transaction

Player

Individual transaction identifier

Merchant

Merchant Trace

iVeri Gateway

RequestID

Acquirer

Acquirer Reference

The players in an iVeri transaction generate the following fields to identify a transaction sequence:

 

Player

Transaction sequence identifier

Merchant

Merchant Reference

iVeri Gateway

Transaction Index


A MerchantReference is a unique identifier defined by the Merchant for a transaction sequence within a limited time period.  A MerchantReference is mandatory (for initial transaction requests and optional for follow-up requests). It typically corresponds to an invoice or ticket number (a transaction sequence).


A MerchantTrace is a unique identifier for each request sent to the gateway and is an optional parameter. The MerchantTrace corresponds to a database index that was generated before a request was sent to the gateway. In short, the MerchantTrace refers to a particular step in the transaction sequence.


Example is below:

For a Debit followed by an immediate Void (cancellation of ticket etc): The MerchantReference remains the same for both steps of the transaction sequence, while the MerchantTrace is different for the Debit and Void.

  • A single MerchantReference can be associated with many MerchantTrace's.
  • Similarly, a single TransactionIndex can be associated with many RequestID's.

TransactionIndex and Follow up transactions

TransactionIndex refers to the unique identifier given by the iVeri Gateway to a set of related transactions. When a TransactionIndex is an input parameter, then the command is referred to as a “follow up”. Therefore, the actions with the suffix “with TransactionIndex” mean “as a Follow up transaction”.


Follow up transactions by default use the same card information that was set in the initial transaction, however by default the follow up is considered a Card not present (Keyed) transaction.


Specifying one of the following mutually exclusive optional follow up input parameters can change the default behaviour:

  • Track2: The follow up transaction is considered a “Swiped” transaction
  • ExpiryDate: applicable to change when the original expiry date is in the past.

A follow up transaction can be done within 6 months of the original transaction. It can be used within a valid transaction sequence (eg a credit after a debit), but not for an invalid sequence (eg a debit following a credit). It cannot be used for a PIN based transaction.



Reversal transaction (Negative transaction)

A reversal transaction is an equal but opposite transaction to a previously successful transaction. This is typically a refund (i.e. a credit following a debit). A reversal typically results in both legs of the transaction being shown on the merchants and cardholders’ statements.


A merchant may initiate a reversal any time after a transaction was processed. A merchant can perform the reversal either by:

  • performing a follow up transaction within 6 months of the original iVeri transaction,
    or
  • initiating a new transaction request with the cardholder’s details.


A reversal should not be confused with a Void

Payment Mechanisms: Pan Vs Track2 Vs Pin

iVeri Gateway separates accounts into 3 different payment mechanisms:

  • PAN
  • Track2
  • PIN

To process a transaction with an account you need to know which payment mechanism you are going to use

Note that independent of the payment mechanism is used, the iVeri Gateway returns a dotted out “PAN” which can be used for display purposes.


PAN (also known as “Card Not Present” or “Keyed”)

The Primary Account Number (PAN) is given by the card holder to the merchant.

Either the card is not present with the Merchant, or the Merchant does not have a card reader to “swipe” the card.

The account can be any card that has the PAN embossed or printed on the card but does not require a PIN.

Mandatory Input Parameters: PAN, ExpiryDate.

Optional Input Parameters: StartDate, CardSecurityCode.


Track2 (also known as “Card Present” or “Swiped”)

A card reader is available to “swipe” the cardholder’s card and read the Track2 from it.

The account can be any card that has a Track2 on the magnetic strip but does not require a PIN.

Mandatory Input Parameter: Track2


PIN (also known as “Card Present” with PIN or “Swiped” with PIN)

The account is a card that requires a PIN (eg debit card) and a card reader is available to “swipe” the cardholder’s card and read the Track2 from it.

A PED (PIN entry device) is available to securely capture the cardholders PIN and encrypt it.

See “PIN based transactions” (section Error: Reference source not found) for more 

Mode: Test Vs Live

 

The iVeri Gateway provides a mechanism where a merchant can perform test transactions that are routed to an iVeri    Gateway issuer simulator. This enables a merchant to complete testing within a test environment. When the merchant is ready s/he can perform live transactions, which are routed to the genuine card issuer. merchant specifies the mode of a transaction by setting Mode as “Test” or “Live” and sends their corresponding Test or Live ApplicationID.


Sending the following card numbers to the Test environment has the following results:

PAN

Result

4242424242424242

returns "Authorised"

2121212121212121

randomly returns "Hot Card", "Please Call" or "Denied"

5454545454545454

randomly returns "Unable to process" or times out

All other card numbers

(eg "1111222233334444")

returns "Invalid card number"

For information on testing PIN based accounts, see “PIN based transactions”.

Merchants are requested not to abuse the test environment more than their realistic requirements.

A merchant abusing the Test environment may have their use of it suspended


Budget Period 


The Budget Period facility is only available within certain localities (eg South Africa), and therefore only currently available with distributor Nedbank. Since a transaction sequence may entail the Budget Period being sent to the acquirer multiple times, the merchants should ensure that this value is consistent. If an authorisation was obtained outside the iVeri Gateway, and then the AuthorisationCode is sent within “Debit with PAN” or “Debit with Track2”, then the BudgetPeriod should be set to the same value as when authorised. If the BudgetPeriod is not sent to the iVeri Gateway, then iVeri assumes to be “straight” (0 months). However, if the external authorisation was “over budget”, then it would then be up to the acquirer/issuer to decide between the conflicting budget values.

Field

Description

Length (bytes)

Format

SS

Start Sentinel

1

;

PAN

Primary Account Number

19 max

Digits

FS

Field Separator

1

=

DATE

Expiration Date (YYMM)

4

Digits

SVC CD

Service Code

3

Digits

Discretionary Data

Optional Issuer Data

variable

Digits

ES

End Sentinel

1

?

 

Total cannot exceed 39 bytes

39

 


Track2

The Track2 is used for card present transactions and is sent to the iVeri Gateway after it is read by the swipe device from the magnetic stripe on the card. It is inclusive of the beginning and end markers being ; and ? respectively.

The Track2 sent to the iVeri Gateway must be in the following format:


The Track2 read from by the card reader typically contains the following fields (at most 40 bytes):

SS

PAN

FS

DATE

SVC CD

Descretionary Data

ES

LRC


The e 1-byte Longitudinal Redundancy Check (LRC) should not be sent to the iVeriGateway.

The End Sentinel (ES) may need to be converted to? (0x3F)

 

Track2 Service Code values

The following tables can be used to determine the meaning of the 3-digit service code.

See section 17.6.4 for algorithm to determine if a card is PIN based or not. 

Note that a transaction may not decline or rejected solely because of the value of the service code.

Value Position#1

Description

MasterCard

Visa

1

International Card

Yes

Yes

2

International Card – Integrated Circuit Card

Yes

Yes

5

National Use Only

Yes

Yes

6

National Use Only – Integrated Circuit Card

Yes

Yes

7

Private Label or Proprietary Card

Yes

No

Value Position#2

Description

MasterCard

Visa

0

Normal Authorisation

Yes

Yes

2

Positive Online Authorisation Required

Yes

Yes


Value Position#3

Description

MasterCard

Visa

0

PIN Required

Yes

Yes

1

Normal Cardholder Verification, No Restrictions

Yes

Yes

2

Normal Cardholder Verification – Goods and services only at point of interaction (no cash back)

Yes

No

3

ATM Only, PIN Required

Yes

Yes

5

PIN Required – Goods and services only at point of interaction (no cash back)

Yes

No

6

Prompt for PIN if PIN Pad Present

Yes

Yes

7

Prompt for PIN if PIN Pad Present – Goods and services only at point of service (no cash back)

Yes

No

Advanced Settings

 

This section documents functionality within the iVeri Gateway that is not enabled by default. Contact your local distributor should you wish to activate one of these settings for your ApplicationIDMerchant Reference validity period See “Duplicate Transactions” (section 7.3.2) for a discussion of this option.


Recurring transaction checking

See“Duplicate Transactions” (section 7.3.3) for a discussion of this option.


Recon Reference extraction

ReconReference extraction setting is only available for the Nedbank https://distributor.an/ 8 digit ReconReference is sent from iVeri to the acquirer to uniquely identify a transaction. This number is used to query transaction information with the acquirer, and it may appear on the merchant reconciliation statement. By default, a ReconReference is generated by the iVeri Gateway. A merchant has the option for their ReconReference to be derived from their MerchantReference. Since a MerchantReference can be in free text format of up to 64 characters, various rules determine how the 7-digit ReconReference is derived from extracting a section of the Merchant Reference. The configuration for activating a derived ReconReference requires:

  • fixed starting position
  • maximum length of up to 7 digits (first digit reserved as a control digit)
  • direction: left-to-right or right-to-left.


Starting position

Length

Direction

MerchantReference

Derived ReconReference

(last 7 digits)

12

7

left-to-right

March01Rref10

0000010

12

7

right-to-left

100Rref01March

0000100

5

4

left-to-right

Rref1000March01

1000


Transaction Type repetition within transaction sequence


Auhorisations, AuthorisationReversals, Debits and Credits are by default limited to one successful of each type per transaction sequence. An ApplicationID can be configured to not limit the successful count of any of these within a transaction sequence. A MerchantTrace must be supplied for transactions using an ApplicationID with this configuration activated.


AuthorisationReversals and Debits reduce the authorisation amount available (for subsequent authorisations, authorisation reversals and debits). Similarly, Credits reduce the total amount debited.


The possible Advanced transaction sequence flow with an initial Authorisation is the following:

The possible Advanced transaction sequence flow with an initial Debit is the following:

The possible Advanced transaction sequence flow with an initial Credit is unchanged from the diagram shown within the “Sequence” section (6.5).