iVeri Client Developers

Guide(Version 4.1.4
Contents
Revision History ............................................. 13
Introduction .................................................... 14
iVeri Enterprise ..........................................15
File Transfer ...............................................15
Security ......................................................15
Merchant Requirements............................15
Terminology ...............................................16
iVeri Client Requirements..........................16
1. iVeri Client Configuration ....................... 17
1.1 Make contact with an iVeri Distributor
and obtain a User Group (Billing Details ID)
....................................................................17
1.2 Install the relevant runtime: ................17
1.3 Default Location (iVeriClient_Home) ..17
1.4 Run the iVeri Client Configuration ......18
1.5 Ensure valid internet connection (with
sufficient bandwidth) to the iVeri Gateway
....................................................................20
1.6 Configure Proxy Server (if necessary) 20
1.7 Capture Default CertificateID ..............21
1.8 Set ClientAuthentication .....................21
1.9 Perform an ApplicationID Ping
(Enterprise specific) ..................................24
1.10 Develop and Test the Application.....24
1.11 Perform 1 cent Transaction
(Enterpri
se specific) 25
1.12 Switch to “Active” ..............................25
ii
 1.13 Move to Production machine............26
2. Important Security Overview .................. 27
2.1 Security in iVeri Client .NET ................27
2.2 Security in iVeri Client. Java ...............27
3. Payment mechanisms: PAN vs Track2 vs
PIN 28
3.1 PAN (also known as “Card Not Present”
or “Keyed”) .................................................28
3.2 Track2 (also known as “Card Present”
or “Swiped”) ...............................................28
3.3 PIN (also known as “Card Present” with
PIN or “Swiped” with PIN) .........................29
4. Commands and Action ........................... 30
4.1 Commands ..........................................30
4.1.1 Transaction commands (may cause
transfer of funds) ........................................... 30
4.1. 1.1 Authorisation (also known as
“Preauthorisation”) ....................................... 30
4.1.1.2 Authorisation Reversal ...................... 30
4.1.1.3 Debit (also known as “Sale” or
“Purchase”) ................................................... 30
4.1.1.4 Credit (also known as “Refund” or
“Pay”) ............................................................ 30
4.1.1.5 Void ................................................... 30
4.1.2 Enquiry commands (do not cause transfer
of funds) ........................................................ 30
4.1.3 FileTransfer commands........................ 31
4.2 Actions .................................................31
4.2.1 Authorisation with PAN ....................... 32
4.2.2 Authorisation with Track2.................... 33
4.2.3 Authorisation with VisaCheckoutCallID
....................................................................... 33
4.2.4 Additional Authorisation with
TransactionIndex ........................................... 33
 4.2.5 uthorisation Reversal with
TransactionIndex ........................................... 33
4.2.6 Debit with PAN .................................... 33
4.2.7 Debit with Track2 ................................ 33
4.2.8 Debit with PIN ..................................... 33
4.2.9 Debit with TransactionIndex ........... 33
4.2.10 Debit with VisaCheckoutCallID ........ 33
4.2.11 Credit with PAN ................................. 33
4.2.12 Credit with Track2 ............................. 34
4.2.13 Credit with TransactionIndex ............. 34
4.2.14 Credit with VisaCheckoutCallID ....... 34
4.2.15 Void .................................................... 34
4.2.16 Balance Enquiry with PIN ................. 34
4.2.17 PAN Enquiry with PAN ..................... 34
4.2.18 PAN Enquiry with Track2 .................. 34
4.2.19 PANToken Enquiry ............................ 34
4.2.20 Ping .................................................... 34
4.2.21 Get Device PIN Key .......................... 35
4.2.22 ThreeDSecureCheckEnrollment ........ 35
4.2.23 ThreeDSecureValidateAuthentication 35
4.2.24 RequestForDebit ................................ 35
4.2.25 MasterPassQuickResponseCode ........ 35
4.2.26 DynamicCurrencyConversion............ 35
4.2.27 MultiCurrencyPricing ........................ 35
4.2.28 MasterPassPaymentNotification ........ 35
4.2.29 UPOPAuthenticationRequestCreation 35
4.2.30 UPOPAuthenticationRequestValidation
....................................................................... 35
5. Enterprise Development ......................... 36
5.1 Overview ..............................................36
5.2 Enterprise class ...................................36
5.3 Enterprise Gateway Parameters .........37
5.4 Parameter Description .......................38
 5.5 Parameters per Action ...................50
5.5.1 Input Parameters per Action................. 50
6. Transaction Sequences and Terminology
55
6.1 Overview ..............................................55
6.2 Unique Identifiers ................................55
6.3 TransactionIndex and Follow up
transactions...............................................56
6.4 Reversal transaction (Negative
transaction) ...............................................57
6.5 Sequences ...........................................57
7. Ensuring End to End Transaction Integrity
59
7.1 Overview ..............................................59
7.2 Individual transactions .......................59
7.2.1 Void ...................................................... 59
7.2.2 Retry ..................................................... 61
7.2.2.1 Retry with client recorded Merchant
Trace.............................................................. 61
7.2.2.2 Retry without Merchant Trace .......... 62
7.2.2.3 Retry with irrelevant Merchant Trace
(or irrelevant Merchant Reference) ............... 62
7.2.3 Enquiry ................................................. 63
7.2.4 Conclusion ........................................... 63
7.3 Duplicate transactions ........................63
7.3.1 Specify a unique Merchant Trace for
each step in a Transaction Sequence ............. 64
7.3.2 Merchant Reference validity period..... 64
7.3.3 Recurring transaction checking............ 64
8. Common Parameters ............................. 66
8.1 Result Codes........................................66
8.2 Mode: Test Vs Live ..............................67
 8.3 Track2 ..................................................67
8.3.1 Track2 Service Code values ................. 68
8.4 Budget Period ......................................69
9. Specialized Techniques ......................... 70
9.1 Ping ......................................................70
8.2 Mod-10 Checking ................................72
9.3 Card Number Checking .......................73
10. ThreeDSecure (also known as
“VerifiedByVISA” or “MasterCard SecureCode”)
74
10.1 3DSecure implementation directly to a
3DSecure provider .....................................74
10.1.1 3DSecure V_XML tags to be sent to the
iVeri Gateway................................................ 74
10.1.2 (Nothing here?) .................................. 75
10.1.3 3DSecure Process Flow Diagram ...... 76
10.1.4 3DSecure implementation to Bankserv
....................................................................... 77
10.1.5 Test Environment ............................... 77
10.1.6 Live Environment .............................. 77
10.1.7 BankServ 3DSecure Message Flow ... 78
10.2 3DSecure implementation using
V_XML Enquiry commands .......................81
10.2.1 Checking Enrollment ......................... 82
10.2.2 Validate Authentication ...................... 83
11. Visa Check-Out with Enterprise ......... 85
11.1 Process Flow in Visa Check-Out with
enterprise ...................................................85
11.1.1 Illustration of Visa Check Out with
Enterprise ...................................................... 86
12. PayD ......................................................... 87
12.1 PayD Process ....................................87
 12.2 Non-Registered Users.......................87
12.3 Registered Users ...............................88
12.4 Voiding payD Transactions ..............88
13. Web Service .............................................. 89
13.1 Message Formats used by the Web
Service .......................................................89
13.1.1Example of SOAP Request ................. 89
13.1.2 Example of SOAP Response.............. 89
13.2 Web Service URL's ............................90
13.3 Web Service implementation ............90
13.4 WebService Methods ........................91
13.4.1 String Execute (bool validateRequest,
string protocol, string protocolVersion, string
request) .......................................................... 91
13.4.2 PinBlock GetPinBlock (string mode,
string pan, string pin) .................................... 94
13.4.3 String GenerateCertificateID (string
billingDetailsID) ........................................... 96
13.4.4 String SubmitCertificateRequest (string
certificateID, string certificateSigningRequest)
....................................................................... 98
13.4.5 String GetCertificate(string
certificateID) ................................................. 99
15.4.6 String RenewCertificateID (string
certificateID) ............................................... 101
13.4.7 Byte [] DownloadFile(string
fileServiceCommand) ................................. 103
14. POS Device Intergration ........................ 106
14.1 PINBlock encryption via Triple DES
DUKPT encryption .................................. 106
14.1.1 Key Injection for DUKPT Mode Test
..................................................................... 107
14.2 PINBlock encryption via
Master/Session encryption.................... 107
14.2.1 Key Injection for Master/Session Mode
 Test .............................................................. 107
14.2.2 Get Device PIN Key ........................ 108
14.3 Track2 encryption via Master/Session
encryption ............................................... 108
14.3.1 Track2 Key Injection for
Master/Session Mode Test .......................... 109
14.4 Track2 encryption via Dukpt
encryption ............................................... 109
14.4.1 Track2 IPEK Injection for Dukpt Mode
Test .............................................................. 109
14.5 PAN encryption via Dukpt encryption
................................................................. 110
16.6.1 “Debit with PIN” and “Balance
Enquiry” ................................................... 110
14.6.1 Debit with PIN ..................................110
14.6.2 Balance Enquiry ................................ 111
14.6.3 Test environment for PIN cards ........ 111
14.6.4 Determining if a card is PIN based ...112
14.7 EMV Transactions”......................... 112
14.8 Coding for EMV data ...................... 113
15. Additional Data Transactions................ 114
15.1 Additional Data for Procurement
Transactions........................................... 114
15.1.1Coding for Procurement .....................114
15.1.2 Tax Calculation .................................115
15.1.3 Calculation when TransactionDiscount
is NOT zero ..................................................116
15.2 Advanced Fraud Screening ............ 116
15.3 Fleetcard transactions ................... 117
15.3.1 Coding for Fleetcards ........................117
15.4 Airline addendum data ................... 118
15.4.1 Coding for Airline addendum data ....118
15.5 CyberSource Fraud Management .. 119
 15.5.1 Device Fingerprinting .......................119
15.5.1.1 PNG Image.....................................119
15.5.1.2 Flash Code .....................................119
15.5.1.3 JavaScript Code ............................ 120
15.5.2 Coding for CyberSource data........... 120
15.6 Authenticated Collections.............. 120
15.6.1 Coding for Authenticated Collection
data .............................................................. 121
16. MasterPass Quick Response Code ....... 122
16.1 Create Code .................................... 122
16.1.1 Additional Parameters ...................... 122
16.1.2 Example: .......................................... 122
16.2 Query Code ..................................... 123
16.2.1 Additional Parameters ...................... 123
16. 2.2 Example: ......................................... 123
16.3 Delete Code .................................... 124
16.3.1 Additional Parameters ...................... 124
16.3.2 Example: .......................................... 124
16.4 Block Code ...................................... 125
16.4.1 Additional Parameters ...................... 125
16.4.2 Example: .......................................... 125
16.5 Unlock Code ................................... 126
16.5.1 Additional Parameters ...................... 126
16.5.3 Example: .......................................... 126
16.6 Update Code ................................... 127
16.6.1 Additional Parameters ...................... 127
16.6.2 Example: .......................................... 127
16.7 Update Code Amount ..................... 128
16.7.1 Additional Parameters ...................... 128
16.7.2 Example: .......................................... 128
17. Foreign Exchange .................................. 129
 17.1 Dynamic Currency Conversion (DCC)
................................................................. 129
17.1.1 DCC Rate Request with Specified BIN
and Base Amount ........................................ 129
17.1.2 Multiple Rate Request with Specified
Base Amount ............................................... 130
17.2 Multi-Currency Pricing (MCP) ....... 131
18. UPOP SecurePlus Authentication ......... 133
18.1.1 Request Creation .............................. 133
18.1.2 Request Validate............................... 134
19. Advanced Settings ................................. 136
19.1 Merchant Reference validity period136
19.2 Recurring transaction checking .... 136
19.3 ReconReference extraction............ 136
19.4 Transaction Type repetition within
transaction sequence............................. 137
20. File Transfer Development .................... 138
20.1 Overview ......................................... 138
20.2 FileTransfer class ........................... 138
20.3 File Transfer Data Types ................ 139
20. File Transfer Parameters ................. 140
20.5 File Transfer Command ................. 141
20.6 File Transfer Parameters per action
................................................................. 142
20.7 Automating the File Transfer process
................................................................. 143
21. Out of Band Transaction Notification ... 145
21.1 Prerequisite..................................... 145
22. Domain Knowledge ................................ 146
22.1 Card Present vs. Card Not Present 146
 22.2 Online vs. Offline Transactions ..... 146
22.2.1 Online Transactions ......................... 147
22.2.2 Offline Transactions ......................... 147
23. Frequently Asked Questions (common to
.NET and Java) ............................................. 149
23.1 Problems connecting to the iVeri
Gateway .................................................. 149
23.2 Request timed out when network
pinging the gateway ............................... 150
23.3 Execute () or executeAsync() must be
called before this method is allowed ..... 150
24. Contact Information............................... 152
24.1 Distributors ..................................... 152
24.1.1 Nedbank South Africa ...................... 152
24.1.2 Nedbank Namibia ............................ 152
24.1.3 CBZ Zimbabwe................................ 152
24.1.4 I&M Bank Kenya ............................. 152
24.1.5 CSC/CSC247 Bank .......................... 152
24.1.6 CIM .................................................. 152
24.2 Websites ......................................... 153
24.2.1 Nedbank ........................................... 153
24.2.2 CBZ Bank ........................................ 153
24.2.3 I&M Bank ........................................ 153
24.2.4 CSC/CSC247 Bank .......................... 153
24.2.5 CIM .................................................. 154
24.2.6 DNS configuration ........................... 154
25. Appendix A: V_XML Message Examples155
26. Appendix B: ACS Redirect Example Page
...................................................................... 161
26.1 Authenticating Enrolled Cards ....... 161
26.2 POST Form ..................................... 161
26.3 Authentication Frame .................... 161
 26.4 PARes Message ............................. 163
26.5 Response Messages ...................... 164
27. Appendix C: Out of Band - Merchant
Webservice ................................................... 165
28. Appendix D: UPOP Authentication Redirect
Example Page............................................... 166
28.1 Authenticating UnionPay Cards .... 166
28.2 POST Form ..................................... 166
28.3 Use of Authentication Page ........... 166
28.3.1 Timing between Authentication and
Authorization .............................................. 167
28.3.2 Failed Authentication Processing ..... 167
28.3.3 Data Required in Authentication
Messages ..................................................... 167
28.4 Full Transaction Flow ..................... 167
REVISION HISTORY

Version Author Date Description

4.0.0 Eugene Kriek 2015-06-22 Removed Requesting Certificates.
Removed Checking for Available Certificates
Java Support JDK 8 upwards
DotNet Support 4.6.x upwards
Added Capture Default CertificateId
Added ClientAuthentication
Added properties to override the default values
• CertificatePath
• CertificateFile
• CertificatePassword
4.0.1 Eugene Kriek 2015-11-03 Added a method to both the Enterprise and the FileTransfer classes to retrieve
the Client Home directory
4.0.2 Eugene Kriek 2016-02-19 When no CertificatePath is set the CertificatePath would point to the Client
Home directory
4.0.3 Roland Elferink 2016-06-22 Added Authenticated Collections. Renumbered section 18 through to 21
because someone has hardcoded them making it impossible to insert a new
section.
4.0.4 Eugene Kriek 2016-11-08 Added RequestForDebit. A new Enquiry command that enables the merchant
to generate a request for a Debit email that is sent to a customer.
4.0.5 Eugene Kriek 2017-04-06 Added DiVert Upload / Download of batches via FileTransfer
4.0.6 B Habe 2017-05-04 Added CSCBank Webservice URL
Updated Hyperlinks to point to the current endpoints
Updated JDK/. Net Framework versions
4.0.7 B. Habe 2017-06-08 Added Out of Band Transaction Notification
4.0.8 S. Bonga 2017-09-13 Updated ProtocolVersion
4.0.9 Eugene Kriek 2017-10-03 Added MasterPass Quick Response Code management
4.0.10 Eugene Kriek 2017-11-11 Converted Build to Maven
4.0.11 Eugene Kriek 2017-11-14 Removed ResultNumber
4.0.12 Eugene Kriek 2018-03-12 Added new constant resultcode 2 for Gateway Unreachable
4.0.13 Eugene Kriek 2018-04-23 Added the following enquiry commands
• DynamicCurrencyConversion,
• MultiCurrencyPricing
4.1.0 Eugene Kriek 2018-06-29 Added MasterPass Payment Notification
4.1.1 Kobus Walters 2018-09-28 Updated the description of the AcquirerReference response tag
4.1.2 Kobus Walters 2019-03-25 Documented the WebService method DownloadFile
4.1.3 B. Habe 2019-03-25 Update the document by adding CIM Gateway URL’s
Removed nPay Related topics
4.1.4 Eugene Kriek 2019-08-12 Added MPGS / Netcetera as 3DS providers and had to add additional input /
output parameters for the following:
• ThreeDSecureCheckEnrollment
• ThreeDSecureValidateAuthentication
4.1.5 Eugene Kriek 2019-09-01 Added UPOP Authentication Enquiry command
• UPOPAuthenticationRequestCreation
• UPOPAuthenticationRequestValidation
This enables the merchant to use SecurePlus authentication to validate a
cardholder

13
INTRODUCTION

The iVeri range of payment products, developed by iVeri Payment Technologies (Pty) Ltd
(www.iveri.com) provide proven credit card payment solutions for businesses on and off the
internet.
The iVeri Client software facilitates the secure communications between the Merchant and
the iVeri Gateway via client-side software, primarily enabling iVeri Merchants to initiate
transactions on cards from within their systems, be they websites, call centres, etc
iVeri Client comes in the following forms:
Client .NET – Built on Microsoft’s .NET Framework is compatible with all .NET compatible
programming languages. Currently dependant on Microsoft operating systems.
Client Java – Built on Oracle JDK / JRE 8. Platform independant.

iVeri Client has two classes within it that provide two different abilities:
Enterprise: For the sending and receiving messages to / from the iVeri Gateway.
FileTransfer: For uploading/downloading of files to / from the iVeri Gateway.

This document is written to show:

The usage of iVeri Client Configuration utility for setting up certificate requirements for
communicating with the iVeri Gateway
The usage of the Enterprise class
The usage of the FileTransfer class

Whenever the iVeri Gateway is enhanced with changes that effects the Gateway Protocol, this
document should be updated, and the latest version posted on the iVeri website.
See the “Protocol History” section for information on changes within the Gateway protocol,
including its enhancements and depreciated (backward compatible) functionality.
The full functionality of the current protocol requires iVeriClient version 4.0.0 or later.
Merchants that are using an earlier version can either upgrade or refer the earlier version
documentation.

14
Database storage, formatting and integration of iVeriClient into a merchant system is
specified by developer(s) appointed by the merchant.

iVeri Enterprise
Enterprise is aimed at Merchants that have the following characteristics:
Access to development resources.
Medium to large websites.
Call centres and physical store environments.
Own Merchant Number and a relationship with an authorised Acquiring Institution

File Transfer
The File Transfer component of iVeri Client enables merchants to upload/download files
to/from the iVeri Gateway. There may be files available for upload/download within iVeri
Client that are not available via the iVeri BackOffice. Similarly, there may be files available for
upload/download within iVeri BackOffice that are not available via the iVeri Client. The
following other sections within this document relevant to File Transfer are: 3, 10.1 and 22.

Security
iVeri Client utilizes the worldwide-accepted SSL standard for encryption in order to protect
the integrity of transaction information. All communication between the iVeri Client software
and the iVeri Gateway is encrypted with 256-bit SSL. Client certificates are issued by the iVeri
CA. Whereas the Gateway certificate is a public certificate.

Note for iVeri Enterprise Users: It is the merchant’s responsibility to secure the link between
the cardholder and the merchant server on which the iVeri Client software operates.

Merchant Requirements
Merchants are required to enter into a “Agreement” with an authorised Acquiring Institution.
See your iVeri Distributor (see section Error: Reference source not found) for more
information on entering into a Merchant Agreement, and obtaining a Merchant Number.

15
Terminology
This document uses certain iVeri specific terminology (like ApplicationID). See sections 7.4
and Error: Reference source not found for descriptions of many of these terms.

iVeri Client Requirements

Merchants using iVeri Client require:
User Group
Test ApplicationID and Live ApplicationID

Please contact your iVeri Distributor (see section Error: Reference source not found) for more
information on how to obtain this information.

The following are the technical requirements for installing, configuring and using iVeri Client:

For iVeri Client.NET: The Microsoft .NET Framework 4.6 SDK / runtime must be installed
before using iVeri Client.NET 4.6.x (previous iVeri Client .NET supported the Microsoft
.NET Framework 4.5 or later).
For iVeri Client Java: Java 8 JDK / JRE (previous iVeri Client supported JDK 7 or later) must
be installed before using the iVeri Client.Java software
Network Connection from the Server to the iVeri Gateway. This may be via any network over
which TCP/IP can be run as the protocol e.g. The Internet, Diginet, Leased Line, ISDN etc.

16
1. IVERI CLIENT CONFIGURATION

1.1 Make contact with an iVeri Distributor and obtain

a User Group (Billing Details ID)
Contact your iVeri Distributor (see section Error: Reference source not found) and request to
be captured on the system. Discuss with the operator which iVeri Product you are suited for:

iVeri Enterprise: You need to use the iVeri Client software.

iVeri Batch: You may upload, and download batches either via the iVeri BackOffice website,
or via the software within iVeri Client.
iVeri DiVert: You may upload, and download DiVert batches either via the iVeri BackOffice
website, or via the software within iVeri Client.
Certain other products: You may download files (for example Reconciliation file) via the
iVeri BackOffice website, or via the software within iVeri Client.

You will be then be asked to supply certain information. Once the iVeri Distributor has
processed this information, you will be emailed a User Group and Password. Keep these
details readily available, as this will be required for requesting Certificate IDs, and for logging
in to the iVeri BackOffice website. This process will result in an ApplicationID being emailed
to the designated technical contact.

1.2 Install the relevant runtime:

iVeri Client. Java: Install Java 8 JDK / JRE or later. This can be downloaded free of charge
from http://www.oracle.com/technetwork/java/index.html
iVeri Client. NET: Install the Microsoft .NET Framework 4.6. This can be downloaded free
of charge from http://www.microsoft.com/net

1.3 Default Location (iVeriClient_Home)

Select option 5 (Show Config file location).
The Config file will reside in one of the following places

17
1. Environment Variable configure: iVeriClient_Home
2. System Property configured iVeriClient_Home
3. Application / User Working directory

You may obtain the working directory by running Option 6

The configuration file location is:
C:\ [Some path] \iVeriClient.config

Note: When changing the iVeriClient_Home environment variable and running a website in IIS,
you have to reset IIS after setting the environment variable

1.4 Run the iVeri Client Configuration

iVeri Client. Java:

1. If you drop the iVeriClient.jar into the ~\jre\lib\ext directory you can just type java
ClientConfig.
2. If you want to run the Configuration Utility from your applications working directory drop
iVeriClient.jar in your application directory. Now type java -jar iVeriClient.jar

The following should appear:

iVeri Client Configuration Utility v4.0.0

Copyright (c) iVeri Payment Technologies 2003-2015
Java Version 1.8.0_45

Initialising...

18
Menu

1. Capture Default CertificateID

2. Set Client Authentication
3. ApplicationID Ping iVeri Gateway
4. Perform 1c Transaction
5. Show iVeri Client Home Location

A. Get Track2 Session Key

X. Exit

Choice [1] :

iVeri Client. NET: Run the Configuration Utility from your applications working directory by
running the “iVeri.ClientConfig.exe” application.

The following should appear:

iVeri Client Configuration Utility v 4.0.0

Copyright (c) iVeri Payment Technologies 2003-2015
Dotnet Version 4.0.30319.34209

Initialising...

Menu

1. Capture Default CertificateID

2. Set Client Authentication
3. ApplicationID Ping iVeri Gateway
4. Perform 1c Transaction
5. Show iVeri Client Home Location
19
A. Get Track2 Session Key
X. Exit

Choice [1] :

NOTE: The Client Configuration utility uses the convention that a default entry is indicated by
square braces (eg [...]) before the required input. Therefore, above default choice is 1.

1.5 Ensure valid internet connection (with sufficient

bandwidth) to the iVeri Gateway

Select option 1 and follow the instructions.

Note: This functionality used to perform an “iVeri Gateways network pings” (ie icmp packets).
However due to the fact that many iVeri Gateways have icmp disabled, testing connectivity to
the iVeri Gateway is done in other ways (from version 2.3.1)

1.6 Configure Proxy Server (if necessary)

Open the configuration file in your favorite text editor and add the following XML sub
elements to the DEFAULTS section of the configuration file.

PROXY_HOST
This element identifies the proxy server by name or IP address.

PROXY_PORT
Specifies the
Specifiesthe port on the proxy server to connect to.

PROXY_USERNAME
The username to use when proxy authentication is required.

PROXY_PASSWORD
The proxy servers password when proxy authentication is required.

Example:

20
<XML>
<GATEWAYS>
<DEFAULTS>
<VERSION>2.0</VERSION>
<TIMEOUT>60</TIMEOUT>
<ERRORFILE>iVeriClientErrors.txt</ERRORFILE>
<DEFAULTGATEWAY />
<PROXY_HOST>10.0.0.2</PROXY_HOST>
<PROXY_PORT>3128</PROXY_PORT>
<PROXY_USERNAME></PROXY_USERNAME>
<PROXY_PASSWORD></PROXY_PASSWORD>
</DEFAULTS>
<GATEWAY Name="nedbank">
<ADDRESS>portal.nedsecure.co.za</ADDRESS>
<PATH>/iVeriGateway/Gateway.aspx</PATH>
</GATEWAY>
<GATEWAY Name="host">
<ADDRESS>portal.host.iveri.com</ADDRESS>
<PATH>/iVeriGateway/Gateway.aspx</PATH>
</GATEWAY>
</GATEWAYS>
</XML>

In the above example iVeriClient would connect to proxy server 10.0.0.2 listening on port
3128 without a username and password.

1.7 Capture Default CertificateID

Select option 1. This will allow you to set the default CertificateId to be used by iVeriClient.
Copy the CertificateID without the '{', '}' braces and paste it

Verify the information entered.

1.8 Set ClientAuthentication

Select option 2. This will allow you to configure whether you are going to use Client
Certificates or not.

21
Enable Client Authentication

1. Yes
2. No

X. Exit

By selecting option 2, No, you will disable Client Authentication and no client certificates will
be used when connecting to the gateway.
By selecting option 1, Yes, you will have to enable Client Authentication by completing the
steps following.

CertificateSource (Java)

When you want to use Client Certificates there are two CertificateSources whereby the
certificate can be stored by.

1. File - Certificate is stored as a PKCS#12 file with a. p12 extension.

2. Keystore - Certificate is stored in a Java Keystore (JKS) keystore.

Certificate Source

1. File
2. KeyStore

X. Exit

Selecting option 1 will perform the following functionality:

Set Certificate Path. Validate the path exists.
Set Certificate File Name. Validate that the certificate exists and that it is a PKC#12
certificate.
Set Certificate Password. Validate the certificate password.
Verify information and confirm.
Enable Client Authentication

22
Selecting option 2 will perform the following functionality:
Set Certificate Path. Validate the path exists.
Set Keystore File Name. Validate that the keystore exists and that it is a JKS keystore
Set Keystore Password. Validate the keystore password.
Set Certificate Password. Validate the certificate password.
Verify information and confirm.
Enable Client Authentication

CertificateSource (Dotnet)
When you want to use Client Certificates there are two CertificateSources whereby the
certificate can be stored by.

1. File - Certificate is stored as a PKCS#12 file with a. p12 extension.

2. Certificate Store - Certificate is stored in the Local Machine Store.

Certificate Source

1. File
2. Certicate Store

X. Exit

Selecting option 1 will perform the following functionality:

Set Certificate Path. Validate the path exists.
Set Certificate File Name. Validate that the certificate exists and that it is a PKC#12
certificate.
Set Certificate Password. Validate the certificate password.
Verify information and confirm.
Enable Client Authentication

23
Selecting option 2 will perform the following functionality:
Validate that certificate with DefaultCertificateId as CommonName exists inside Local
Machine Store.
Enable Client Authentication

1.9 Perform an ApplicationID Ping (Enterprise

specific)
Select option 3. This will perform the following functionalities:
Validate your Certificate
Check that your ApplicationID is ready for use
Check your ApplicationID-CertificateID combination is valid
Check that the iVeri Gateway is up
Check that the link between the iVeri Gateway and the acquirer(s) is up

1.10 Develop and Test the Application

Develop and Test your application referencing the sections below and samples as
appropriate. Your development should include the logging of transaction information in
database (preferable) or file for future references and queries. Should there be a dispute over
what data was sent between the Merchant and the iVeri Gateway, the Merchant would be
required to produce these logs.

In order to ensure that iVeri Enterprise merchants keep client-side logs, we require that a
sample of these logs (in any format displayable in a text editor) be emailed when
development is completed. See “Contact information” (section Error: Reference source not
found) for an email address to submit logs to.

Logs should include any actions that may be performed by the merchant.

24
The getLoggableRequest()and getLoggableResponse() methods can be used for
logging the input and output from the transaction. These two methods retrieve the xml sent
to or received from the gateway and contain all the necessary transaction information to be
logged. The getLoggableRequest() method is called the line before execution, while the
getLoggableResponse() method is called the line after execution.

These methods allow logging required sensitive data (e.g. Credit Card Numbers) in a secure
manner.

1.11 Perform 1 cent Transaction (Enterprise

specific)
The “1c Live Transaction” functionality is available via option 5 in the iVeri ClientConfig. This
helps the merchant check that iVeri Gateway and the acquirer are correctly configured for the
Merchant to receive a 1c deposit into their account. This functionality is also known as a 1c
“Trial” transaction because it allows a “Live” transaction, which is otherwise not allowed until
the Merchants Live ApplicationID Status is “Active” (see 3.12 for more information).

1.12 Switch to “Active”

Once you:
have emailed the required logs as per Step 3.10 AND
(Enterprise specific) have performed a live (trial) transaction and seen the deposit into
your bank account as per Step Error: Reference source not found

Contact the iVeri Distributor help desk and request that your ApplicationID Status be made
“Active”. Only once your logs have been checked by the iVeri Distributor will your
ApplicationID will switched to “Active”.

25
1.13 Move to Production machine
If your development machine and production machines are two different machines, you will
need to install your developed code to the production machine. To do this, you need to repeat
Steps 3.2 through to Error: Reference source not found for FileTransfer and Steps 3.2 through
to 3.9 for iVeri Enterprise to ensure everything is correctly configured on the Production
machine.

26
2. IMPORTANT SECURITY OVERVIEW

2.1 Security in iVeri Client .NET

When iVeriClient is run with ClientAuthentication enabled and using the Local Machine Store
as the CertificateSource make sure that the user that the application is run under has
permissions to the specific certificate in the store. Please make sure that the user that the
application is run under has read, write permissions to the iVeriClient_Home directory.

2.2 Security in iVeri Client. Java

IveriClient is required to be able to retrieve client certificates from disk in an OS and
Application Framework independent way.

Please ensure that your application has read permissions to the directory where your
keystore / certificate is located.
Please make sure that your iVeriClient has read, write permissions to the iVeriClient_Home
directory.

27
3. PAYMENT MECHANISMS: PAN VS
TRACK2 VS PIN

iVeri Gateway separates accounts into 3 different payment mechanisms:

PAN
Track2
PIN

In order 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.

3.1 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.

3.2 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

28
3.3 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 details.

29
 4. COMMANDS AND ACTION

4.1 Commands
4.1.1 Transaction commands (may cause transfer of funds)
4.1. 1.1 Authorisation (also known as “Preauthorisation”)
Causes a reservation of funds on the cardholders account.
4.1.1.2 Authorisation Reversal
Unreserve the funds previously reserved on the cardholders account.
4.1.1.3 Debit (also known as “Sale” or “Purchase”)
Causes a transfer of funds from the cardholder to the merchant.
4.1.1.4 Credit (also known as “Refund” or “Pay”)
Causes a transfer of funds from the merchant to the cardholder.
4.1.1.5 Void
Cancel one of the above commands within a short time after the command was initiated.
4.1.2 Enquiry commands (do not cause transfer of funds)
See section on “Actions” below for a description of these commands
Balance
PAN
PANToken
Ping
GetDevicePINKey
ThreeDSecureCheckEnrollment
ThreeDSecureValidateAuthentication
AuthenticatedCollection
RequestForDebit
MasterPassQuickResponseCode
DynamicCurrencyConversion
MultiCurrencyPricing

30
 MasterPassPaymentNotification
UPOPAuthenticationRequestCreation
UPOPAuthenticationRequestValidation
4.1.3 FileTransfer commands
See section 22 on “FileTransfer” for a description of these commands
Batch Upload
Batch Download
HotCard Download
BINLookup Download
BINManagement Download
BlackCard Download
TransactionHistory Download
Recon Download
AcquirerRecon Download
Inventory Download
DiVert Upload
DiVert Download

4.2 Actions
An Action corresponds to the combination of a Payment Mechanism and a Command. The
concept of an Action is used within the documentation and examples as a means of
describing functionality. Note that the iVeriClient software and the iVeriGateway use the
concepts Payment Mechanism and Command instead of Action.

The iVeri Gateway allows for the following actions:

Authorisation with PAN
Authorisation with Track2
Authorisation with VisaCheckoutCallID
Additional Authorisation with TransactionIndex

31
 Authorisation Reversal with TransactionIndex
Debit with PAN
Debit with Track2
Debit with PIN
Debit with TransactionIndex
Debit with VisaCheckoutCallID
Credit with PAN
Credit with Track2
Credit with TransactionIndex
Credit with VisaCheckoutCallID
Void
Balance Enquiry with PIN
PAN Enquiry with PAN
PAN Enquiry with Track2
PANToken Enquiry
Ping
Get Device PIN Key
ThreeDSecureCheckEnrollment
ThreeDSecureValidateAuthentication
RequestForDebit
MasterPassQuickResponseCode
DynamicCurrencyConversion
MultiCurrencyPricing
MasterPassPaymentNotification
UPOPAuthenticationRequestCreation
UPOPAuthenticationRequestValidation
4.2.1 Authorisation with PAN
Reserve funds when a card not present.

32
4.2.2 Authorisation with Track2
Reserve funds when a card is present. Funds reservation is not applicable for cards requiring
a PIN.
4.2.3 Authorisation with VisaCheckoutCallID
Reserve funds when a card is present. Funds reservation is not applicable for cards requiring
a PIN.
4.2.4 Additional Authorisation with TransactionIndex
Increase the amount previously reserved via iVeri by an additional amount. The addition of
funds previously reserved outside the iVeri Gateway is not supported.
4.2.5 uthorisation Reversal with TransactionIndex
Release the funds previously reserved on the cardholders account via the iVeri Gateway. The
release of funds reserved outside the iVeri Gateway is not supported.
4.2.6 Debit with PAN
Transfer of funds from cardholder to merchant when a card not present. The use of an
AuthorisationCode previously obtained outside the iVeri Gateway is supported.
4.2.7 Debit with Track2
Transfer of funds from cardholder to merchant when a card is present. The use of an
AuthorisationCode previously obtained outside the iVeri Gateway is supported.
4.2.8 Debit with PIN
Transfer of funds from cardholder to merchant when a card requiring a PIN is present.
4.2.9 Debit with TransactionIndex
Transfer of funds from cardholder to merchant. Follow up of an action previously sent to the
iVeri Gateway. Not supported for cards requiring a PIN.
4.2.10 Debit with VisaCheckoutCallID
Transfer of funds from cardholder to merchant. Follow up of an action previously sent to the
iVeri Gateway. Not supported for cards requiring a PIN.
4.2.11 Credit with PAN
Transfer of funds from merchant to cardholder when a card not present.

33
4.2.12 Credit with Track2
Transfer of funds from merchant to cardholder when a card is present. Credit is not currently
supported for cards requiring a PIN.
4.2.13 Credit with TransactionIndex
Transfer of funds from merchant to cardholder. Follow up of an action previously sent to the
iVeri Gateway. Not supported for cards requiring a PIN.
4.2.14 Credit with VisaCheckoutCallID
Transfer of funds from merchant to cardholder. Follow up of an action previously sent to the
iVeri Gateway. Not supported for cards requiring a PIN.
4.2.15 Void
Cancel a transaction command within a short time after the command was initiated.
4.2.16 Balance Enquiry with PIN
Obtain the balance of the PIN based account in the currency of the account. Note that this
currency may be different to the currency of the merchant.
4.2.17 PAN Enquiry with PAN
Obtain information about a card (which is not present) without performing a transaction, for
example to check if the card is a hot card or blacklisted by the merchant.
4.2.18 PAN Enquiry with Track2
Obtain information about a card (which is present) without performing a transaction, for
example to check if the card is a hot card or blacklisted by the merchant. PAN Enquiry is not
currently supported for cards requiring a PIN.
4.2.19 PANToken Enquiry
Obtain a TransactionIndex for the card number and expiry date without performing a
transaction. The TransactionIndex is to be used in a Tokenized transaction.
4.2.20 Ping
The Ping command is primarily used to determine if the connection status between the
Merchant and the Acquirer. If the connection is down, then the Ping command can also be
used to check when the status is back up.
See section 9.1 for more information.

34
4.2.21 Get Device PIN Key
Get the current Triple DES session key for a device. See PIN based transactions (section Error:
Reference source not found).
4.2.22 ThreeDSecureCheckEnrollment
Check the CardHolders 3DSecure Enrollment. (section 10.2).
4.2.23 ThreeDSecureValidateAuthentication
Validate the CardHolders 3DSecure Authentication process. (section 10.2).
4.2.24 RequestForDebit
A Request for a Debit (Sale) is generated and an Email is sent to a cardholder.
4.2.25 MasterPassQuickResponseCode
Generating / Managing a transactional code that can be paid for by a cardholder. (section 17).
4.2.26 DynamicCurrencyConversion
Generating / Managing a transactional code that can be paid for by a cardholder. (section 18).
4.2.27 MultiCurrencyPricing
Generating / Managing a transactional code that can be paid for by a cardholder. (section 18).
4.2.28 MasterPassPaymentNotification
Inquiring whether a payment notification has been received from MasterPass.
4.2.29 UPOPAuthenticationRequestCreation
The creation of the Authentication Request message to be posted to the UPOP authentication
server (section 17.1).
4.2.30 UPOPAuthenticationRequestValidation
The validation of the Authentication Response message received from the UPOP
authentication server (section 17.2).

35
5. ENTERPRISE DEVELOPMENT

5.1 Overview
The following is available to assist Enterprise development:
iVeri Client Developers Guide (this document)
The iVeri Client API (which includes the Enterprise class)
iVeri Enterprise code samples
Distributor website (see section Error: Reference source not found) for updates to the
documentation mentioned

5.2 Enterprise class

The Enterprise class has the following basic flow:
Instantiate Enterprise class
Set the Gateway and the CertificateID.
These can be set within the Enterprise constructor, or as separate methods (properties in
iVeriClient.net)
You may choose to override the (properties in iVeriClient.java) CertificatePath,
KeyStoreFile, CertificateFile, KeyStorePassword and
CertificatePassword
You may choose to override the (properties in iVeriClient.net) CertificatePath,
CertificateFile, and CertificatePassword
Prepare the command to be sent to the gateway
Call one of the following methods: prepare / authorisation / authorisationReversal
/ debit / credit / ping
set the various input parameters: generally, via setTag, or setAttribute
submit the request to the iVeri Gateway: via execute or executeAsync
check the results returned, particularly ResultStatus and ResultCode
check other output parameters: generally, via getTag, or getAttribute

36
5.3 Enterprise Gateway Parameters
Below we describe the various gateway parameters.
This is followed by a table of what input and output parameters are relevant for each action.
Parameters are shown grouped according to their usage.

The following key is used for data types:

Data Type Description
A Alpha only (A-Za-z)
AN Alphanumeric (a-zA-Z0-9)
Base64 Base64 encryption of binary data
Boolean True or False
Guid Globally Unique Identifier: {[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}\}
(eg {8E51611F-E19A-4FF0-B229-6A69F42AAA62})
Hex Hex (0-9A-Fa-f)
N Numeric (Positive integer)
N. Digits and dots (.) (e.gs 4242........4242, 1.0)
N: Digits and colons
String ANPS Free format string containing: Alpha, numeric, special and padding (printable ASCII)
Z Positive or negative integer

The Node Type column corresponds to how the Enterprise class should be used for the
parameter:
Node Type Set input parameter value Get output parameter value
attribute enterprise.setAttribute(..) enterprise.getAttribute(..)
tag enterprise.setTag(..) enterprise.getTag(..)
parameter enterprise.prepare(...) N/A
attribute parameter enterprise.prepare(...) enterprise.getAttribute(..)
property Use method or property of enterprise corresponding to the parameter N/A
subtag call enterprise.setTag(..) within N/A
enterprise.openElement(...)
...
enterprise.closeElement()

37
5.4 Parameter Description
Core Parameters
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
ApplicationID attribute Guid 38 38 Identification of the merchant’s configuration within the iVeri Gateway
paramet
er
CertificateID property Guid 38 38 The iVeri CertificateID installed on the server communicating with the iVeri Gateway
CertificatePath property A Valid Path to directory where the KeyStoreFile or CertificateFile exists on the filesystem
CertificateFile property A Existing certificate file
CertificatePassword property A Password of the certificate
KeyStoreFile property A Existing keystore file (Only iVeriClient.java)
KeyStorePassword property A Keystore password (Only iVeriClient.java)
Gateway property A 10 The name of the gateway connecting to. If not explicitly set, the default gateway is used.
Command attribute A 50 The command specifying what should be done by the iVeri Gateway
paramet
er
GetDevicePINKey Get DevicePINKey (use Category=Security)
Ping Ping (use Category=Syste m)
Authorisation Authorisation (use Category=Transaction)
AuthorisationReversal Authorisation Reversal (use Category=Transaction)
Credit Credit (use Category=Transaction)
Debit Debit (use Category=Transaction)
Void Void (use Category=Transac tion)
Balance Balance Enquiry (use Category=Enquiry)
PAN PAN Enquiry (use Category=Enquiry)
PANToken PANToken Enquiry (use Category=Enquiry)
ThreeDSecureCheckEnroll ThreeDSecureCheckEnrollment Enquiry (use Category=Enquiry)
ment
ThreeDSecureValidateAut ThreeDSecureValidateAuthentication Enquiry (use Category=Enquiry)
hentication
AuthenticatedCollection AuthenticatedCollection:Enquiry (use Category=Enquiry)
RequestForDebit RequestForDebit Enquiry (use Category = ‘Enquiry’)
MasterPassQuickRespons MasterPass QuickResponseCode Enquiry (use Category = ‘Enquiry’)
eCode
Mode attribute A 4 4 The mode of the corresponding ApplicationID. See section 10.2
paramet
er
Test
Live
RequestID attribute Guid 38 38 A unique identifier generated by the iVeri Gateway for this request

38
 Category paramet A 50 A categorisation of the request. Only required in conjunction with a prepare method.
er
Transaction use if Command = Debit or Credit or Authorisation or AuthorisationReversal
or Void
Enquiry use if Command = Balance, PAN or PANToken or
AuthenticatedCollection or ‘ RequestForDebit’
System use if Command = Ping
Security use if Command = GetDevicePINKey
Common Parameters
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
Acquirer tag A 3 32 The Acquiring system to which this transaction was routed by iVeri
Nedcor
NedbankBICISO
IMNarada
DashenACI
ChamsACI
MSCCTranzWare
CTLNigeria
AcquirerDate tag N 8 8 The date that the Acquirer allocated to this transaction
YYYYMMDD YearMonthDay
AcquirerReference tag N: 64 A reference allocated by the Acquirer to this transaction with format specific to the acqiurer. It is a composite
element consisting of a settlement cycle and a transaction trace. The cycle can be 5 digits (the acquirer batch
number) or 8 digits (cycle end date). The trace is the significant part of the acquirer Retrieval Reference
Number (RRN). The trace can be 8 digits (if the RRN starts with 0000) or 12 digits (the full RRN).
CCCCC: TTTTTTTT CycleNumber:RRN8 (for Nedbank providers)
yyyyMMdd:tttttttt CycleEndDate:RRN8 (for the TMS provider)
yyyyMMdd:ydddhhtttttt CycleEndDate:RRN (for providers in general)
AcquirerTime tag N 6 The time that the Acquirer allocated to this transaction
HHMMSS HourMinuteSecond
Amount tag N 0 12 The total value of the transaction in the smallest unit of the currency specified (eg in cents)
AuthorisationCode tag AN 0 6 The Authorisation Code issued by the Issuer to the Merchant either telephonically or electronically
BudgetPeriod tag N 0 2 The number of months over which the cardholder would like to pay the transaction off. See section 10.4
0 default
3
6
9
12
18
24
36
CardSecurityCode tag N 3 4 The 3 or 4 digits printed on the card which are not contained on the magnetic strip. Usually printed after the
CCNumber on the signature strip. Corresponds to American Express CIV, MasterCard CVC2 and VISA CVV2.
Does not exist within Associations
Currency tag A 3 The ISO 4217 currency code of the value of the transaction. e.g. USD or ZAR or GBP

39
 DisplayAmount tag String 30 The Amount returned in a currency aware printable format
ExpiryDate tag N 4 6 The last month of the validity period of the card
MMYY MonthYear
MMYYYY MonthYear
CardholderName tag String 50 The name of the cardholder as embossed on the card.
CardholderEmail tag String 125 The email address of the cardholder
OrderDescription tag String 250 A brief description of the purchase made by the cardholder
AllowBudgetPeriod tag Boolean When this is true a ‘BudgetPeriod’ input field will be present on the CardDetails capture form.
RequestExpiryDate tag N 8 8 The date after which the debit request will expire
YYYYMMDD YearMonthDay
CreateTransactionUrl tag Boolean When this value is ‘true’ a ‘TransactionUrl’ will be returned to the merchant. If ‘false’ a debit request email will
be sent to the ‘CardholderEmail’
TransactionUrl tag String 225 The transaction url that the Cardholder must be redirected to perform a transaction when the command was
‘RequestForDebit’. This will be returned to the merchant in the response if the ‘CreateTransactionUrl’
parameter is set to ‘true’
MerchantName tag String 50 The merchant name associated with the ApplicationID
MerchantAddress tag String 50 The merchant address associated with the ApplicationID
MerchantCity tag String 50 The merchant city associated with the ApplicationID
MerchantCountryCode tag String 2 The merchant country code associated with the ApplicationID
MerchantCountry tag String 50 The merchant country name associated with the ApplicationID
MerchantReference tag String 0 64 A merchant generated identifier that is unique within a specified time period that identifies a transaction
sequence. In the case that the transaction is an Authenticated Collection this field will contain the 14-
character long Contract Reference allocated by the Merchant for this transaction.
OriginalMerchantReference tag String 0 64 A merchant generated identifier of a previous transaction used in a Tokenized PAN transaction
MerchantTrace tag String 0 64 Unique merchant identification for the request
MerchantUSN tag String 0 15 The merchant USN associated with the ApplicationID
OriginalMerchantTrace tag String 64 A reference to the original MerchantTrace previously sent to the iVeri Gateway
OriginalRequestID tag Guid 38 38 The RequestID that was returned as part of the original transaction
PAN tag N. . 20 Primary Account Number (eg Credit card number), may have been extracted from Track2. When this is an
output parameter, then a section of it is dotted out, and safe to display or print
PANMode tag String 0 128 The mechanism by which the PAN was determined from the card. The value is a comma separated list of the
following:
Name Direction Description
Keyed Input/Outp Card number was keyed
ut
Tokenized Output PANFormat TransactionIndex, OriginalMerchantReference or
MSISDN (non -registration) was specified in the request
Swiped Input/Outp Card was swiped. This means that a Track2 must be specified in
ut the request.
Dipped Input/Outp Card was processed while in the card reader slot of the device.
ut This means that a Track2 must be specified in the request.
Tapped Input/Outp Card was processed by a contactless device. This means that a24
ut Track2 must be specified in the request.
ConstructedTrack2 Output For when a partial Track2 is received in the request usually
accompanied by a PINBlock as one of the legs of a PANFormat
“MSISDN” transaction.
CVV Output The CardSecurityCode tag had a value in the request

40
 PIN Output The PINBlock tag had a value in the request
PINCapable Input/Outp No online PIN or EMV data sent to the gateway, but the device is
ut capable to process PIN.
EMV Output EMV data were specified in the request18
EMVFallback Output No EMV data specified in the request, but the service code of the
request Track2 indicate a chip card.
EncryptedPAN Output The value of the PAN tag in the request specified encrypted data
EncryptedTrack2 Output The value of the Track2 tag in the request specified encrypted
data
PurchaseDate tag 4 4 The date on which the purchase was made. Defaults to current Date
MMDD MonthDay
PurchaseTime tag 4 4 The time at which the purchase was made. Defaults to current Time
HHMM HourMinute
ReconReference tag N 0 8 Identifier that the Merchant is returned during a transaction and that also appears in the reconciliation
information supplied by the Acquirer. Either assigned by the iVeri Gateway or derived from the specified
MerchantReference.
StartDate tag A 6 The date of the start of the validity period of the card number. The start date is not available on many cards,
and will remain an optional parameter until the start date becomes more common
MMYY MonthYear
MMYYYY MonthYear
Terminal tag N 0 8 Identifier optionally allocated by the merchant which is intended to group transactions together for reporting
purposes in reconciliation statements.
Track2 tag String 39 Track2 after being read by the swipe device from the magnetic stripe on the card (for card present
transactions). It is inclusive of the beginning and end markers being ; and ? respectively. See section 10.3
TransactionIndex tag Guid 38 38 Unique identifier allocated by iVeri for a series of related transactions. If PANFormat is TransactionIndex,
TransactionIndex is used to locate a previous transaction for the PAN to be resolved.
MobileMoneyID tag N 1 6 An additional transaction identifier returned for a PANFormat “MSISDN” transaction. This tag should be
passed to the Gateway along with OriginalRequestID or OriginalMerchantTrace when the transaction needs
to be Voided.
MSISDN tag String A mobile number required by PANFormat “MSISDN” transactions
VisaCheckoutCallID tag String 0 48 Visa Checkout transaction ID associated with a payment request.
MasterPassTransactionID tag N This is the MasterPass system transaction reference
ForeignAmount Tag String 0 11 When doing a transaction in a foreign currency we need to specify the amount here in the foreign
currency
Mandatory when doing transaction in foreign currency
ForeignCurrency Tag String 3 3 When doing a transaction in a foreign currency we need to specify the foreign currency here
Mandatory when doing transaction in foreign currency
ForeignExchangeID Tag Guid 38 38 Unique Identifier returned in the DynamicCurrencyConversion / MultiCurrencyPricing linked
to the BaseAmount /BaseCurrency and the Amount and Currency in the current transaction
request
Mandatory when doing transaction in foreign currency
PANFormat tag String An enumeration specifying how to obtain the PAN details
PAN Required tag: PAN. If PANFormat is not specified, this value is used if the PAN
tag is set and the Track2 tag not set.
Track2 Required tag: Track2. If PANFormat is not specified, this value is used if the
Track2 tag is set.

41
 TransactionIndex/ Required tags: PAN and one of TransactionIndex or
OriginalMerchantReferenc OriginalMerchantReference. The PAN is the dotted-out number of the card
e/ used with the original transaction. The full PAN is looked up using the given
identifier for the original transaction.
VisaCheckoutCallID Required tags: VisaCheckoutCallID
The VisaCheckoutCallID is used to retireve the Payment Data from the Visa
Checkout Process.
MSISDN Required tag: MSISDN. If in addition, AccountType, PAN (full) and ExpiryDate
are provided, the transaction also serves as a registration of the MSISDN,
thereby enabling future transactions with MSISDN only.
CardHolderPresence tag String 0 128 Specify how the cardholder is involved when a virtual transaction is performed. This tag supersedes the
ElectronicCommerceIndicator tag. The value is a comma separated list of the following:
CardPresent Gets set in the output when a full Track2 was specified in the request. This
value may also be set in the request when the card number was keyed on a
POS device.
CardNotPresent The physical plastic of the card was not present when the request was sent to
the gateway.
eCommerce Gets set in the output when one of the ElectronicCommerceIndicator values
was specified in the request
ThreeDSecure Encryption (SSL) used between CardHolder and Merchant. ThreeDSecure was
successful
ThreeDSecureAttempted Encryption (SSL) used between CardHolder and Merchant. ThreeDSecure was
attempted unsuccessfuly
SecureChannel Encryption (SSL) used between CardHolder and Merchant. ThreeDSecure not
used
ClearChannel No encryption used between CardHolder and Merchant
MOTO Telephonic or mail order
Recurring Transactions submitted by a merchant automatically
Card Detail Parameters
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
Association tag String 0 50 The association to which the card number belongs e.g. VISA or Master card or American Express
BIN tag N 1 9 The Bank Identification Number into which PANs are grouped. Generally, this is the first two to eight digits
CardType tag String 0 50 A description of the type of the card used e.g. Credit Card, Maestro, Electron etc
Issuer tag String 0 50 If the card is local this gives a description of the institution that issued this particular card
Jurisdiction tag String 0 50 Description of whether the card is a local or international card
Result Parameters
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
Code attribute N 3 The numeric Result Code of the completed execution. See section 10.1
Description attribute String 1024 A description of the results of the completed execution. Only relevant where ResultStatus is Unsuccessful [ -
1] or Successful with warning [1]
Source attribute String 128 The source of the result
Previous attribute Boolean In most cases returns false, indicating that the other result values refer to the immediately completed
execution. For advanced usage within a Reprint, to indicate whether the result returned refers to the current
execution, or a previous execution.

42
 Status attribute Z 2 The status of the completed execution
-1 Unsuccessful
0 Successful
1 Successful, with warning
3DSecure Parameters (see section 12)
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
ElectronicCommerceIndicator tag A 0 More commonly known as the ECI, it describes for virtual transactions what steps were taken to secure and
authenticate the transaction. Values are the following subset of CardHolderPresence values: ThreeDSecure,
ThreeDSecureAttempted, SecureChannel and ClearChannel.
CardHolderAuthenticationData tag Base64 28 28 For usage with Verified by Visa / MasterCard SecureCode. The CAVV or UCAF field depending on whether
the card is VISA or Master card. Note: Original binary format length = 20 bytes. Mandatory when
ElectronicCommerceIndicator = ThreeDSecure
CardHolderAuthenticationID tag Base64 28 28 For usage with Verified by Visa / MasterCard SecureCode. The Transaction ID. Note: Original binary format
length = 20 bytes. Mandatory when ElectronicCommerceIndicator = ThreeDSecure
ThreeDSecure_RequestID tag Guid 38 The RequestID that was returned as part of the Enrollment Check that will be used to retrieve data for the
Authentication Validation
ThreeDSecure_ACS_URL tag URL No Limit URL of the Access Control Server of the card-issuing bank where you need to send the
ThreeDSecure_PAReq so that the customer can be authenticated.. The field length can be very large.
ThreeDSecure_PAReq tag Base64 No Limit Digitally signed payer authentication request message that contains a unique transaction ID.The field length
can be very large.
ThreeDSecure_SignedPARes tag Base64 No Limit Digitally signed PARes message that contains the authentication result.The field length can be very large.
ThreeDSecure_VEResEnrolled tag A 1 1 Indicator that shows whether the cardholder is participating in 3DS.
UPOP SecurePlus Parameters
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
UPOP_TransactionTime tag String The time when the Merchant sends the transaction.
Date and time formatted as an ISO 8601 combined date and time string using the extended format.

- Format: YYYY-MM-DDThh:mm:ssZ

- YYYY = year
- MM = month
- DD = day
- hh = hour
- mm = minutes
- ss = seconds
UPOP_RelatedTransactionType tag String 2 2 Related Transaction Type. One of:

- Purchase
- Pre-authorization

The corresponding UnionPay protocol values are:

- 01: Purchase
- 02: Pre-authorization

43
 UPOP_RequestID tag Guid 38 The RequestID that was returned as part of the Request Creation that will be used to retrieve data for the
Authentication Validation
UPOP_FrontUrl tag URL 256 UPOP send the transaction result notification to the URL via cardholder’s browser
UPOP_BackUrl tag URL 256 UPOP send the transaction result notification to the URL via system
UPOP_ACPReq tag Base64 No Limit The Authentication Request message to be posted to the UPOP authentication server
UPOP_Endpoint tag URL The UPOP authentication server endpoint where the Authentication Request message must be posted via
cardholder’s browser
UPOP_ACPRes tag Base64 No Limit The Authentication Response message received from the UPOP authentication server
POS Parameters (see section Error: Reference source not found)
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
DeviceFirmware tag String 64 The firmware (software) currently loaded on the device. This may be set as an integer
DeviceFirmwareVersion tag String 64 The version of the firmware (software) currently loaded on the device.
DevicePINKey tag Hex 32 32 Master/Session encryption specific: The device PIN Key encrypted under the device master key i.e.
DMK(DPK)
MACDevicePINKey tag Hex 8 8 Master/Session encryption specific: The MAC of the device PIN Key i.e. MAC(DPK)
AccountType tag A 0 32 The type of account that this transaction relates to (known to the cardholder)
Savings Credit t

Cheque NotSpecified
AvailableBalance tag N 12 The available amount in the cardholders account given in the smallest unit of currency of the cardholder (not
necessarily the currency of the merchant)
DisplayAvailableBalance tag String 25 The AvailableBalance returned in a currency aware printable format
CashAmount tag N 12 The Cash (back) portion of the Amount. Subject to the constraint: 0 <= CashAmount <= Amount
CurrentBalance tag Z 12 The current balance in the cardholders account given in the smallest unit of currency of the cardholder (not
necessarily the currency of the merchant)
DisplayCurrentBalance tag String 25 The CurrentBalance returned in a currency aware printable format
DeviceMake tag String 64 The manufacturer of the device (terminal). e.g. Dione / Sagem
DeviceSerialNumber tag String 64 The serial number of the device (terminal)
DeviceCycle tag String 20 The current batch id of the device (terminal)
PINBlock tag Hex 16 16 The cardholders PIN encrypted using the current device pin key
KeySerialNumber tag Hex 20 20 DUKPT encryption specific: Mandatory input parameter needed in decryption of a DUKPT PINBlock.
Track2KeySerialNumber tag Hex 20 20 DUKPT Track2 encryption specific: Mandatory input parameter needed in decryption of a DUKPT Track2.
PANKeySerialNumber tag Hex 20 20 DUKPT PAN encryption specific: Mandatory input parameter needed in decryption of a DUKPT PAN.
EMV Parameters (see section 15)
EMV_AuthorisationRequestCryptogr tag Hex 16 EMV tag 9F26
am
EMV_ApplicationIdentifier tag Hex 32 EMV tag 9F06
EMV_ApplicationInterchangeProfile tag Hex 4 EMV tag 82
EMV_CardSequenceNumber tag Hex 2 EMV tag 5F34
EMV_ApplicationTransactionCounter tag Hex 4 EMV tag 9F36
EMV_ApplicationVersion tag Hex 4 EMV tag 9F08
EMV_CardHolderVerificationMethod tag Hex 6 EMV tag 9F34
Result
EMV_CryptogramInformationData tag Hex 2 EMV tag 9F27
EMV_IssuerApplicationData tag Hex 64 EMV tag 9F10
EMV_TerminalCapabilities tag Hex 6 or 8 EMV tag 9F33

44
 EMV_TerminalType tag N 2 EMV tag 9F35
EMV_TransactionType tag N 2 EMV tag 9C
EMV_TerminalVerificationResult tag Hex 10 EMV tag 95
EMV_UnpredictableNumber tag Hex 8 EMV tag 9F37
EMV_TransactionStatusInformation tag Hex 4 EMV tag 9B
EMV_IssuerAuthenticationData tag Hex 16 or 32 EMV tag 91
EMV_IssuerScriptTemplate1 tag Hex 999 EMV tag 71
EMV_IssuerScriptTemplate2 tag Hex 999 EMV tag 72
EMV_ResponseCode tag AN 2 EMV tag 8A
Procurement Parameters (see section Error: Reference source not found)
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
CustomerReferenceIdentifier tag AN 17 Description allocated by the merchant to be printed on the Cardholders statement
CustomerVATRegistrationNumber tag AN 13 The VAT registration number of the Customer if available
DestinationCountry tag A 2 2 The ISO code for the country of residence of the Merchant. e.g. ZA, US, GB
DestinationZIPCode tag AN 0 10 The Customers Destination ZIP code
NationalTax tag N 0 12 The VAT amount of the transaction in the currencys smallest denomination. Depending on the
NationalTaxIndicator this may be included or in addition to the Amount field
NationalTaxIndicator tag N 0 1 Indicates whether VAT is applicable to this transaction.
0 NationalTax is NOT included
1 NationalTax is included
OrderDate tag A 0 6 The date that the order was placed. This is not necessarily the same as the PuchaseDate. Defaults to current
Date
YYMMDD YearMonthDay
PurchaseIdentifier tag AN 0 25 Optional description allocated by the Merchant to be displayed on the Merchants statement. Defaults to
MerchantReference.
ShipFromZIPCode tag AN 0 10 The ZIP code of the Merchant (Shipping source ZIP code)
ShippingAmount tag N 0 12 The amount charged to the customer for shipping charges in the currencys smallest denomination.
ShippingTaxRate tag 0 4 The VAT rate that applies to the ShippingAmount. It is a percentage and not the actual value. The value is the
rate multiplied with 10000.
TransactionDiscount tag N 0 12 Discount value for the transaction as a whole, it is the result of individual line item percentage discounts
applied to line items. In the currency’s smallest denomination
UniqueVATInvoiceReferenceNumber tag AN 0 15 The invoice number allocated by the merchant and appears on the merchant’s invoice given to the customer.
This is an optional field is independent of the Merchant Reference.
Procurement LineItem Parameters (see section Error: Reference source not found)
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
Discount subtag N 0 12 The total discount for the line item in the currencys smallest denomination.
ItemCommodityCode subtag N 0 4 The ISO commodity code for the line item unit.
ItemDescriptor subtag N 0 26 A description for the line item unit.
ProductCode subtag AN 0 12 The merchants code for the line item unit.
Quantity subtag N 0 8 The total number of line item units.
TaxRate subtag N 0 4 The VAT rate applicable to the line item. The value is the rate multiplied with 10000.
Total subtag N 0 12 The total amount for the line item in the currencys smallest denomination. The value equals Quantity x
UnitCost - Discount.

45
 UnitCost subtag N 0 10 The cost of a line item unit in the currencys smallest denomination.
UnitOfMeasure subtag AN 0 12 The measurement unit description.
PassengerFirstName subtag AN 0 60 Passengers first name.
PassengerLastName subtag AN 0 60 Passengers last name
PassengerID subtag AN 0 32 ID of the passenger to whom the ticket was issued. For example, you can use this field for
the frequent flyer number
PassengerStatus subtag AN 0 32 Your companys passenger classification, such as with a frequent flyer program. In this case,
you might use values such as standard, gold, or platinum.
PassengerType subtag AN 0 32 Passenger classification associated with the price of the ticket. You can use one of the
following values:
• ADT: Adult
• CNN: Child
• INF: Infant
• YTH: Youth
• STU: Student
• SCR: Senior Citizen
• MIL: Military
Note: The fields in Blue will only be used when doing CyberSource Advanced Fraud Screening.
Fleet Parameters (see section Error: Reference source not found)
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
CustomerReferenceIdentifier tag AN 8 Contains two subfields, and is in the format: “Type” + “Odometer Reading”
Type Private (P) or Business (B). Max Length = 1. Data Type = A
Odometer reading Odometer reading. Max Length = 7. Data Type = N
Fleet LineItem Parameters (see section Error: Reference source not found)
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
ProductCode subtag AN 0 64 The iVeri Product Code for the Fleet LineItem. The latest set of iVeri Fleet Product Codes can be obtained via
the Inventory download command (Only use the ProductCodes with Type=Fleet). The set at time of writing is
provided here.
FLEET OIL Oil
FLEET SERVICE Service
FLEET TYRES Tyres
FLEET ACCIDENTS Accidents
FLEET ACCESSORIES Accessories
FLEET BRAKES Brakes
FLEET EXHAUSTS Exhausts
FLEET SHOCK Shock absorbers
ABSORBERS
FLEET BATTERIES Batteries
FLEET GLASS Glass
FLEET TRUCK STOP Truck Stop
FLEET FORECOURT Forecourt Shop
SHOP

46
 FLEET HOTEL Hotel Expenses
EXPENSES
FLEET TOLL GATE Toll Gate
FLEET MISCELLANEOUS Miscellaneous
FLEET PREMIUM Premium Fuel
FLEET REGULAR Regular Fuel
FLEET SASOL Sasol Fuel
FLEET DIESEL Diesel Fuel
FLEET UNLEADED Unleaded Super Fuel
SUPER
FLEET UNLEADED Unleaded Premium Fuel
PREMIUM
FLEET AVIATION Aviation Fuel
Quantity subtag N 0 8 The total number of line item units
QuantityDecimalPlaces subtag N 0 4 The number of implied decimals in the Quantity
UnitCost subtag N 0 10 The cost of a line item unit in the currencys smallest d enomination

AirlineData Parameters (see section Error! Bookmark not defined.)

Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
PassengerName subtag AN 0 20 Passenger name as printed on ticket.
PrimaryTicketNumber subtag N 0 15 The ticket number.
FirstDepartureLocationCode subtag AN 0 3 Code for departure airport location, eg. JNB for Johannesburg
FirstArrivalLocationCode subtag AN 0 3 Code for destination airport location, eg. JNB for Johannesburg
PNRNumber subtag AN 0 6 The PNR number
OfficeIATANumber subtag N 0 8 The office IATA number
OrderNumber subtag AN 0 8 The order number
PlaceOfIssue subtag AN 0 20 The ticket office location
DepartureDate subtag N 0 8 Date of departure in yyyymmdd format
CompleteRoute subtag AN 0 255 Concatenation of individual travel legs in the format ORIG1-DEST1[:ORIG2-DEST2...:ORIGn-DESTn], f
or example:CPT-JNB :JNB-:NBO. For airport codes
DepartureTime subtag AN 0 15 Departure time of the first leg of the trip. Use one of the following formats:
• HH:mm \"GMT\"zzz
• HH = two digit hour in 24-hour format
• mm = two digit minutes
• zzz = time zone of the departing flight,
for example: If the airline is based in city A, but
the flight departs from city B, z is the time zone
of city B at the time of departure.

Important For travel information, use GMT

instead of UTC, or use the local time zone.
Examples
19:55 GMT+02:00

47
 19:55 GMT+0200
11:25 GMT-03:00
11:25 GMT-0300
Note When specifying an offset from GMT,
the format must be exactly as specified in the
example. Insert no spaces between the time
zone and the offset.
JourneyType subtag AN 0 32 Type of travel, for example: one way or round trip.
Note: The fields in Blue will only be used when doing CyberSource Advanced Fraud Screening and will not be recorded on the iVeri system.

CyberSource Parameters (see section 18.5.2)

Parameter Node Data Type Required Maximum Description
Type Length
DeliveryMethod subtag AN O 255 Physical or Virtual
DeviceFingerprintID subtag AN O 88 Session ID for the fingerprint.
BillTo_FirstName subtag AN R 60 First name of cardholder
BillTo_LastName subtag AN R 60 Last name of cardholder
BillTo_Street subtag AN R 60 Street address of cardholder
BillTo_City subtag AN R 50 Billing city for cardholder
BillTo_State subtag AN O 2 State or province of the cardholder. Required for U.S. and Canada.
Use the two-character state, province, or territory codes.
BillTo_Country subtag AN R 2 Billing country for cardholder. Use the two-character country codes.
BillTo_PostalCode subtag AN O 10 Postal code of the billing address. Required only if the BillTo_Country field is US or CA
BillTo_Email subtag AN R 100 Email address of the cardholder
BillTo_IPAddress subtag AN O 15 IP address of the cardholder as reported by your Web server via socket information.
Note: If any of the fields marked in Red is unavalable all the fields in Red will be replaced with defaults specified by CyberSource

AuthenticatedCollectionData Parameters (see section nn)

Parameter Node Data Type Require Maximum Description
Type d Length
AccountNumber subtag AN R 19 The account number that the payor is agreeing to allow the payee debit.
DebtorIdentification subtag AN R 35 Some data to identify the payor e.g. ID Number
MaximumCollectionAmount subtag AN R 12 The maximum amount that the payor is agreeing to in the smallest unit of the currency specified (eg in cents)
Note: If any of the fields marked in Red is unavalable all the fields in Red will be replaced with defaults

48
 ForeignExchange Enquiry Request Parameters
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
Currency subtag A 3 3 The ISO 4217 currency code of the value of the transaction. e.g. USD or ZAR or GBP
Amount subtag N 0 11 The total value of the transaction in the smallest unit of the currency specified (eg in cents)
ForeignExchange Tag AN Contains a collection of ForeignExchangeItems

ForeignExchangeItem Parameters
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
Version attribute AN 0 20 Reserved for Future use
ForeignExchangeID subtag Guid 38 38 Universally Unique Identifier.
Note: This tag must be set when a transaction is done to the gateway with a foreign currency
ForeignExchangeProvider subtag AN 0 64 Foreign exchange provider the request was done to
BaseCurrency subtag A 3 3 Merchant’s local currency. alphabetic currency code
BaseAmount subtag N 0 11 Amount of transaction in base currency
ForeignCurrency subtag N 3 3 Cardholder’s currency. alphabetic currency code
ForeignAmount subtag AN 0 11 Amount converted to ForeignCurrencyThis is the foreign exchange rate used for DCC or MCP transactions
ExchangeRate subtag N 0 20 This is the foreign exchange rate used for DCC or MCP transactions.
ExpiryDateTime subtag N 0 8 Shows the expiration date and time in the format of UTC (Coordinated Universal Time).
MarginPercentage This value is the markup applied to foreign exchange rate for the transaction.
This markup is also referred to as the rate margin which corresponds to the margin that is applied to the
wholesale foreign exchange rate used in the DCC transaction.
CommissionPercentage Reserved for the purpose of meeting regulatory requirements where applicable.

49
5.5 Parameters per Action
5.5.1 Input Parameters per Action

The following table uses the following key for input parameters per action:
M Mandatory
O Optional
C Conditional
blank not relevant

Context Parameter Additional Authorisation with TransactionIndex

AuthorisationReversal with TransactionIndex
Authorisation with VisaCheckoutCallID

ThreeDSecureValidateAuthentication

MasterPassQuickResponseCode
MasterPassPaymentNotification
ThreeDSecureCheckEnrollment
Debit with VisaCheckoutCallID

DynamicCurrencyConversion
Credit with TransactionIndex
Debit with TransactionIndex
Authorisation with Track2

Balance Enquiry with PIN

PAN Enquiry with Track2

Authorisation with PAN

PAN Enquiry with PAN

MultiCurrencyPricing
Get Device PIN Key
PANToken Enquiry
Credit with Track2
Debit with Track2

RequestForDebit
Credit with PAN
Debit with PAN

Debit with PIN

Ping
Void

Core ApplicationID M M M M M M M M M M M M M M M M M M M M M M M M M M
Core Category M M M M M M M M M M M M M M M M M M M M M M M M M M M
Core CertificateID M M M M M M M M M M M M M M M M M M M M M M M M M M M
Core Gateway O O O O O O O O O O O O O O O O O O O O O O O O O O O
Core Command M M M M M M M M M M M M M M M M M M M M M M M M M M M
Core Mode M M M M M M M M M M M M M M M M M M M M M M M M M M M
Common Amount M M M M M O M M M O M M O M M M M M
Common AuthorisationCode O O O
Common BudgetPeriod O O O O O O O
Common CardSecurityCode O O O O O O O O O
Common PAN M M M M M M M O
Common Currency O O O O O O O O O O M M M M M
Common VisaCheckoutCallID M
Common ExpiryDate M O O O O O O O M M M
Common CardholderName M
Common MerchantReference M M M M M M M M M M M M M M M M M M
Common OriginalMerchantReference C C C
Common MerchantTrace O O O O O O O O O O O O O
Common OriginalMerchantTrace C
Common OriginalRequestID C
Common PurchaseDate O O O O O O O O O O O O O
Common PurchaseTime O O O O O O O O O O O O O
Common StartDate O O O O O O O
Common Terminal O O O O O O O O O O O O O
Common Track2 M O O M M O M O M M
Common TransactionIndex M M M M
Common MobileMoneyID O
Common MSISDN C

50
 Context Parameter

Additional Authorisation with TransactionIndex

AuthorisationReversal with TransactionIndex
Authorisation with VisaCheckoutCallID

ThreeDSecureValidateAuthentication

MasterPassQuickResponseCode
MasterPassPaymentNotification
ThreeDSecureCheckEnrollment
Debit with VisaCheckoutCallID

DynamicCurrencyConversion
Credit with TransactionIndex
Debit with TransactionIndex
Authorisation with Track2

Balance Enquiry with PIN

PAN Enquiry with Track2

Authorisation with PAN

PAN Enquiry with PAN

MultiCurrencyPricing
Get Device PIN Key
PANToken Enquiry
Credit with Track2
Debit with Track2

RequestForDebit
Credit with PAN
Debit with PAN

Debit with PIN

Ping
Void
Common PANFormat O M O M O
Common PANMode O O O O O O O O O O O O O O O O
Common CardHolderPresence O O O O O O
Common CardholderEmail M
Common OrderDescription O
Common AllowBudgetPeriod O
Common RequestExpiryDate O
Common CreateTransactionUrl O
3DSecure ElectronicCommerceIndicator O O O O O
3DSecure CardHolderAuthenticationData O O O O O
3DSecure CardHolderAuthenticationID O O O O O
3DSecure ThreeDSecure_RequestID M
3DSecure ThreeDSecure_SignedPARes M
MasterPass MasterPassAction M
MasterPass MasterPassMerchantID M
MasterPass MasterPassShortDescription
MasterPass MasterPassCodeExpiryDate
MasterPass MasterPassMerchantName
MasterPass MasterPassCode
MasterPass MasterPassTransactionID
POS AccountType O O
POS CashAmount O
POS DeviceFirmware O O O
POS DeviceFirmwareVersion O O O
POS DeviceMake M M M
POS DeviceSerialNumber M M M
POS DeviceCycle O O O O O O O
POS KeySerialNumber C C
POS Track2KeySerialNumber C C C C C C
POS PANKeySerialNumber C C C C C
Procurement CustomerReferenceIdentifier O O O O O O
Procurement CustomerVATRegistrationNumber O O O O O O
Procurement DestinationCountry O O O O O O
Procurement DestinationZIPCode O O O O O O
Procurement NationalTax O O O O O O
Procurement NationalTaxIndicator O O O O O O
Procurement OrderDate O O O O O O
Procurement PurchaseIdentifier O O O O O O
Procurement ShipFromZIPCode O O O O O O
Procurement ShippingAmount O O O O O O
Procurement ShippingTaxRate O O O O O O
Procurement TransactionDiscount O O O O O O
Procurement UniqueVATInvoiceReference O O O O O O
Number
Procurement Discount O O O O O O
: LineItem
Procurement ItemCommodityCode O O O O O O

51
 C
Y
Fleet

Fleet:
Fleet:
Fleet:

blank
LineItem
LineItem
LineItem
: LineItem
: LineItem
: LineItem
: LineItem
: LineItem
: LineItem
: LineItem
: LineItem
Context

Procurement
Procurement
Procurement
Procurement
Procurement
Procurement
Procurement

Total

not relevant
TaxRate

Quantity
Quantity

UnitCost
UnitCost
Parameter

ProductCode
ProductCode
ItemDescriptor

UnitOfMeasure

relevant (may be populated)

returned if supported by Acquirer
CustomerReferenceIdentifier
Authorisation with PAN
Authorisation with Track2
Authorisation with VisaCheckoutCallID
Additional Authorisation with TransactionIndex
AuthorisationReversal with TransactionIndex
Debit with PAN

O O
O O
O O
O O
O O
O O
O O
O O
O O
O O
O O

Debit with Track2

Debit with PIN
Debit with VisaCheckoutCallID
Debit with TransactionIndex
Credit with PAN
Credit with Track2

O O O O
O O O O
O O O O
O O O O
O O O O
O O O O
O O O O
O O O O
O O O O
O O O O
O O O O

Credit with TransactionIndex

Void
Balance Enquiry with PIN
PAN Enquiry with PAN
PANToken Enquiry
PAN Enquiry with Track2
Ping
Get Device PIN Key
ThreeDSecureCheckEnrollment
ThreeDSecureValidateAuthentication
RequestForDebit
MasterPassQuickResponseCode

52
MasterPassPaymentNotification
DynamicCurrencyConversion
MultiCurrencyPricing
Y relevant (may be populated)
C returned if supported by Acquirer
blank not relevant

Context Parameter

Additional Authorisation with TransactionIndex

AuthorisationReversal with TransactionIndex

ThreeDSecureValidateAuthentication

MasterPassQuickResponseCode
MasterPassPaymentNotification
ThreeDSecureCheckEnrollment

DynamicCurrencyConversion
Credit with TransactionIndex
Debit with TransactionIndex
Authorisation with Track2

Balance Enquiry with PIN

PAN Enquiry with Track2

Authorisation with PAN

PAN Enquiry with PAN

MultiCurrencyPricing
Get Device PIN Key
PANToken Enquiry
Credit with Track2
Debit with Track2

RequestForDebit
Credit with PAN
Debit with PAN

Debit with PIN

Ping
Void
Core ApplicationID Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y
Core Command Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y
Core Mode Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y
Core RequestID Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y
Common Acquirer Y Y Y Y Y Y Y Y Y Y Y Y Y
Common AcquirerDate Y Y Y Y Y Y Y Y Y Y Y Y Y
Common AcquirerReference Y Y Y Y Y Y Y Y Y Y Y Y Y
Common AcquirerTime Y Y Y Y Y Y Y Y Y Y Y Y Y
Common Amount Y Y Y Y Y Y Y Y Y Y Y Y
Common DisplayAmount Y Y Y Y Y Y Y Y Y Y Y Y
Common AuthorisationCode Y Y Y Y Y Y Y Y Y Y Y
Common Currency Y Y Y Y Y Y Y Y Y Y Y C Y
Common MerchantName Y Y Y Y Y Y Y Y Y Y Y
Y
Common MerchantAddress Y Y Y Y Y Y Y Y Y Y Y
Y
Common MerchantCity Y Y Y Y Y Y Y Y Y Y Y
Y
Common MerchantCountryCode Y Y Y Y Y Y Y Y Y Y Y
Y
Common MerchantCountry Y Y Y Y Y Y Y Y Y Y Y
Y
Common MerchantReference Y Y Y Y Y Y Y Y Y Y Y Y Y
Common MerchantTrace Y Y Y Y Y Y Y Y Y Y Y Y
Common MerchantUSN Y Y Y Y Y Y Y Y Y Y Y Y Y
Common PAN Y Y Y Y Y Y Y Y Y Y Y Y Y Y
Common ReconReference Y Y Y Y Y Y Y Y Y Y Y Y
Common Terminal Y Y Y Y Y Y Y Y Y Y Y Y
Common TransactionIndex Y Y Y Y Y Y Y Y Y Y Y Y Y
Common MobileMoneyID C
Common PANMode Y Y Y Y Y Y Y Y Y Y Y Y Y Y
Y
Common CardHolderPresence Y Y Y Y Y Y Y Y Y Y Y Y Y
Y
Common TransactionUrl C
3DSecure ElectronicCommerceIndicator C C C C C C C C C C C Y Y

53
 Context Parameter

Additional Authorisation with TransactionIndex

AuthorisationReversal with TransactionIndex

ThreeDSecureValidateAuthentication

MasterPassQuickResponseCode
MasterPassPaymentNotification
ThreeDSecureCheckEnrollment

DynamicCurrencyConversion
Credit with TransactionIndex
Debit with TransactionIndex
Authorisation with Track2

Balance Enquiry with PIN

PAN Enquiry with Track2

Authorisation with PAN

PAN Enquiry with PAN

MultiCurrencyPricing
Get Device PIN Key
PANToken Enquiry
Credit with Track2
Debit with Track2

RequestForDebit
Credit with PAN
Debit with PAN

Debit with PIN

Ping
Void
3DSecure CardHolderAuthenticationData Y Y
3DSecure CardHolderAuthenticationID Y Y
3DSecure ThreeDSecure_RequestID Y Y
3DSecure ThreeDSecure_ACS_URL Y
3DSecure ThreeDSecure_PAReq Y
Card Detail Association Y Y Y Y Y Y Y Y Y Y Y Y
Y
Card Detail BIN Y Y Y Y Y Y Y Y Y Y Y Y Y
Y
Card Detail CardType Y Y Y Y Y Y Y Y Y Y Y Y
Y
Card Detail Issuer Y Y Y Y Y Y Y Y Y Y Y Y
Y
Card Detail Jurisdiction Y Y Y Y Y Y Y Y Y Y Y Y
Y
Result Code Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y
Result Description Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y
Result Source Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y
Result Status Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y Y
POS AccountType C C
POS AvailableBalance C Y
POS CurrentBalance C Y
POS DisplayAvailableBalance C C
POS DisplayCashAmount Y Y
POS DisplayCurrentBalance C C
POS DevicePINKey Y
POS MACDevicePINKey Y
MasterPass MasterPassCode O
MasterPass MasterPassCodeExpiryDate O
MasterPass MasterPassMerchantName O
MasterPass MasterPassShortDescription O
MasterPass MasterPassMerchantId Y
Forex ForeignExchangeID Y Y
Forex ForeignExchangeProvider Y Y
Forex BaseCurrency Y Y
Forex BaseAmount Y
Forex ForeignCurrency Y Y
Forex ForeignAmount Y
Forex ExchangeRate Y Y
Forex ExpiryDateTime Y Y
Forex MarginPercentage Y Y
Forex CommissionPercentage Y Y

54
6. TRANSACTION SEQUENCES AND
TERMINOLOGY

6.1 Overview
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

6.2 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).

55
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]:
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.

6.3 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.

56
6.4 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 (section 7.2.1)

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

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

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

58
7. ENSURING END TO END TRANSACTION
INTEGRITY

7.1 Overview
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.

7.2 Individual transactions

7.2.1 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:
communications error between merchant and cardholder
printer could not print the invoice
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.

59
 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 similar to:

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);

A Void has one of the following responses:

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)

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.

60
 Implement a retry mechanism discussed below without using a Void.

7.2.2 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.

7.2.2.1 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:

If the previous attempt was successful, a successful result is returned.
If the previous attempt was unsuccessful, the transaction request is retried.

61
 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.

7.2.2.2 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.
7.2.2.3 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!

62
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”.
7.2.3 Enquiry
A merchant with a doubt of the current status of a transaction can determine its status by:
Performing a “Transaction lookup” within iVeri BackOffice
Download a “Reconciliation file” (can be automated with iVeri FileTransfer) and
compare records.
Check an immediate notification mechanism (such as email for iVeriBatch clients,
and SMS for iVeri Voice clients)
Look in the logs for an exception message containing details of a misconfiguration
or a coding error.
7.2.4 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.

7.3 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.

63
7.3.1 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.

7.3.2 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.

7.3.3 Recurring transaction checking

The Recurring transaction checking period is an additional mechanism to protect merchants
against undesired double debiting.

64
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.

65
8. COMMON PARAMETERS

8.1 Result Codes

The following is the list of Result Codes:
Result Status Result Result Description Only relevant when
Code
0 (OK) 0 N/A (Approved)
-1 (Not OK) 1 Timeout waiting for response
-1 (Not OK) 2 Gateway unreachable
-1 (Not OK) 3 Hot card
-1 (Not OK) 4 Denied
-1 (Not OK) 5 Please call
-1 (Not OK) 6 Card Address failure
1 (Warning) 6 Warning: Approved but Card Address failure
-1 (Not OK) 7 Card Security Code failure
1 (Warning) 7 Warning: Approved but Card Security Code failure
-1 (Not OK) 8 Card Type not accepted
-1 (Not OK) 9 Unable to process the transaction
-1 (Not OK) 10 Card blocked
-1 (Not OK) 11 Invalid amount
-1 (Not OK) 12 Invalid budget period
-1 (Not OK) 13 Void unsuccessful Command Void
-1 (Not OK) 14 Invalid card number
-1 (Not OK) 15 Invalid track2
-1 (Not OK) 16 Invalid card date (Expiry Date or Card period)
-1 (Not OK) 18 Invalid authorisation code
-1 (Not OK) 19 Incorrect PIN PINBlock submitted
-1 (Not OK) 20 Device PIN Key has expired PINBlock submitted
1 (Warning) 21 Warning: Approved but Cash Denied PINBlock and CashAmount
submitted
-1 (Not OK) 22 EMV not supported
-1 (Not OK) 23 Card information not present
-1 (not OK) 24 Invalid Recurring Account CardHolderPresence Recurring
specified
1 (Warning) 25 Warning: Approved but Identification Required
-1 (Not OK) 100 The requested file is not available for download FileTransfer
-1 (Not OK) 101 The specified file has already been uploaded FileTransfer
-1 (Not OK) 255 General Error (Exception)

The following Result Codes require special mention:

Result Res Result Examples Action

Status ult Description
Cod
e
-1 1 Timeout waiting for - There was no reply from the card holder’s - Request can be automatically retried (with a wait in
(Not OK) response issuer between)
- Request was not processed within an
expected time period
-1 9 Unable to process - The connection between iVeri and the - Request can be automatically retried (with a wait in
(Not OK) the transaction acquirer is down between)
- The iVeri Gateway is offline for maintenance
-1 255 General Error - The ApplicationID has been suspended - Request can be retried only after someone has read

66
(Not OK) (Exception) - Could not establish a connection to the iVeri the error description and done an action to fix it
Gateway due to no network connection from
the client.
- The merchant code is calling the iVeri
Gateway incorrectly.

8.2 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.

A 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 or 5959595959595959 returns "Authorised"
2121212121212121 randomly returns "Hot Card", "Please Call" or "Denied"
5454545454545454 randomly returns "Unable to process" or times out
All other card numbers returns "Invalid card number"
(eg "1111222233334444")

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.

8.3 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:

67
 Field Description Length Format
(bytes)
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

The Track2 read from by the card reader typically contains the following fields (at most 40 bytes):
SS PAN FS DATE SVC CD Discretionary Data ES LRC

The 1-byte Longitudinal Redundancy Check (LRC) should not be sent to the iVeriGateway.
The End Sentinel (ES) may need to be converted to? (0x3F)

8.3.1 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 Description MasterC Visa
Posit ard
ion#1
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 Description MasterC Visa

Posit ard
ion#2
0 Normal Authorisation Yes Yes
2 Positive Online Authorisation Required Yes Yes

Value Description MasterC Visa

Posit ard
ion#3
0 PIN Required Yes Yes
1 Normal Cardholder Verification, No Restrictions Yes Yes
2 Normal Cardholder Verification – Goods and services Yes No
only at point of interaction (no cash back)
3 ATM Only, PIN Required Yes Yes

68
 5 PIN Required – Goods and services only at point of Yes No
interaction (no cash back)
6 Prompt for PIN if PIN Pad Present Yes Yes
7 Prompt for PIN if PIN Pad Present – Goods and services Yes No
only at point of service (no cash back)

8.4 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.

69
9. SPECIALIZED TECHNIQUES

9.1 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:

the merchant is communicating with the iVeri Gateway, and
the merchant configuration is active, and
the iVeri Gateway is online, and
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 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:

70
 go into Store and Forward mode
notify a certain person
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.

A merchant abusing the Ping command may have their use of it suspended.

71
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.

8.2 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.

72
 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 x2 x1 x2 x1 x2 x1 x2
Products 8 2 16 7 18 4 14
3 Sum the integers 8 + 2 + (1+6) + 7 + (1+8) + 4 + (1+4) = 42
4 Derive the Check Digit 50 – 42 = 8

9.3 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

See section 20

73
10. THREEDSECURE (ALSO KNOWN AS
“VERIFIEDBYVISA” OR “MASTERCARD
SECURECODE”)

“Verified by VISA” (VbV), “MasterCard SecureCode” and “American Express SafeKey” are online
services that use personal passwords or identity information to help protect against unauthorised
usage of VISA, MasterCard or American Express cards within the Internet environment.

10.1 3DSecure implementation directly to a 3DSecure

provider
Using this approach, the merchant implements the ThreeDSecure provider's message flow,
determine whether or not to proceed with the transaction based on the 3D Secure Process Flow
diagram of section 12.1.2 and send the iVeri Gateway the TheeDSecure V_XML tags if the
transaction may continue.

10.1.1 3DSecure V_XML tags to be sent to the iVeri Gateway

The merchant uses the flow diagram to decide whether to process or fail the transaction. When
processing the transaction, the merchant determines the value of the
ElectronicCommerceIndicator (ECI) flag, and sets the following parameters (tags):
ElectronicCommerceIndicator (ECI),
CardHolderAuthenticationData (CAVV) and

CardHolderAuthenticationID (XID)
along with the rest of the transaction information and sends out the authorisation to the payment
network.

The following are the iVeri parameters (tags) specific to 3D Secure:

“ElectronicCommerceIndicator” which holds the enumerated ECI indicator
which (if specified) is one of: [ClearChannel | SecureChannel |
ThreeDSecureAttempted | ThreeDSecure]. The difference between

74
 SecureChannel or ClearChannel is whether SSL is used between the
cardholder and the merchant.
“CardHolderAuthenticationData” which holds the base64 encoded CAVV
data
“CardHolderAuthenticationID” which holds the base64 encoded XID data

These 3 tags are set using iVeri Enterprise, for example:

enterprise.setTag("ElectronicCommerceIndicator","ClearChannel");
enterprise.setTag("CardHolderAuthenticationData",cavv);
enterprise.setTag("CardHolderAuthenticationID",xid);

These tags are only needed to be set in an initial transaction, not when a TransactionIndex is
set.
In other words, if a merchant performs an Authorisation and then a follow up Debit, then the
above tags need only be set within the Authorisation.

10.1.2 (Nothing here?)

75
10.1.3 3DSecure Process Flow Diagram

76
10.1.4 3DSecure implementation to Bankserv
The Centinel MAPS (Merchant Authentication Processing System) performs the required
interaction, message formatting and processing required by the different payment authentication
initiatives such as:
Verified by Visa
MasterCard SecureCode
SPA etc.

The Centinel MAPS product is a product of Cardinal Commerce and is distributed in South Africa
by Bankserv. The Centinel MAPS service is hosted by Bankserv.

For Centinel integration queries and assistance, contact: [email protected]

10.1.5 Test Environment

The following information is needed when using the Centinel MAPS test environment for
MasterCard SecureCode and Verified by VISA
URL (MPI): https://msgtest.bankserv.co.za/maps/txns.asp

American Express SafeKey

URL (MPI): https://msgtest.bankserv.co.za/maps/amex.asp

ProcessorID :1000
Password : DeMo123
MerchantID : 12345678

The Centinel MAPS test cards are available within the “CNP Secure Test Cards” document. These
test cards are different to the iVeri test cards. Therefore, when sending test cards to Centinel, use
their test cards, and thereafter when sending the transaction to iVeri, set the card information
according to section 8.2.

10.1.6 Live Environment

The following information is needed when using the Centinel MAPS live environment: MasterCard
SecureCode and Verified by VISA

77
 URL (MPI): https://msgnedcor.bankserv.co.za/maps/txns.asp

American Express SafeKey

URL (MPI): https://msgnedcor.bankserv.co.za/maps/amex.asp

ProcessorID :1000

Password : (Please request this from BankServ, send an email to [email protected] with
your merchant number and Processer ID)

MerchantID: This must be obtained from your Distributer

10.1.7 BankServ 3DSecure Message Flow

At the point of checkout, the Cardholder selects an appropriate payment method
based on the initiatives supported by the Merchant. The Cardholder fills out the
checkout form including the payment option and clicks buy.
If the association of the Card is a MasterCard or Visa, and the merchant is enabled
for 3D Secure, then the Merchant passes a cmpi_lookup message to Centinel
MAPS, containing the following values based on the payment information:
FieldName Description
MsgType cmpi_lookup
Version Application Version identifier
ProcessorId Application Processor identifier
MerchantId Application Merchant identifier
OrderNumber Order number from the Merchant Website
PurchaseAmount Formatted total sale transaction
RawAmount Total amount without decimalization
PurchaseCurrency 3-digit numeric ISO4217 currency code for the sale amount
PAN Credit card number used for transaction
PANExpr Credit card expiry date, formatted YYMM

Sample Message:
<CardinalMPI>

<MsgType>cmpi_lookup</MsgType>

<Version>1.3</Version>

<ProcessorId>1000</ProcessorId>

<MerchantId>12345678</MerchantId>

<OrderNumber>IVERI00001</OrderNumber>

<PurchaseAmount>ZAR11</PurchaseAmount>

<RawAmount>11</RawAmount>

78
<PurchaseCurrency>710</PurchaseCurrency>

<PAN>4242424242424242</PAN>

<PANExpr>0410</PANExpr>

</CardinalMPI>

This message contains all the required information supplied by the cardholder in
order to check the enrollment of the cardholder.
Based on the card number range stored within Centinel MAPS, a Verify Enrollment
Request (VEReq), message will be sent to the Enrollment directory server.
The Enrollment directory server will send the VEReq to the cardholders Issuing
Bank Access Control Server (ACS) where it will verify the enrollment status.
The Verify Enrollment Response (VERes), is then passed back to the Directory
server with the corresponding ACS url, if applicable.
The information is then passed back to Centinel MAPS where it is verified and the
Payment Authentication Request (PAReq) is created.
The lookup response is then returned to the Merchant, Containing the following
values:
FieldName Description
ErrorDesc Application error description for the associated errornumber
ErrorNo Application error number, non zero, encountered while attempting to process the message request
TransactionId This number is required to be passed on the cmpi_authenticate message
Payload Contains the encoded PAReq generated by MAPS, available if Enrolled = Y
SPSHiddenFields Contains the SPA hidden form fields, Available if Master card transaction
Enrolled CardHolder enrolled status
(Y - enrolled, N - not enrolled, U - Cardholder enrolled but authentication unavailable)
ACSUrl Contains the fully qualified path of the Issuers ACS, this is used by the merchant to redirect the Cardholder,
available if Enrolled = Y

Sample Message:
<CardinalMPI>

<ErrorDesc></ErrorDesc>

<ErrorNo>0</ErrorNo>

<TransactionId>jMpkHtqeHD+6GTlUhafK</TransactionId>

<Payload>*******PAReqMessage********</Payload>

<SPAHiddenFields></SPAHiddenFields>

<Enrolled>Y</Enrolled>

<ACSUrl>http://dns/path</ACSUrl>

79
</CardinalMPI>

Based on the existence of the ACS url in the lookup response the Merchant will
redirect the cardholder’s browser to the corresponding ACS server. The cardholder
enters their authentication data and initiates the Authentication process directly
with the ACS server.
The ACS, in conjunction with the Card Issuer, authenticates the cardholder. The
Payment Authentication Response (PARes), is send back to the Cardholder via the
web browser.
The PARes is forwarded to the Merchant.
The Merchant initiates a cmpi_authenticate message to the Centinel MAPS,
containing the following values:
FieldName Description
MsgType cmpi_authenticate
Version Application Version identifier
TransactionId This links the cmpi_lookup with the cmpi_authenticate message together
ProcessorId Application Processor identifier
MerchantId Application Merchant identifier
PAResPayload PARes generated by the Issuer ACS

Sample Message:
<CardinalMPI>

<msg_type>cmpi_authenticate</msg_type>

<version>1.3</version>

<processor_id>1000</processor_id>

<merchant_id>12345678</merchant_id>

<order_number>AUT000191</order_number>

<PAResPayload>*******PAResMessage********</PAResPayload>

</CardinalMPI>

The authenticate response is then returned to the Merchant, Containing the following values:
FieldName Description
ErrorDesc Application error description for the associated errornumber
ErrorNo Application error number, non zero, encountered while attempting to process the message request
Cavv Transaction stain from PARes
SignatureVerification Status of the signature verification of the PARes message
(Y - validated successfully, N - not validated)
Xid Transaction Xid from PARes
EciFlag E-Commerce indicator from PARes

80
PAResStatus Transaction status from PARes
(Y, N, U or A)

Sample Message:
<CardinalMPI>

<ErrorDesc></ErrorDesc>

<ErrorNo>0</ErrorNo>

<Cavv>AAABAJEDFwAAAAAAAAMXAAAAAAA=</Cavv>

<SignatureVerification>Y</SignatureVerification>

<Xid>QPqHUYfUAn1c4OJGzEM2lEzeAYU=</Xid>

<EciFlag>05</EciFlag>

<PAResStatus>Y</PAResStatus>

</CardinalMPI>

10.2 3DSecure implementation using V_XML Enquiry

commands
Payer Authentication services enable you to quickly and easily add support for:
Verified by Visa
MasterCard SecureCode
Amex SafeKey
SPA etc.

To find out if your Visa- or MasterCard-branded card is supported by Payer Authentication,

contact your payment
processor.

These card authentication services deter unauthorized card use and enable you to receive
protection, liability shift, from fraudulent chargeback activity.

Payer Authentication through has been made available by iVeri with the addition of the following
Enquiry commands:
ThreeDSecureCheckEnrollment

81
 ThreeDSecureValidateAuthentication

Note: The Merchant has to be enabled for 3DSecure Checking on the iVeri Gateway.

10.2.1 Checking Enrollment

The goal is to check if the card is enrolled and to authenticate the results if it is enrolled. To do so,
you would build up a Enquiry request with the command set as ThreeDSecureCheckEnrollment.
The following required parameters needs to be sent:
ApplicationID
CertificateID
Mode
MerchantReference
Amount
Currency
PAN
ExpiryDate

If the Enrollment Check was unsuccessful the merchant is not permitted to continue with the
transaction. Instead, ask the customer for another form of payment.

If the Enrollment Check was successful, the following parameters will be returned:

ThreeDSecure_RequestID - Links the Enrollment process with the

Authentication process.
ThreeDSecure_ACS_URL - Only Present if card is Enrolled.
ThreeDSecure_PAReq - Only Present if card is Enrolled.

If the card is not enrolled, skip the Validate Authentication, and proceed with the authorisation.
The following would also be returned and is required to be submitted through to the gateway only
if the card was not enrolled:

82
 CardHolderAuthenticationID
CardHolderAuthenticationData
ElectronicCommerceIndicator

If the card is enrolled. The merchant’s website will have to be redirected to the Access Control
Server (ACS) URL and the PAReq must be posted to it. an Example of the redirect page will be
provided in Appendix B.

10.2.2 Validate Authentication

For enrolled cards, the next step is to request the validation service to verify the authentication
response message returned by the card-issuing bank. To do so, you would build up a Enquiry
request with the command set as ThreeDSecureValidateAuthentication. The following required
parameters need to be sent:

ApplicationID
CertificateID
Mode
MerchantReference
Amount
Currency
PAN
ExpiryDate
ThreeDSecure_RequestID - Links the Enrollment process with the
Authentication process.
ThreeDSecure_SignedPARes - PARes message extracted from the form.
Appendix B.

If the Validate Authentication was unsuccessful the merchant is not permitted to submit the
transaction for authorisation. Instead ask the customer for another form of payment.

83
If the Validate Authentication was successful, the following parameters will be returned and is
required to be send through to the gateway:

ThreeDSecure_RequestID - Not required to be send to gateway with

transaction.
CardHolderAuthenticationID - Must be send to gateway with transaction.
CardHolderAuthenticationData - Must be send to gateway with
transaction.
ElectronicCommerceIndicator - Must be send to gateway with transaction.

84
11. VISA CHECK-OUT WITH ENTERPRISE

Visa Check-Out is a digital representation of a cardholders Visa Card. Cardholders can register
their debit or credit cards by downloading the Visa Check-Out app. Once cardholders have their
profiles and card details loaded in Visa Check-out, they are able to make purchases at merchants
who are accepting with Visa Check-Out payments.

*The process flow described below only show cases the interaction between cardholder,
enterprise merchant, the gateway and Visa service

11.1 Process Flow in Visa Check-Out with enterprise

1. Cardholder selects Visa Check-Out as payment method
2. Enterprise Merchant calls Visa Light Box or Widget and presents it to the
Cardholder to Login
3. Cardholder Logins via Visa Light Box
4. Cardholder selects a card and presses Continue
5. Upon clicking Continue, Enterprise Merchant sends the Call ID to the iVeri gateway
6. The iVeri gateway uses the Call ID to get the Payload from Visa services
7. Payload is returned by Visa services to the iVeri gateway
8. The iVeri gateway decrypts the Payload and retrieves the PAN
9. The iVeri gateway sends the transaction request to the acquire for processing
10. When a response is received, the iVeri gateway sends the transaction response to
the enterprise merchant
11. Lastly, the enterprise merchant updates Visa services with a failed or successful
transaction response.

85
11.1.1 Illustration of Visa Check Out with Enterprise

86
12. PAYD

PayD transactions allow the customer to make a payment using their debit card + pin, without a
POS device present (i.e. web site purchases), by using their mobile phones.

12.1 PayD Process

1. Customer selects payD as payment method for the transaction. (The payment
selection process is provided by the merchant)
a. Customer enters their mobile number instead of their card details. (Card
details are not present in the V_XML)
b. PanFormat is set to MSISDN and the MSISDN tag set to the customer's
mobile number, this will identify the transaction as a payD transaction.
2. Transaction is sent to the gateway as a normal enterprise transaction.
3. The gateway identifies the transaction as a payD transaction and forwards the
transaction to payD.
4. payD determines the registration status of the user. (see respective sections below
on how the process changes)

12.2 Non-Registered Users

1. payD determines the user has not been registered and the transaction fails.
2. The gateway returns Error Code 23 and Description “Card information not present”
to the merchant.
3. The merchant must then, in addition to the MSISDN, prompt the user for their PAN
(full card number), ExpiryDate and AccountType (savings, cheque, credit)
4. PanFormat is set to MSISDN. (PanFormat must still be set to MSISDN, to identify
transaction as a payD transaction)
5. Transaction is sent to the gateway as a normal enterprise transaction.
6. The gateway identifies the transaction as a payD transaction, and forwards the
transaction to payD

87
 7. payD performs the user registration
8. ...continue as a registered user..

12.3 Registered Users

1. The customer is prompted to enter their PIN using their mobile phone.
2. payD then forwards the transaction (along with card data) to the gateway to be
completed.
3. The gateway will respond to the merchant the transaction status and a new tag
MobileMoneyID

12.4 Voiding payD Transactions

1. The exisiting void mechanism is used to void payD transactions. In addition to the
existing tags used to perform a void, the merchant must also set the
MobileMoneyID tag.

88
13. WEB SERVICE

The iVeri web service will allow cross platform integration with the various systems provided by
iVeri, using a common interface.

13.1 Message Formats used by the Web Service

Communication between the client and web service is via SOAP protocol. The SOAP requests and
responses are shown for each method provided by the web service.
13.1.1Example of SOAP Request
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/">

<SOAP-ENV:Header/>

<SOAP-ENV:Body>

<Execute xmlns="http://iveri.com/">

<validateRequest>true</validateRequest>

<protocol>V_XML</protocol>

<protocolVersion>2.0</protocolVersion>

<request>.........</request>

</Execute>

</SOAP-ENV:Body>

</SOAP-ENV:Envelope>

13.1.2 Example of SOAP Response

<soap:Envelope xmlns="http://schemas.xmlsoap.org/soap/envelope/">

<soap:Body xmlns="http://schemas.xmlsoap.org/soap/envelope/">

<ExecuteResponse>

<ExecuteResult>.......</ExecuteResult>

</ExecuteResponse>

</soap:Body>

</soap:Envelope>

89
13.2 Web Service URL's

iVeri WebService uses the Gateway addresses (see section Error: Reference source not foundError:
Reference source not found) below with the following difference:
[Gateway]/iVeriWebService/Service.asmx
example:
https://portal.nedsecure.co.za/iVeriWebService/Service.asmx

Service Description
Nedbank: https://portal.nedsecure.co.za/iVeriWebService/Service.asmx?wsdl

I&M Bank: https://portal.host.iveri.com/iVeriWebService/Service.asmx?wsdl

CBZ Bank: https://portal.host.iveri.com/iVeriWebService/Service.asmx?wsdl

ECS Bank: https://portal.host.iveri.com/iVeriWebService/Service.asmx?wsdl

CSC & CSC24Seven Bank: https://portal.host.iveri.com/iVeriWebService/Service.asmx?wsdl

CIM : https://portal.host.iveri.com/iVeriWebService/Service.asmx?wsdl

13.3 Web Service implementation

All methods provided by the web service return a V_XML formatted response. The GetPinBlock
method is the only exception. The GetPinBlock method will return a PINBlock data structure.

90
The V_XML request and response format is defined by the V_XML.xsd schema, which can be
downloaded from https://portal.nedsecure.co.za/schemas/v_xml/7.0/v_xml.xsd

Client code must check the respective Result fields to determine if the web service method was
successful or not. (Result fields are defined by the V_XML specification)

In order for a client to call the execute method the client certificate must be provided with the
HTTP Request.

13.4 WebService Methods

13.4.1 String Execute (bool validateRequest, string protocol, string protocolVersion, string request)
Description
Execute the V_XML formatted request. The action to be performed is determined by the
V_XML, as defined by the V_XML specifications.

ie. Transaction (Sale, Refund etc)

Returns
A V_XML formatted string (The return string will need to be URL decoded)
Client Certificate
Is required (provided with HTTP Request)

Parameters
ValidateRequest true:
:boolean Will validate the V_XML request against the schema definition. If there are any schema
errors processing of the request will terminate and the request will not be passed on to the
relevant provider.
or
false:
Will not validate the V_XML request.
The V_XML request along with any schema errors will be passed on to the relevant
provider for processing. If there are schema errors processing will terminate in the
provider.

Set this parameter to true while testing client code and false when in a production
environment.

Protocol Currently supported protocols

: string • V_XML

If validate is set to true, an unsuccessful response will be generated for any

unsupported values.
ProtocolVersion Currently supported protocol version
: string • "7.0" (V_XML)

If validate is set to true, an unsuccessful response will be generated for any

91
 unsupported values.
Request A V_XML format string without any namespace declarations. Providing namespace
: string declarations will result in an unsuccessful call.

The request must also be URL encoded

Additional
Validation Performed The execute method will also return unsuccessful if:

• No client certificate present

• Certificate ID not provided in the V_XML request
• Certificate ID in the Client Certificate does not match the Certificate ID in the
V_XML

Validation of the Client Certificate is always performed.

Note: URL Encode / Decode is not necessary in .NET and PHP

Method formatted as a SOAP Request and Response

13.4.1.1 SOAP Request

POST /iVeriWebService/Service.asmx HTTP/1.1

Host: portal.nedsecure.co.za
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://iveri.com/Execute"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<Execute xmlns="http://iveri.com/">
<validateRequest>boolean</validateRequest>
<protocol>string</protocol>
<protocolVersion>string</protocolVersion>
<request>string</request>
</Execute>
</soap:Body>

92
</soap:Envelope>

13.4.1.2 SOAP Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<ExecuteResponse xmlns="http://iveri.com/">
<ExecuteResult>string</ExecuteResult>
</ExecuteResponse>
</soap:Body>
</soap:Envelope>

93
 13.4.2 PinBlock GetPinBlock (string mode, string pan, string pin)
Description
Generate a PIN Block using the HSM (Hardware Security Module)
Returns
PinBlock data structure containing the following fields:

• ResultStatusCode
• ResultDescription
• DeviceSerialNumber
• DeviceMake
• KeySerialNumber
• PinBlock

ResultStatusCode see Status Codes used by V_XML

ResultDescription see Descriptions used by V_XML
Client Certificate
not required

Parameters
mode "test"
: string
"live"

pan Primary Account Number

: string
pin
: string
Additional
Validation Performed • pan length is not less than 13 chracters and not more than 19 characters
• pan is also validated against the LUHN Formula
• pin length is not less than 4 characters and not more than 14 characters

Method formatted as a SOAP Request and Response

13.4.2.1 SOAP Request

POST /iVeriWebService/Service.asmx HTTP/1.1

Host: portal.nedsecure.co.za
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://iveri.com/GetPinBlock"

94
<?xml version="1.0" encoding="utf-8"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetPinBlock xmlns="http://iveri.com/">
<mode>string</mode>
<pan>string</pan>
<pin>string</pin>
</GetPinBlock>
</soap:Body>
</soap:Envelope>

13.4.2.2 SOAP Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetPinBlockResponse xmlns="http://iveri.com/">
<GetPinBlockResult>
<ResultStatusCode>int</ResultStatusCode>
<ResultDescription>string</ResultDescription>
<DeviceSerialNumber>string</DeviceSerialNumber>
<DeviceMake>string</DeviceMake>
<KeySerialNumber>string</KeySerialNumber>
<PinBlock>string</PinBlock>
</GetPinBlockResult>
</GetPinBlockResponse>
</soap:Body>

95
</soap:Envelope>

13.4.3 String GenerateCertificateID (string billingDetailsID)

Description
Creates a new unique Certificate ID to be used when generating a new certificate signing
request. Certificate status will be created. This method must be used in conjunction with
the SubmitCertificateRequest method to complete request of a new certificate.
Returns
A V_XML formatted string containing the generated certificate ID.
Client Certificate
not required

Parameters
billingDetailsID Billing Group ID
:string

Method formatted as a SOAP Request and Response

15.4.3.1 SOAP Request

POST /iVeriWebService/Service.asmx HTTP/1.1

Host: portal.nedsecure.co.za
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://iveri.com/GenerateCertificateID"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GenerateCertificateID xmlns="http://iveri.com/">
<billingDetailsID>string</billingDetailsID>
</GenerateCertificateID>
</soap:Body>
</soap:Envelope>

96
13.4.3.2 SOAP Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GenerateCertificateIDResponse xmlns="http://iveri.com/">
<GenerateCertificateIDResult>string</GenerateCertificateIDResult>
</GenerateCertificateIDResponse>
</soap:Body>
</soap:Envelope>

97
13.4.4 String SubmitCertificateRequest (string certificateID, string certificateSigningRequest)
Description
Submits a PKCS10 certificate signing request. Certificate status will be pending.
Returns
A V_XML formatted string.
Client Certificate
not required

Parameters
certificateID Certificate ID (GUID) used to generate the certificateSigningRequest
: string

certificateSigningReq Base 64 encoded string containing the new certificate signing request
uest
: string example of a certificate signing request

-----BEGIN NEW CERTIFICATE REQUEST-----

MIIDGjCCAoMCAQAwgbMxCzAJBgNVBAYTAlpBMRAwDgYDVQQIDAdHYXV0ZW5nMR
AwINT8mTAfmAe4FdlY9RUv43F9jBYqsV/B6fQxRiSehqnOeS4pmK5gIXiqmfgA/NmZqRio
hLwr45SNu6NjF6Bx56T9fAw7RKTsN9dYb6vEtOXew2kc
-----END NEW CERTIFICATE REQUEST-----

Method formatted as a SOAP Request and Response

13.4.4.1 SOAP Request

POST /iVeriWebService/Service.asmx HTTP/1.1

Host: portal.nedsecure.co.za
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://iveri.com/SumitCertificateRequest"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<SumitCertificateRequest xmlns="http://iveri.com/">
<certificateID>string</certificateID>

98
 <certificateSigningRequest>string</certificateSigningRequest>
</SumitCertificateRequest>
</soap:Body>
</soap:Envelope>

13.4.4.2 SOAP Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<SumitCertificateRequestResponse xmlns="http://iveri.com/">
<SumitCertificateRequestResult>string</SumitCertificateRequestResult>
</SumitCertificateRequestResponse>
</soap:Body>
</soap:Envelope>

13.4.5 String GetCertificate(string certificateID)

Description
Download a base 64 encoded P7B certificate that has been issued
Returns
A V_XML formatted string (The return string will need to be URL decoded) containing the
Client Certificate
not required

Parameters
certificateID Certificate ID (GUID) used to generate the certificateSigningRequest
:string

Method formatted as a SOAP Request and Response

99
13.4.5.1 SOAP Request

POST /iVeriWebService/Service.asmx HTTP/1.1

Host: portal.nedsecure.co.za
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://iveri.com/GetCertificate"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetCertificate xmlns="http://iveri.com/">
<certificateID>string</certificateID>
</GetCertificate>
</soap:Body>
</soap:Envelope>

13.4.5.2 SOAP Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<GetCertificateResponse xmlns="http://iveri.com/">
<GetCertificateResult>string</GetCertificateResult>
</GetCertificateResponse>
</soap:Body>

100
</soap:Envelope>

15.4.6 String RenewCertificateID (string certificateID)

Description
Will change the certificate status of the certificate mathcing the certificate ID to "created".
This method must be used in conjunction with the SubmitCertificateRequest method to
complete the renewal of the certificate.
Returns
A V_XML formatted string (The return string will need to be URL decoded)
Client Certificate
not required

Parameters
certificateID Certificate ID (GUID) of existing certificate.
:string

Method formatted as a SOAP Request and Response

13.4.6.1 SOAP Request

POST /iVeriWebService/Service.asmx HTTP/1.1

Host: portal.nedsecure.co.za
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://iveri.com/RenewCertificateID"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<RenewCertificateID xmlns="http://iveri.com/">
<billingDetailsID>string</billingDetailsID>
<certificateID>string</certificateID>
</RenewCertificateID>
</soap:Body>
</soap:Envelope>

101
13.4.6.2 SOAP Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<RenewCertificateIDResponse xmlns="http://iveri.com/">
<RenewCertificateIDResult>string</RenewCertificateIDResult>
</RenewCertificateIDResponse>
</soap:Body>
</soap:Envelope>

102
13.4.7 Byte [] DownloadFile(string fileServiceCommand)
Description
Downloads a file.
Returns
A Base64 encoded string which is the contents of the downloaded zipped file.
Client Certificate
Send as parameter

Parameters
See section 22.4

Method formatted as a SOAP Request and Response

13.4.7.1 SOAP Request

POST /iVeriWebService/Service.asmx HTTP/1.1

Host: portal.nedsecure.co.za
Content-Type: text/xml; charset=utf-8
Content-Length: length
SOAPAction: "http://iveri.com/RenewCertificateID"

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DownloadFile xmlns="http://iveri.com/">
<fileServiceCommand>Html encoded string</fileServiceCommand>
</DownloadFile>
</soap:Body>
</soap:Envelope>

where <fileServiceCommand> is the Html encoded value

&lt;File Command=&quot;&quot;>
&lt;Gateway&gt;&lt;/Gateway&gt;
&lt;CertificateID&gt;&lt;/CertificateID&gt;

103
 &lt;UserGroup&gt;&lt;/UserGroup&gt;
&lt;UserName&gt;&lt;/UserName&gt;
&lt;Password&gt;&lt;/Password&gt;
&lt;FileName&gt;&lt;/FileName&gt;
&lt;AcquirerCycle&gt;&lt;/AcquirerCycle&gt;
&lt;StartDateTime&gt;&lt;/StartDateTime&gt;
&lt;EndDateTime&gt;&lt;/EndDateTime&gt;
&lt;Mode&gt;&lt;/Mode&gt;
&lt;Acquirer&gt;&lt;/Acquirer&gt;
&lt;MerchantUsn&gt;&lt;/MerchantUsn&gt;
&lt;Format&gt;&lt;/Format&gt;
&lt;/File&gt;

of

<File Command="">
<Gateway></Gateway>
<CertificateID></CertificateID>
<UserGroup></UserGroup>
<UserName></UserName>
<Password></Password>
<FileName></FileName>
<AcquirerCycle></AcquirerCycle>
<StartDateTime></StartDateTime>
<EndDateTime></EndDateTime>
<Mode>Live</Mode>
<Acquirer></Acquirer>
<MerchantUsn></MerchantUsn>
<Format></Format>
</File>

104
Note that DateTime values must be in the format yyyy-MM-ddTHH:mm:ss (date and time
separated with a T).

13.4.7.2 SOAP Response

HTTP/1.1 200 OK
Content-Type: text/xml; charset=utf-8
Content-Length: length

<?xml version="1.0" encoding="utf-8"?>

<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<DownloadFileResponse xmlns="http://iveri.com/">
<DownloadFileResult>Base64 string</DownloadFileResult>
</DownloadFileResponse>
</soap:Body>
</soap:Envelope>

The DownloadFileResult must be Base64 decoded and then unzipped to obtain the original file
contents.

105
14. POS DEVICE INTERGRATION

The following section covers the details of POS Device integration (particularly PIN based
transactions).
PIN transactions are encrypted either using Triple DES DUKPT or Triple DES Master/Session
encryption architecture.
The combination of Acquirer and type of device used determine the encryption architecture
chosen.

iVeri provides facilities where PIN transactions can be process in either mode Live or Test.
For security reasons, a key cannot be used in both modes Live and Test. Therefore, a device is
either loaded for mode Test or mode Live.

A Device that is to be used for mode Live must be injected with a key within an iVeri Trusted Centre
using the appropriate encryption architecture.
A Device that is to be used for mode Test may be injected by a merchant, or within the Trusted
Centre.
To change a device from mode Test to Live, device has to be reinjected with a key within an iVeri
Trusted Centre.

A merchant wishing to perform a Live Debit with PIN transaction requires an approved device that
has been injected appropriately by the appropriate distributor.

14.1 PINBlock encryption via Triple DES DUKPT

encryption
The DUKPT PINBlock encryption process flow is the following: A Device (with a
DeviceSerialNumber and a DeviceMake) is injected in a Trusted Centre with an Initial PIN
Encryption Key (IPEK) and Initial Key Serial Number (IKSN). Whenever a PIN block is required from
the device, a counter is incremented, which indicates a PIN Encryption key. When performing a

106
Debit with PIN, the PINBlock is sent encrypted using the PIN Encryption key, along with the current
KeySerialNumber (which indicates the device and the current counter value).

14.1.1 Key Injection for DUKPT Mode Test

There is one Test IKSN and IPEK that is public knowledge. When a Device is to be injected with the
Test Device Master Key, it can be done either within the iVeri Test Loading Centre, or by the
merchant. When a device is loaded with a test device master key by the merchant, then the
merchant must contact their iVeri Distributor with the device information: Make, Model and Serial
Number.
The Test values are
IKSN: FFFF0000030000000000
IPEK: 02B50748B58B7C4452E22E39DE560CE2

14.2 PINBlock encryption via Master/Session encryption

Master/Session keys are Double Length and are sent to the iVeri Gateway in Hexadecimal format.

The Master/Session PINBlock encryption process flow is the following: A Device (with a
DeviceSerialNumber and a DeviceMake) is injected in a Trusted Centre with a Device Master Key. A
merchant periodically sends a request for a session key (GetDevicePINKey) which is returned
encrypted under the Device Master Key. When performing a Debit with PIN, the PINBlock is sent
encrypted using the current session key.

14.2.1 Key Injection for Master/Session Mode Test

There is one Test Device Master Key that is public knowledge. When a Device is to be injected with
the Test Device Master Key, it can be done within the iVeri Test Loading Centre, or by the
merchant. When a device is loaded with a test device master key by the merchant, then the
merchant must contact their iVeri Distributor with the device information: Make, Model and Serial
Number.
The Test Device Master Key is: 375DE602546843B68089911652E951CB
(MAC: CA40C1F2)

107
14.2.2 Get Device PIN Key
The command “GetDevicePINKey” (which is only relevant for PINBlock encryption via
Master/Session) has the following mandatory input parameters:
DeviceMake
DeviceSerialNumber

Unlike other commands to the iVeri Gateway, “GetDevicePINKey” does not require the input
parameter ApplicationID.
Using iVeri Enterprise in iVeri Client.net, this can be prepared using the following syntax:
enterprise.prepare("Security", "GetDevicePINKey", new Guid(), mode);
or using java:
enterprise.prepare("Security", "GetDevicePINKey", "", mode);

“GetDevicePINKey” must be called if “Debit with PIN” or “Balance Enquiry” reply with the Result
code: “Device PIN Key expired” [20]. It should be called upon startup and every 24 hours, or 200
transactions thereafter.

“GetDevicePINKey” returns the following output parameters, which can be stored for later usage
with “Debit with PIN” and “Balance Enquiry”:
DevicePINKey
MACDevicePINKey

14.3 Track2 encryption via Master/Session encryption

A POS Device Integration architect has the option sending the Track2 to the iVeri Gateway in an
encrypted format. This optional functionality is there as an extra security measure against
someone sniffing the data between the device and the server communicating with the iVeri
Gateway.

The Master/Session Track2 encryption process flow is the following: A Device (with a
DeviceSerialNumber and a DeviceMake) is injected in a Trusted Centre with a Track2 Master Key.

108
A merchant periodically sends a request for a session key (getTrack2SessionKey) which is
returned encrypted under the Track2 Master Key. When performing a transaction or a balance
enquiry, the Track2 is sent encrypted using the current Track2 session key.

14.3.1 Track2 Key Injection for Master/Session Mode Test

There is one Test Track2 Master Key that is public knowledge. When a Device is to be injected
with the Test Track2 Master Key, it can be done either within the iVeri Test Loading Centre, or by
the merchant.
The Test Track2 Master Key is: BFE60D7685A24C15BC8FFBFE137C8C86
(MAC: 2F3BC80A)

14.4 Track2 encryption via Dukpt encryption

A POS Device Integration architect has the option sending the Track2 to the iVeri Gateway in an
encrypted format. This optional functionality is there as an extra security measure against
someone sniffing the data between the device and the server communicating with the iVeri
Gateway.

The Dukpt Track2 encryption process flow is the following: A Device (with a DeviceSerialNumber
and a DeviceMake) is injected in a Trusted Centre with a Track2 IPEK (initial pin encryption key).
This IPEK is different from the one injected for Dukpt PIN encryption. For this encryption, the
following are mandatory input parameters together with the Track2 tag:
DeviceSerialNumber
DeviceMake
Track2KeySerialNumber

14.4.1 Track2 IPEK Injection for Dukpt Mode Test

BDK: 1534C275CDB5DCE015D952AB208AC1DA (MAC: B3D647B5)
IKSN: FFFF8000030000000000
IPEK: 5EC604C6F4D5EC3223F5B1BCC2AD6DD2

109
14.5 PAN encryption via Dukpt encryption
A POS Device Integration architect has the option sending the PAN to the iVeri Gateway in an
encrypted format. This optional functionality is there as an extra security measure against
someone sniffing the data between the device and the server communicating with the iVeri
Gateway.

The Dukpt PAN encryption process flow is the following: A Device (with a DeviceSerialNumber and
a DeviceMake) is injected in a Trusted Centre with a Track2 IPEK (initial pin encryption key). This
IPEK is different from the one injected for Dukpt PIN encryption. For this encryption, the following
are mandatory input parameters together with the PAN tag:
DeviceSerialNumber
DeviceMake
PANKeySerialNumber

16.6.1 “Debit with PIN” and “Balance Enquiry”

The merchant determines if the card is PIN based typically via a local bin list (section 17.6.4). If it
is PIN based, the merchant reads in the PIN from the PED, and obtains an encrypted PINBlock.

A PIN based request is identified by the existance of a PINBlock tag. The existance of the
PINBlock tag implies Track2, DeviceSerialNumber, DeviceMake and DevicePINKey is mandatory.
AccountType is 'Savings' or 'Cheque' or 'Credit' or 'NotSpecified'.

14.6.1 Debit with PIN

The mandatory Amount tag refers to the total transaction amount. The optional CashAmount tag
is any cash portion of the transaction. Therefore, always Amount >= CashAmount.
Normal Withdrawal: CashAmount = Amount
Normal Sale: CashAmount = 0 (or not specified)
Combined Sale and Withdrawal: 0 < CashAmount < Amount

The only time the balance of a PIN based card can be increased using iVeri is by Voiding a
previous transaction.

110
14.6.2 Balance Enquiry
Obtain the balance of the PIN based account in the currency of the account.

Using iVeri Enterprise, this can be prepared using the following syntax:
enterprise.prepare("Enquiry", "Balance", applicationID, mode);

14.6.3 Test environment for PIN cards

iVeri Test cards are available upon request. The Result Codes responded within the PIN based
issuer simulator for Mode Test are as follows:
Input Result returned
Void of previous transaction Successful [0]
4242424242424242 or 5959595959595959 See below
2121212121212121 randomly: HotCard [3] or Denied [4]
5454545454545454 randomly:
Unable to process the transaction [9] or
Timeout waiting for response [1]
All other card numbers Invalid card number [14]
(eg “1111222233334444”)

“4242424242424242” returns the following:

PIN Amount & CashAmount Result returned
54321 N/A Denied [4] (similar to PIN tries exceeded)
12345 Amount <= CurrentBalance Successful [0]
12345 Amount – CashAmount > CurrentBalance Denied [4] (Insufficient funds)
12345 (Amount > CurrentBalance) and Approved but cash denied Warning [21]
(Amount – CashAmount) <= CurrentBalance (Approve with Partial Authentication)
Other N/A Incorrect PIN [19]

The Current Balance for PAN 4242424242424242 for the current merchant testing is stored in
memory, and is manipulated in the following manner:
Initial amount is: 10,000.00 (max balance)
Reset to max balance upon service restart
Decreased after a successful debit.
Replenished to the max balance if the CurrentBalance goes below 10.00 (min
balance).
If a Void is received, then CurrentBalance is increased. Since a Void could be
received after a replenishment (or service restart), CurrentBalance is forced to be
less than or equal to max balance.

111
14.6.4 Determining if a card is PIN based
A merchant determines the card is PIN based by using a local BIN list in conjunction with the
Track2 information read from a card.
The BINLookup download within the File Transfer mechanism (section 22) may be used to refresh
a local BIN list.

A merchant can determine if the card is PIN based in the following manner:

1. The BINLookup download within the File Transfer mechanism (section 22) is used
to populate a local BIN list. It can be refreshed daily.
2. The Track2 of the card is read within a card reader
3. The PAN is determined from the Track2 (see section 10.3)
4. The PAN is checked against the local BIN list.
5. If the initial digits of the card PAN is found on the BIN list then based on the
IsPINCard attribute:
0 Prompt for PIN
1 Do not prompt for PIN
2 If Position #3 of the Track2 Service Code (see section 10.3.1) is 0 or 6 then Prompt for PIN,
else Do not prompt for PIN
6. If there is no BIN list available (or if the initial digits of the card PAN are not found
on the BIN list), then:
a. If the PAN starts with 50, 56, 57, 58 or 6 then Prompt for PIN
b. Else if Position #3 of the Track2 Service Code (see section 10.3.1) is in
{0,5,6,7} then Prompt for PIN
c. Else do not prompt for PIN.

14.7 EMV Transactions”

The introduction of smart cards based on the EMV standard (EMV: Europay, MasterCard, Visa) is
progressing worldwide. More and more banks rely on secure transactions for payments. With the
migration from magstripe to EMV chip, banks are able to offer their customers the utmost in
security. EMV chip technology prevents unauthorized access to card information and helps fight
fraud.

112
14.8 Coding for EMV data
The following is a code snippet in C#:

EMV Request Tags:

enterprise.setTag("EMV_AuthorisationRequestCryptogram", authorisationRequestCryptogram);
enterprise.setTag("EMV_ApplicationIdentifier", applicationIdentifier);
enterprise.setTag("EMV_ApplicationInterchangeProfile", applicationInterchangeProfile);
enterprise.setTag("EMV_CardSequenceNumber", cardSequenceNumber);
enterprise.setTag("EMV_ApplicationTransactionCounter", applicationTransactionCounter);
enterprise.setTag("EMV_ApplicationVersion", applicationVersion);
enterprise.setTag("EMV_CardHolderVerificationMethodResult",
cardHolderVerificationMethodResult);
enterprise.setTag("EMV_CryptogramInformationData", cryptogramInformationData);
enterprise.setTag("EMV_IssuerApplicationData", issuerApplicationData);
enterprise.setTag("EMV_TerminalCapabilities", terminalCapabilities);
enterprise.setTag("EMV_TerminalType", terminalType);
enterprise.setTag("EMV_TransactionType", transactionType);
enterprise.setTag("EMV_TerminalVerificationResult", terminalVerificationResult);
enterprise.setTag("EMV_UnpredictableNumber", unpredictableNumber);
enterprise.setTag("EMV_TransactionStatusInformation", transactionStatusInformation);

EMV Response Tags:

enterprise.getTag(“EMV_IssuerAuthenticationData”);
enterprise.getTag(“EMV_IssuerScriptTemplate1”);
enterprise.getTag(“EMV_IssuerScriptTemplate2”);
enterprise.getTag(“EMV_ResponseCode”);

113
15. ADDITIONAL DATA TRANSACTIONS

15.1 Additional Data for Procurement Transactions

Procurement transactions refer to transactions that contain the line item (or order basket) details.
If the line item details are sent to iVeri within a transaction, then a procurement card holder get
those details from their issuing bank (for example on their monthly statement). This is of
assistance in tracking business to business transactions particularly in large corporations.

Procurement transactions are currently only available within distributor Nedbank.

15.1.1Coding for Procurement

The following optional input parameters are Procurement specific per transaction:
CustomerReferenceIdentifier
CustomerVATRegistrationNumber
DestinationCountry
DestinationZIPCode
NationalTax
NationalTaxIndicator
OrderDate
PurchaseIdentifier
ShipFromZIPCode
ShippingAmount
ShippingTaxRate
TransactionDiscount
UniqueVATInvoiceReferenceNumber

The following optional input parameters are Procurement specific per Line item:
Discount
ItemCommodityCode

114
 ItemDescriptor
ProductCode
Quantity
TaxRate
Total
UnitCost
UnitOfMeasure

Since Line items are repeated, the advanced Enterprise methods openElement and closeElement
must be used. The following is a code snippet in VB.net:

enterprise.setTag("ShippingTaxRate", shippingTaxRate)
enterprise.setTag("TransactionDiscount", transactionDiscount)
enterprise.setTag("UniqueVATInvoiceReferenceNumber", vatReferenceNo)

Dim dr As DataRow
For Each dr In myTable.Rows
enterprise.openElement("LineItem")
enterprise.setTag("ItemCommodityCode", dr("Item Code"))
enterprise.setTag("ItemDescriptor", dr("Description"))
enterprise.setTag("ProductCode", dr("Product Code"))
enterprise.setTag("Quantity", dr("Quantity"))
enterprise.setTag("UnitOfMeasure", dr("Unit Of Measure"))
enterprise.setTag("UnitCost", dr("Unit Cost"))
enterprise.setTag("TaxRate", dr("Tax Rate"))
enterprise.setTag("Discount", dr("Discount"))
enterprise.setTag("Total", dr("Total"))
enterprise.closeElement()

15.1.2 Tax Calculation

The calculations below show how the NationalTax is calculated. Note that rounding can be up or
down since the resulting NationalTax value is allowed to fall in a precision tolerance interval based
on the number of line items.
Calculation when TransactionDiscount is zero
NationalTax = (sum of (LineItem Total x LineItem TaxRate) / 10000) + (ShippingAmount x
ShippingTaxRate) / 10000

115
15.1.3 Calculation when TransactionDiscount is NOT zero
The TransactionDiscount is spread across some or all of the line items resulting in an additional
discount for these line items.
Let’s call the LineItem Total of the affected line items, reduced LineItem Total. Then,
NationalTax = (sum of (reduced LineItem Total x LineItem TaxRate) / 10000) + (ShippingAmount x
ShippingTaxRate) / 10000.
For the above calculation, a maximum and minimum tax amount is obtained by sorting line items
in ascending and descending order respectively according to LineItem TaxRate.

15.2 Advanced Fraud Screening

The following optional input parameters are CyberSource specific per Line item:
Discount
ItemCommodityCode
ItemDescriptor
ProductCode
Quantity
TaxRate
Total
UnitCost
UnitOfMeasure
PassengerFirstName
PassengerLastName
PassengerID
PassengerStatus
PassangerType
Note: The fields in Blue will be used when doing Advanced Fraud Screening and is not recorded on
the iVeri system.

Since Line items are repeated, the advanced Enterprise methods openElement and closeElement
must be used. The following is a code snippet in VB.net:

116
enterprise.setTag("ShippingTaxRate", shippingTaxRate)
enterprise.setTag("TransactionDiscount", transactionDiscount)
enterprise.setTag("UniqueVATInvoiceReferenceNumber", vatReferenceNo)

Dim dr As DataRow
For Each dr in myTable.Rows
enterprise.openElement("LineItem")
enterprise.setTag("UnitCost", dr("Unit Cost"))
enterprise.setTag("Quantity", dr("Quantity"))
enterprise.setTag("ItemDescriptor", dr("Description"))
enterprise.setTag("ProductCode", dr("Product Code"))
enterprise.setTag("PassengerFirstName", dr("Passenger FirstName"))
enterprise.setTag("PassengerLastName", dr("Passenger LastName"))
enterprise.setTag("PassengerID", dr("Passenger ID"))
enterprise.setTag("PassengerStatus", dr("Passenger Status"))
enterprise.setTag("PassengerType", dr("Passenger Type"))
enterprise.closeElement()
Next

15.3 Fleetcard transactions

Fleet cards facilitate the tracking of costs and managing statistical information of a fleet of
vehicles.
A Fleet transaction refer to special processing for a Fleet card.

Fleet transactions are currently only available within distributor Nedbank.

If a fleet card is received with other distributors, then the fleet specific parameters are ignored.

15.3.1 Coding for Fleetcards

The following optional input parameters are Fleet specific per transaction:
CustomerReferenceIdentifier

The following optional input parameters are Fleet specific per Line item:
ProductCode
Quantity
QuantityDecimalPlaces

117
 UnitCost

The latest available values of the ProductCode field are obtained via the “Inventory” download
command (See section 22). Only use the ProductCodes with Type='Fleet'. The list at the time of
writing is given in 7.4
Since Line items are repeated, the advanced Enterprise methods openElement and closeElement
must be used. The following is a code snippet in C#:

enterprise.setTag("CustomerReferenceIdentifier", customerReferenceIdentifier);

foreach (DataRow dr in myTable.Rows)

{
enterprise.openElement("LineItem");
enterprise.setTag("ProductCode", dr["Product Code"]);
enterprise.setTag("Quantity", dr["Quantity"]);
enterprise.setTag("QuantityDecimalPlaces", dr["QuantityDecimalPlaces"]);
enterprise.setTag("UnitCost", dr["Unit Cost"]);
enterprise.closeElement();
}

15.4 Airline addendum data

Airline addendum data is additional transaction data which appear on a card holder's statement
when buying a ticket from an airline merchant who include this data in a transaction request.

Airline addendum data is currently only available within distributor Nedbank. Merchants who want
to make use of this need to have the NedbankBICISO provider assigned to their Application ID's on
the iVeri Gateway.
In addition, for the NedbankBICISO provider, the airline addendum data is currently only supported
for follow-up debit (pre-authorised debit) transactions.

15.4.1 Coding for Airline addendum data

The following is a code snippet in C#:

enterprise.openElement("AirlineData");

118
enterprise.setTag("PassengerName", passengerName);
enterprise.setTag("PrimaryTicketNumber", primaryTicketNumber);
enterprise.setTag("FirstDepartureLocationCode", firstDepartureLocationCode);
enterprise.setTag("FirstArrivalLocationCode", firstArrivalLocationCode);
enterprise.setTag("PNRNumber", pnrNumber);
enterprise.setTag("OfficeIATANumber", officeIATANumber);
enterprise.setTag("OrderNumber", orderNumber);
enterprise.setTag("PlaceOfIssue", placeOfIssue);
enterprise.setTag("DepartureDate", departureDate);
enterprise.setTag("CompleteRoute", completeRoute);
enterprise.setTag("DepartureTime", departureTime);
enterprise.setTag("JourneyType", journeyType);
enterprise.closeElement();

Note: The fields in Blue will be used when doing Advanced Fraud Screening.
These fields are not recorded on the iVeri system.

15.5 CyberSource Fraud Management

CyberSource data is additional transaction data which iVeri Payment Technologies Ltd needs to
process orders within CyberSource's fraud screening solution.

15.5.1 Device Fingerprinting

In order to successfully implement Device Fingerprinting, a 1-pixel image file (which cannot be
seen) and two scripts need to be placed in the <body> tag of the merchant’s checkout page*. This
will ensure a 3-5 second window in which the code segments can complete the data collection
necessary to create a fingerprint for the device making the order.

Below are the code segments for implementing Device Fingerprinting:

15.5.1.1 PNG Image

<p style="background:url(https://h.online-metrix.net/fp/clear.png?org_id=<org ID>&amp;session_id=<merchant id><session
ID>&amp;m=1)"></p> <img src="https://h.online-metrix.net/fp/clear.png?org_id=<org ID>&amp;session_ id=<merchant id><session
ID>&amp;m=2" alt="">

15.5.1.2 Flash Code

<object type="application/x-shockwave-flash" data="https://h.online-metrix.net/fp/ fp.swf?org_id=<org ID>&amp;session_id=<merchant
id><session ID>" width="1" height="1" id="thm_fp"> <param name="movie" value="https://h.online-metrix.net/fp/fp.swf?org_id=<org
ID>&amp;session_id=<merchant id><session ID>" /> <div></div> </object>

119
15.5.1.3 JavaScript Code
<script src="https://h.online-metrix.net/fp/check.js?org_id=<org ID>&amp;session_ id=<merchant id><session ID>" type="text/javascript">
</script>

Parameter Data Type Description

Org ID AN Will be supplied by iVeri Payment Technologies Ltd to the merchant.
Session ID AN The session ID is a string variable (letters and numbers only) that must be unique for each
merchant ID. Any string that are already generating, such as an order number or Web
session ID. However, do not use the same uppercase and lowercase letters to indicate
different session IDs.
This is the same value that must be send to iVeri in the DeviceFingerprintID field.
Merchant id AN Will be supplied by iVeri Payment Technologies Ltd to the merchant.

15.5.2 Coding for CyberSource data

The following is a code snippet in C#:

enterprise.openElement("CyberSource");
enterprise.setTag("DeliveryMethod", Virtual);
enterprise.setTag("DeviceFingerprintID", sessionId);
enterprise.setTag("BillTo_FirstName", billTo_FirstName);
enterprise.setTag("BillTo_LastName", billTo_LastName);
enterprise.setTag("BillTo_Street", billTo_Street);
enterprise.setTag("BillTo_City", billTo_City);
enterprise.setTag("BillTo_Country", billTo_Country);
enterprise.setTag("BillTo_Email", billTo_Email);
enterprise.setTag("BillTo_IPAddress", billTo_IPAddress);
enterprise.closeElement();

15.6 Authenticated Collections

Authenticted collections are intended to enable a merchant who wants to make regular direct
debits to a customer’s account to authenticate the customer. This has two benefits, the merchant
has proved that the customer has consented to these regular debits and the customer has verfied
themselves by way of a pin validation so there is a higher level of comfort that the customer's
account is a valid account and does belong to the customer.
Authenticated Collections is currently only available from Nedbank. Merchants who want to make
use of this need to have the NedbankPostilion provider assigned to their Application ID's on the
iVeri Gateway.
In addition, for the NedbankPostilion provider, the Authenticated Collections provider parameter
must be enabled otherwise the transaction will be declined.

120
15.6.1 Coding for Authenticated Collection data
The following is a code snippet in C#:
enterprise.openElement("AuthenticatedCollectionData");
enterprise.setTag("AccountNumber", accountNumber);
enterprise.setTag("DebtorIdentification", debtorIdentification);
enterprise.setTag("MaximumCollectionAmount", maximumCollectionAmount);
enterprise.closeElement();

Note that MerchantReference must be set for Authenticated Collections AND the transaction must
be PIN authenticated card present. The MerchantReference is used as the contract reference. An
AuthorisationCode is returned if successful.

121
16. MASTERPASS QUICK RESPONSE CODE

16.1 Create Code

Generate a transactional code that can then be paid for by a cardholder. This code can be
represented as a QR code, transferred using NFC or manually entered into a device. The code can
also be used as part of an In-App payment.
16.1.1 Additional Parameters
Request Parameter Description
MasterPassAction Mandatory, The action to perform.
MasterPassMerchantID Mandatory, The merchant id as captured on MasterPass.
MasterPassShortDescription Mandatory, This will be displayed to the consumer at the time a code is scanned. Length is 5 to 45 characters
MasterPassCodeExpiryDate Optional. If this is empty the code will by default expire in 30 minutes from issue. If this value is 0 the code will
never expire. This time is specified in epoch.
Amount Mandatory, To use a variable amount use 0 as the amount.
Currency Mandatory, The currency is tied to the merchant setup.
MerchantReference Mandatory, Used to link code to transaction.

Response Parameter Description

MasterPassAction The action that was performed
MasterPassCode This is the result code
MasterPassCodeExpiryDate Date until the code is valid. This is in epoch time.

16.1.2 Example:
Request:
<?xml version="1.0" encoding="UTF-8"?><V_XML CertificateID="172bc42c-7ffb-44d0-a1e4-
441444e1274c" Direction="Request" ProductType="Enterprise" ProductVersion="iVeriClient.JAVA
v4.0.2" Version="2.0">
<Enquiry ApplicationID="8b2101c2-88a2-11d4-bccf-0000e884f861"
Command="MasterPassQuickResponseCode" Mode="Test">
<MasterPassMerchantID>280</MasterPassMerchantID>
<MasterPassAction>CreateCode</MasterPassAction>
<Currency>ZAR</Currency>
<MerchantReference>1507023127597</MerchantReference>
<Amount>1075</Amount>
<MasterPassShortDescription>Basket of goods</MasterPassShortDescription>
</Enquiry>
</V_XML>

Response:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<V_XML Direction="Response" Version="2.0">
<Enquiry ApplicationID="{8B2101C2-88A2-11D4-BCCF-0000E884F861}"
Command="MasterPassQuickResponseCode" Mode="Test" RequestID="{04D220A0-A1D4-4ABF-B6FF-

122
8ADF514486F5}">
<Result AppServer="GOLIATH" DBServer="titan" Gateway="DEV2012" Status="0"/>
<MasterPassAction>CreateCode</MasterPassAction>
<MasterPassCodeExpiryDate>1507024950794</MasterPassCodeExpiryDate>
<MasterPassCode>9599003889</MasterPassCode>
</Enquiry>
</V_XML>

16.2 Query Code

Query a code that has been created.
16.2.1 Additional Parameters

Request Parameter Description

MasterPassAction Mandatory, The action to perform.
MasterPassMerchantID Mandatory, The merchant id as captured on MasterPass.
MasterPassCode Mandatory, The result code that must be queried

Response Parameter Description

MasterPassAction The action that was performed
MasterPassShortDescription Short decription linked to the code
MasterPassCodeExpiryDate Date until the code is valid. This is in epoch time.
MasterPassMerchantName The name of the merchant as captured on MasterPass
Amount Amount linked to the code.
Currency The currency is tied to the merchant setup.
MerchantReference Linked to the code.

16. 2.2 Example:

Request:
<?xml version="1.0" encoding="UTF-8"?><V_XML CertificateID="172bc42c-7ffb-44d0-a1e4-
441444e1274c" Direction="Request" ProductType="Enterprise" ProductVersion="iVeriClient.JAVA
v4.0.2" Version="2.0">
<Enquiry ApplicationID="8b2101c2-88a2-11d4-bccf-0000e884f861"
Command="MasterPassQuickResponseCode" Mode="Test">
<MasterPassMerchantID>280</MasterPassMerchantID>
<MasterPassAction>QueryCode</MasterPassAction>
<Currency>ZAR</Currency>
<MerchantReference>1507025114123</MerchantReference>
<MasterPassCode>9599003889</MasterPassCode>
</Enquiry>
</V_XML>

Response:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<V_XML Direction="Response" Version="2.0">
<Enquiry ApplicationID="{8B2101C2-88A2-11D4-BCCF-0000E884F861}"
Command="MasterPassQuickResponseCode" Mode="Test" RequestID="{A0B3A6DA-4BB2-4D3D-BF26-
59C2845622B3}">
<Result AppServer="GOLIATH" DBServer="titan" Gateway="DEV2012" Status="0"/>
<Currency>R</Currency>

123
 <MerchantReference>1507023127597</MerchantReference>
<Amount>1075</Amount>
<MasterPassAction>QueryCode</MasterPassAction>
<MasterPassShortDescription>Basket of goods</MasterPassShortDescription>
<MasterPassCodeExpiryDate>1507024950000</MasterPassCodeExpiryDate>
<MasterPassMerchantName>Web Tickets</MasterPassMerchantName>
</Enquiry>
</V_XML>

16.3 Delete Code

Delete a code that has been created
16.3.1 Additional Parameters
Request Parameter Description
MasterPassAction Mandatory, The action to perform.
MasterPassMerchantID Mandatory, The merchant id as captured on MasterPass.
MasterPassCode Mandatory, The result code that must be deleted

Response Parameter Description

MasterPassAction The action that was performed

16.3.2 Example:
Request:
<?xml version="1.0" encoding="UTF-8"?><V_XML CertificateID="172bc42c-7ffb-44d0-a1e4-
441444e1274c" Direction="Request" ProductType="Enterprise" ProductVersion="iVeriClient.JAVA
v4.0.2" Version="2.0">
<Enquiry ApplicationID="8b2101c2-88a2-11d4-bccf-0000e884f861"
Command="MasterPassQuickResponseCode" Mode="Test">
<MasterPassMerchantID>280</MasterPassMerchantID>
<MasterPassAction>DeleteCode</MasterPassAction>
<Currency>ZAR</Currency>
<MerchantReference>1507026463652</MerchantReference>
<MasterPassCode>9599003889</MasterPassCode>
</Enquiry>
</V_XML>

Response:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<V_XML Direction="Response" Version="2.0">
<Enquiry ApplicationID="{8B2101C2-88A2-11D4-BCCF-0000E884F861}"
Command="MasterPassQuickResponseCode" Mode="Test" RequestID="{4117F60B-F3D4-4650-A2C5-
BC08C542AA5F}">
<Result AppServer="GOLIATH" DBServer="titan" Gateway="DEV2012" Status="0"/>
<MasterPassAction>DeleteCode</MasterPassAction>
</Enquiry>
</V_XML>

124
16.4 Block Code
This is an API call to temporarily block a code. This prevents purchases on the code.
16.4.1 Additional Parameters

Request Parameter Description

MasterPassAction Mandatory, The action to perform.
MasterPassMerchantID Mandatory, The merchant id as captured on MasterPass.
MasterPassCode Mandatory, The result code that must be blocked

Response Parameter Description

MasterPassAction The action that was performed

16.4.2 Example:
Request:
<?xml version="1.0" encoding="UTF-8"?><V_XML CertificateID="172bc42c-7ffb-44d0-a1e4-
441444e1274c" Direction="Request" ProductType="Enterprise" ProductVersion="iVeriClient.JAVA
v4.0.2" Version="2.0">
<Enquiry ApplicationID="8b2101c2-88a2-11d4-bccf-0000e884f861"
Command="MasterPassQuickResponseCode" Mode="Test">
<MasterPassMerchantID>280</MasterPassMerchantID>
<MasterPassAction>BlockCode</MasterPassAction>
<Currency>ZAR</Currency>
<MerchantReference>1507026463652</MerchantReference>
<MasterPassCode>9599003889</MasterPassCode>
</Enquiry>
</V_XML>

Response:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<V_XML Direction="Response" Version="2.0">
<Enquiry ApplicationID="{8B2101C2-88A2-11D4-BCCF-0000E884F861}"
Command="MasterPassQuickResponseCode" Mode="Test" RequestID="{4117F60B-F3D4-4650-A2C5-
BC08C542AA5F}">
<Result AppServer="GOLIATH" DBServer="titan" Gateway="DEV2012" Status="0"/>
<MasterPassAction>BlockCode</MasterPassAction>
</Enquiry>
</V_XML>

125
16.5 Unlock Code
This unblocks a blocked code. This call enables future purchases on that code.
16.5.1 Additional Parameters

Request Parameter Description

MasterPassAction Mandatory, The action to perform.
MasterPassMerchantID Mandatory, The merchant id as captured on MasterPass.
MasterPassCode Mandatory, The result code that must be unblocked

Response Parameter Description

MasterPassAction The action that was performed

16.5.3 Example:
Request:
<?xml version="1.0" encoding="UTF-8"?><V_XML CertificateID="172bc42c-7ffb-44d0-a1e4-
441444e1274c" Direction="Request" ProductType="Enterprise" ProductVersion="iVeriClient.JAVA
v4.0.2" Version="2.0">
<Enquiry ApplicationID="8b2101c2-88a2-11d4-bccf-0000e884f861"
Command="MasterPassQuickResponseCode" Mode="Test">
<MasterPassMerchantID>280</MasterPassMerchantID>
<MasterPassAction>UnblockCode</MasterPassAction>
<Currency>ZAR</Currency>
<MerchantReference>1507026463652</MerchantReference>
<MasterPassCode>9599003889</MasterPassCode>
</Enquiry>
</V_XML>

Response:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<V_XML Direction="Response" Version="2.0">
<Enquiry ApplicationID="{8B2101C2-88A2-11D4-BCCF-0000E884F861}"
Command="MasterPassQuickResponseCode" Mode="Test" RequestID="{4117F60B-F3D4-4650-A2C5-
BC08C542AA5F}">
<Result AppServer="GOLIATH" DBServer="titan" Gateway="DEV2012" Status="0"/>
<MasterPassAction>UnblockCode</MasterPassAction>
</Enquiry>
</V_XML>

126
16.6 Update Code
Query a code that has been created.
16.6.1 Additional Parameters
Request Parameter Description
MasterPassAction Mandatory, the action to perform.
MasterPassMerchantID Mandatory, the merchant id as captured on MasterPass.
MasterPassCode Mandatory, the result code that must be queried
Amount Mandatory, to use a variable amount use 0 as the amount.
Currency Mandatory, the currency is tied to the merchant setup.
MerchantReference Mandatory, used to link code to transaction.
MasterPassShortDescription Mandatory, This will be displayed to the consumer at the time a code is scanned. Length is 5 to 45 characters
MasterPassCodeExpiryDate Optional. If this is empty the code will by default expire in 30 minutes from issue. If this value is 0 the code will
never expire. This time is specified in epoch.

Response Parameter Description

MasterPassAction The action that was performed

16.6.2 Example:
Request:
<?xml version="1.0" encoding="UTF-8"?><V_XML CertificateID="172bc42c-7ffb-44d0-a1e4-
441444e1274c" Direction="Request" ProductType="Enterprise" ProductVersion="iVeriClient.JAVA
v4.0.2" Version="2.0">
<Enquiry ApplicationID="8b2101c2-88a2-11d4-bccf-0000e884f861"
Command="MasterPassQuickResponseCode" Mode="Test">
<MasterPassMerchantID>280</MasterPassMerchantID>
<MasterPassAction>UpdateCode</MasterPassAction>
<Currency>ZAR</Currency>
<MerchantReference>1507027434321</MerchantReference>
<MasterPassCode>9599003889</MasterPassCode>
<Amount>1125</Amount>
<MasterPassShortDescription>Basket of Sweets</MasterPassShortDescription>
</Enquiry>
</V_XML>

Response:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<V_XML Direction="Response" Version="2.0">
<Enquiry ApplicationID="{8B2101C2-88A2-11D4-BCCF-0000E884F861}"
Command="MasterPassQuickResponseCode" Mode="Test" RequestID="{1C2756AC-52B3-4DE8-8142-
66C4783258FA}">
<Result AppServer="GOLIATH" DBServer="titan" Gateway="DEV2012" Status="0"/>
<MasterPassAction>UpdateCode</MasterPassAction>
</Enquiry>
</V_XML>

127
16.7 Update Code Amount
Query a code that has been created.
16.7.1 Additional Parameters

Request Parameter Description

MasterPassAction Mandatory, the action to perform.
MasterPassMerchantID Mandatory, the merchant id as captured on MasterPass.
MasterPassCode Mandatory, the result code that must be queried
Amount Mandatory, To use a variable amount use 0 as the amount.
Currency Mandatory, the currency is tied to the merchant setup.
MasterPassCodeExpiryDate Optional. If this is empty the code will by default expire in 30 minutes from issue. If this value is 0 the code will
never expire. This time is specified in epoch.

Response Parameter Description

MasterPassAction The action that was performed

16.7.2 Example:
Request:
<?xml version="1.0" encoding="UTF-8"?><V_XML CertificateID="172bc42c-7ffb-44d0-a1e4-
441444e1274c" Direction="Request" ProductType="Enterprise" ProductVersion="iVeriClient.JAVA
v4.0.2" Version="2.0">
<Enquiry ApplicationID="8b2101c2-88a2-11d4-bccf-0000e884f861"
Command="MasterPassQuickResponseCode" Mode="Test">
<MasterPassMerchantID>280</MasterPassMerchantID>
<MasterPassAction>UpdateCodeAmount</MasterPassAction>
<Currency>ZAR</Currency>
<MerchantReference>1507028386455</MerchantReference>
<MasterPassCode>9599003889</MasterPassCode>
<Amount>1300</Amount>
</Enquiry>
</V_XML>

Response:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<V_XML Direction="Response" Version="2.0">
<Enquiry ApplicationID="{8B2101C2-88A2-11D4-BCCF-0000E884F861}"
Command="MasterPassQuickResponseCode" Mode="Test" RequestID="{10C424BC-6371-413B-AC27-
94949D4D8A6A}">
<Result AppServer="GOLIATH" DBServer="titan" Gateway="DEV2012" Status="0"/>
<MasterPassAction>UpdateCodeAmount</MasterPassAction>
</Enquiry>
</V_XML>

128
17. FOREIGN EXCHANGE

17.1 Dynamic Currency Conversion (DCC)

A service that enables payment card cardholders to make international card purchases or
transactions in their own currency. The conversion of the purchase price of goods or services from
the merchant’s local currency to the cardholder’s home currency occurs at the point of sale at the
quoted exchange rate from a cited exchange rate source.
17.1.1 DCC Rate Request with Specified BIN and Base Amount
Request:
<?xml version="1.0" encoding="UTF-8"?><V_XML CertificateID="4C9CFBF1-1824-470C-B0A2-
5462F2F8FE29" Direction="Request" ProductType="Enterprise" ProductVersion="iVeriClient.JAVA
v4.0.12" Version="2.0">
<Enquiry ApplicationID="8b2101c3-88a2-11d4-bccf-0000e884f861"
Command="DynamicCurrencyConversion" Mode="Live">
<PAN>424242424</PAN>
<Amount>1000</Amount>
<Currency>GBP</Currency>
</Enquiry>
</V_XML>
Response:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<V_XML Direction="Response" Version="2.0">
<Enquiry ApplicationID="{8B2101C3-88A2-11D4-BCCF-0000E884F861}"
Command="DynamicCurrencyConversion" Mode="Live" RequestID="{F199C7AA-16A3-48A8-92E8-
D9FBDD5819A6}">
<Result AppServer="GOLIATH" Code="0" DBServer="titan" Description="" Gateway="DEV2012"
Status="0"/>
<Currency>GBP</Currency>
<Amount>1000</Amount>
<ForeignExchange>
<ForeignExchangeItem>
<ForeignExchangeID>{8D4CC317-6DA6-4DCE-BB4F-DECA3BE86326} </ForeignExchangeID>
<ForeignExchangeProvider>Fexco</ForeignExchangeProvider>
<BaseCurrency>GBP</BaseCurrency>
<BaseAmount>10.00</BaseAmount>
<ForeignCurrency>HKD</ForeignCurrency>
<ForeignAmount>115.63</ForeignAmount>
<ExchangeRate>11,5629</ExchangeRate>
<ExpiryDateTime>2020-01-22 05:47:58 PM</ExpiryDateTime>
<MarginPercentage>3</MarginPercentage>
<CommissionPercentage>0,000000</CommissionPercentage>
</ForeignExchangeItem>
</ForeignExchange>
</Enquiry>
</V_XML>

129
17.1.2 Multiple Rate Request with Specified Base Amount
Request:
<?xml version="1.0" encoding="UTF-8"?><V_XML CertificateID="4C9CFBF1-1824-470C-B0A2-
5462F2F8FE29" Direction="Request" ProductType="Enterprise" ProductVersion="iVeriClient.JAVA
v4.0.12" Version="2.0">
<Enquiry ApplicationID="8b2101c3-88a2-11d4-bccf-0000e884f861"
Command="DynamicCurrencyConversion" Mode="Live">
<Amount>1000</Amount>
<Currency>GBP</Currency>
</Enquiry>
</V_XML>
Response:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<V_XML Direction="Response" Version="2.0">
<Enquiry ApplicationID="{8B2101C3-88A2-11D4-BCCF-0000E884F861}"
Command="DynamicCurrencyConversion" Mode="Live" RequestID="{03D3D31A-6C7B-4E4F-8818-
8B45D12031D3}">
<Result AppServer="GOLIATH" Code="0" DBServer="titan" Description="" Gateway="DEV2012"
Status="0"/>
<Currency>GBP</Currency>
<Amount>1000</Amount>
<ForeignExchange>
<ForeignExchangeItem>
<ForeignExchangeID>{7E5E0298-3AB5-4836-90AE-DFFC27ABECD7} </ForeignExchangeID>
<ForeignExchangeProvider>Fexco</ForeignExchangeProvider>
<BaseCurrency>GBP</BaseCurrency>
<BaseAmount>10.00</BaseAmount>
<ForeignCurrency>AUD</ForeignCurrency>
<ForeignAmount>20.94</ForeignAmount>
<ExchangeRate>2,0937</ExchangeRate>
<ExpiryDateTime>2020-01-22 05:47:58 PM</ExpiryDateTime>
<MarginPercentage>3</MarginPercentage>
<CommissionPercentage>0,000000</CommissionPercentage>
</ForeignExchangeItem>
<ForeignExchangeItem>
<ForeignExchangeID>{DB5DA813-D15A-4F3B-A916-A3D321582201} </ForeignExchangeID>
<ForeignExchangeProvider>Fexco</ForeignExchangeProvider>
<BaseCurrency>GBP</BaseCurrency>
<BaseAmount>10.00</BaseAmount>
<ForeignCurrency>CAD</ForeignCurrency>
<ForeignAmount>20.79</ForeignAmount>
<ExchangeRate>2,0788</ExchangeRate>
<ExpiryDateTime>2020-01-22 05:47:58 PM</ExpiryDateTime>
<MarginPercentage>3</MarginPercentage>
<CommissionPercentage>0,000000</CommissionPercentage>
</ForeignExchangeItem>
.
.
.
.
.

130
 <ForeignExchangeItem>
<ForeignExchangeID>{FB20C820-D574-4755-9E05-A7CA82645296}</ForeignExchangeID>
<ForeignExchangeProvider>Fexco</ForeignExchangeProvider>
<BaseCurrency>GBP</BaseCurrency>
<BaseAmount>10.00</BaseAmount>
<ForeignCurrency>BRL</ForeignCurrency>
<ForeignAmount>60.50</ForeignAmount>
<ExchangeRate>6,0497</ExchangeRate>
<ExpiryDateTime>2020-01-22 05:47:58 PM</ExpiryDateTime>
<MarginPercentage>3</MarginPercentage>
<CommissionPercentage>0,000000</CommissionPercentage>
</ForeignExchangeItem>
</ForeignExchange>
</Enquiry>
</V_XML>

17.2 Multi-Currency Pricing (MCP)

MCP offers eCommerce merchants the ability to sell their goods or services in currencies other
than their base/local currency. This gives the merchant the ability to transact with new customers
around the world while at the same time they can generate a new revenue stream.

With MCP, the merchant prices goods/services in a currency other than, or in addition to, the
merchant’s local currency.

The cardholder makes a purchase decision based on the price displayed by the merchant. The
transaction is then completed with the price displayed by the merchant and the currency selected
by the cardholder, with no currency conversion performed by the merchant.
Request:
<?xml version="1.0" encoding="UTF-8"?><V_XML CertificateID="4C9CFBF1-1824-470C-B0A2-
5462F2F8FE29" Direction="Request" ProductType="Enterprise" ProductVersion="iVeriClient.JAVA
v4.0.12" Version="2.0">
<Enquiry ApplicationID="8b2101c3-88a2-11d4-bccf-0000e884f861" Command="MultiCurrencyPricing"
Mode="Live"/>
</V_XML>
Response:
<?xml version="1.0" encoding="utf-8" standalone="no"?>
<V_XML Direction="Response" Version="2.0">
<Enquiry ApplicationID="{8B2101C3-88A2-11D4-BCCF-0000E884F861}" Command="MultiCurrencyPricing"
Mode="Live" RequestID="{DC559A80-61E2-4353-9FE6-517CE12AA5E9}">
<Result AppServer="GOLIATH" Code="0" DBServer="titan" Description="" Gateway="DEV2012"
Status="0"/>
<Currency>GBP</Currency>

131
 <ForeignExchange>
<ForeignExchangeItem>
<ForeignExchangeID>{20BC0FED-99BC-4FA7-A021-4DF7D267B50D} </ForeignExchangeID>
<ForeignExchangeProvider>Fexco</ForeignExchangeProvider>
<BaseCurrency>GBP</BaseCurrency>
<ForeignCurrency>AUD</ForeignCurrency>
<ExchangeRate>2,0937</ExchangeRate>
<ExpiryDateTime>2020-01-22 05:47:58 PM</ExpiryDateTime>
<MarginPercentage>3</MarginPercentage>
<CommissionPercentage>0,000000</CommissionPercentage>
</ForeignExchangeItem>
<ForeignExchangeItem>
<ForeignExchangeID>{3F59544D-5E79-461F-996E-B59352267C79} </ForeignExchangeID>
<ForeignExchangeProvider>Fexco</ForeignExchangeProvider>
<BaseCurrency>GBP</BaseCurrency>
<ForeignCurrency>CAD</ForeignCurrency>
<ExchangeRate>2,0788</ExchangeRate>
<ExpiryDateTime>2020-01-22 05:47:58 PM</ExpiryDateTime>
<MarginPercentage>3</MarginPercentage>
<CommissionPercentage>0,000000</CommissionPercentage>
</ForeignExchangeItem>
.
.
.
<ForeignExchangeItem>
<ForeignExchangeID>{4FC256A4-1EAF-45E5-A06A-2B609C9CAB3D}</ForeignExchangeID>
<ForeignExchangeProvider>Fexco</ForeignExchangeProvider>
<BaseCurrency>GBP</BaseCurrency>
<ForeignCurrency>BRL</ForeignCurrency>
<ExchangeRate>6,0497</ExchangeRate>
<ExpiryDateTime>2020-01-22 05:47:58 PM</ExpiryDateTime>
<MarginPercentage>3</MarginPercentage>
<CommissionPercentage>0,000000</CommissionPercentage>
</ForeignExchangeItem>
</ForeignExchange>
</Enquiry>
</V_XML>

132
18. UPOP SECUREPLUS AUTHENTICATION

This card authentication services deter unauthorized card use and enable you you to accept
authenticated UnionPay debit and credit card payments.

Payer Authentication through has been made available by iVeri with the addition of the following
Enquiry commands:
UPOPAuthenticationRequestCreation
UPOPAuthenticationResponseValidation

Note: The Merchant has to be enabled for 3DSecure Checking on the iVeri Gateway.

18.1.1 Request Creation

The goal is to create the Authentication Request message to be posted to the UPOP authentication
server. To do so, you would build up a Enquiry request with the command set as
UPOPAuthenticationRequestCreation. The following required parameters needs to be sent:
ApplicationID
CertificateID
Mode
MerchantReference
Amount
Currency
PAN
UPOP_TransactionTime
UPOP_FrontUrl
UPOP_BackUrl
UPOP_RelatedTransactionType

133
If the Request Creation was unsuccessful the merchant is not permitted to continue with the
transaction. Instead, ask the customer for another form of payment.

If the Request Creation was successful, the following parameters will be returned:

UPOP_RequestID - Links the Creation process with the Validation process.

UPOP_TransactionTime - Must always be present
UPOP_Endpoint - Only Present if Creation process successful.
UPOP_ACPReq - Only Present if Creation process successful.

The merchant’s website will have to be redirected to the Authentication Server UPOP Endpoint and
the ACPReq must be posted to it. an Example of the redirect page will be provided in Appendix D.

18.1.2 Request Validate

The Authentication Response message received from the UPOP authentication server must now
be validated. To do so, you would build up a Enquiry request with the command set as
UPOPAuthenticationResponseValidation. The following required parameters need to be sent:

ApplicationID
CertificateID
Mode
UPOP_RequestID - Links the Creation process with the Validation process.
UPOP_TransactionTime - Must always be present
UPOP_ACPRes - ACPRes message extracted from the form. Appendix D.

If the Request Validation was unsuccessful the merchant is not permitted to submit the
transaction for authorisation. Instead ask the customer for another form of payment.

134
If the Request Validation was successful, the following parameters will be returned and is required
to be send through to the gateway:

UPOP_RequestID - Must be send to gateway with transaction.

UPOP_TransactionTime - Must be send to gateway with transaction.
CardHolderAuthenticationData -Must be send to gateway with transaction.
ElectronicCommerceIndicator - Must be send to gateway with transaction.

135
19. 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
ApplicationID.

19.1 Merchant Reference validity period

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

19.2 Recurring transaction checking

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

19.3 ReconReference extraction

The ReconReference extraction setting is only available for the Nedbank distributor.
A 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.

Examples:
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

136
19.4 Transaction Type repetition within transaction
sequence
Authorisations, 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).

137
20. FILE TRANSFER DEVELOPMENT

The iVeri File Transfer mechanism facilitates the automation of uploading or downloading of files.
There may be files available for upload/download within the iVeri Client File Transfer mechanism
that are not available via the iVeri BackOffice. Similarly, there may be files available for
upload/download within iVeri BackOffice that are not available via the iVeri Client File Transfer
mechanism.

20.1 Overview
The following is available to assist FileTransfer development:
iVeri Client Developers Guide (this document)
The iVeri Client API (which includes the Enterprise class)
• For iVeriClient.net: See Start - Programs - iVeriClient -” iVeri Client API”
• For iVeriClient.java: \jre\lib\iveri\doc\index.htm.
iVeri FileTransfer code samples
Distributor website (see section Error: Reference source not found) for updates to
the documentation mentioned

20.2 FileTransfer class

The FileTransfer class has the following basic flow:
Instantiate FileTransfer class
Set the Gateway and the CertificateID.
These can be set within the FileTransfer constructor, or as separate methods (properties in
iVeriClient.net).
You may choose to override the (properties in iVeriClient.java) CertificatePath,
KeyStoreFile, CertificateFile, KeyStorePassword and CertificatePassword
You may choose to override the (properties in iVeriClient.net) CertificatePath,
CertificateFile, and CertificatePassword
Set the mandatory properties. eg Command, ApplicationID, Mode

If appropriate set various input parameters via setTag

138
submit the request to the iVeri Gateway: via upload or download
check the results returned, particularly ResultStatus and ResultCode
for downloads, use the contents of the newly downloaded file.

20.3 File Transfer Data Types

File Transfer parameters have the following data types
Data Type Description
A Alpha only (A-Za-z)
Guid Globally Unique Identifier: {[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}\}
(eg {8E51611F-E19A-4FF0-B229-6A69F42AAA62})
N Numeric (Positive integer)
String Free format string containing: Alpha, numeric, special and padding (printable ASCII)

The Node Type column corresponds to how the FileTransfer class should be used for the
parameter:

Node Type Set input parameter value

property Use method or property of FileTransfer corresponding to the parameter
tag fileTransfer.setTag(..)

139
20. File Transfer Parameters
FileTransfer Parameters
Parameter Node Data Type Minimu Maximum Description
Type m Length
Length
Gateway property A 10 The name of the gateway connecting to. If not explicitly set, the default gateway is used.
CertificateID property Guid 38 38 The iVeri CertificateID installed on the server communicating with the iVeri Gateway
UserGroup property N 10 The UserGroup used to login to the BackOffice website. Usually the same as the BillingDetailsID
UserName property String 16 A Username created under the specified UserGroup
Password property String 32 The BackOffice password of the specified user
Command property A 50 The command identifying what should be done by the iVeri Gateway
Batch Upload / Download
DiVert Upload / Download
HotCard Download
BINLookup Download
BINManagement Download
BlackCard Download
TransactionHistory Download
Recon Download
AcquirerRecon Download
Inventory Download
ApplicationID property Guid 38 38 Identification of the merchant profile performing the file transfer
Mode property A 4 4 The mode of the corresponding ApplicationID
FileName tag String 0 50 The identifying file name of the original batch / divert file uploaded
FileFormat tag String 0 10 The format of the batch file to download
Fixed default
XML
StartDateTime tag String 0 20 The starting datetime from which reconciliation information are required
YYYY-MM-DD HH:MM: YearMonthDay HourMinuteSecond
SS
EndDateTime tag String 0 20 The ending datetime to which reconciliation information are required
YYYY-MM-DD HH:MM: YearMonthDay HourMinuteSecond
SS
Acquirer tag A 3 32 The acquirer that settled the transactions
Nedcor
NedbankBICISO
IMNarada
DashenACI
ChamsACI
MSCCTranzWare
CTLNigeria
Nips
AcquirerCycle tag N 5 8 The cycle from which reconciliation information are required
MerchantUsn tag N 5 20 Acquirer identification for a merchant account.

140
20.5 File Transfer Command
The Upload Commands are:
Batch
DiVert

The Download Commands are:

Batch
DiVert
HotCard
BINLookup
BINManagement
BlackCard
TransactionHistory (with a date time interval)
Recon (with a cycle interval for an acquirer)
AcquirerRecon (currently only available to Nips merchants)
Inventory (currently only available to Nedbank merchants accepting Fleet cards)

141
20.6 File Transfer Parameters per action
The input parameters that are relevant to each action are shown in the following table using the
following key:
M Mandatory
O Optional
blank not relevant

TransactionHistory Download

Recon Download by Acquirer

BINManagement Download

AcquirerRecon Download
BINLookup Download

BlackCard Download

Inventory Download
HotCard Download

DiVert Download
Batch Download

DiVert Upload
Batch Upload

by Date

Cycle
DiVert UploadGateway O O O O O O O O O O O O
CertificateID M M M M M M M M M M M M
UserGroup M M M M M M M M M M M M
UserName M M M M M M M M M M M M
Password M M M M M M M M M M M M
Command M M M M M M M M M M M M
ApplicationID O M M M O O
Mode O M M M M O
FileName O O O
FileFormat O
StartDateTime M
EndDateTime M
Acquirer M M
AcquirerCycle M
MerchantUsn M

The only output parameters relevant to the File Transfer mechanism are the Result related
parameters (see section 10.1).
The specifications for the content of the files relevant to each of the above commands are
contained, the following documents:
iVeri Download Files XML Specification
iVeri Batch XML Specification
iVeri Batch Fixed Format Specification
iVeri DiVert Specification Guide

142
20.7 Automating the File Transfer process
iVeriClient is released with a command line FileTransfer utility for testing and
automating the FileTransfer process.
This compiled utility can be used without development skills.
To obtain launch the FileTransfer utility:
iVeriClient.NET: run “iVeri.FileTransfer.exe” from the FileTransfer subdirectory of the
installation directory, eg:
C:\Program Files\iVeri\Client\FileTransfer\iVeri.FileTransfer.exe parameters
iVeriClient.Java: type the following:
java FileTransfer parameters

Calling the utility without parameters will display the usage parameters, which is
summarized here:
Usage: FileTransfer [[-u]|[-d]] gateway certificateID
command userGroup userName password
pathFileName [name1 value1][name2 value2]...

The name-value pairs correspond to the relevant parameters for the chosen action as per
section Error: Reference source not found.

Examples:
FileTransfer -u iVeri Client "gateway" {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} Batch
123456 Administrator **** "C:\MyBatch.txt"
FileTransfer -d iVeri Client "gateway" {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} Batch
123456 Administrator **** "C:\MyBatch.txt" FileFormat XML
FileTransfer -u iVeri Client "gateway" {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} DiVert
123456 Administrator **** "C:\MyDiVert.txt"
FileTransfer -d iVeri Client "gateway" {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} DiVert
123456 Administrator **** "C:\MyDiVert.txt"
FileTransfer -d iVeri Client "gateway" {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} HotCard
123456 Administrator **** "C:\HotCard.zip"
FileTransfer -d iVeri Client "gateway" {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} BinLookup
123456 Administrator **** "C:\BinLookup.zip"
FileTransfer -d iVeri Client "gateway" {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
TransactionHistory 123456 Administrator **** "C:\Transactions17to20Jan.xml"

143
StartDateTime "2006-01-17 09:00:00" EndDateTime "2006-01-20 00:20:00" ApplicationID
{xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} Mode Live
FileTransfer -d iVeri Client "gateway" {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} Recon
123456 Administrator **** "C:\Recons14198.xml" Acquirer Nedbank AcquirerCycle 14198
MerchantUsn 2160000000 ApplicationID {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} Mode Live
FileTransfer -d iVeri Client "gateway" {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx}
AcquirerRecon 123456 Administrator **** "Recons14198-1000.zip" Acquirer Nips
FileTransfer -d iVeri Client "gateway" {xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx} Inventory
123456 Administrator **** "C:\Inventory.zip"

Notes:
In the above examples, the valid gateway, certificateID, userGroup, userName, password,
ApplicationID must be inserted as appropriate.
The pathFileName can refer to a zipped or a non-zipped file.

144
21. OUT OF BAND TRANSACTION
NOTIFICATION

Out of Band Transaction notification is a dedicated messaging system that allows merchants to
receive their transaction outcome reliable and timeously. The transaction outcome available in the
Out of Band notification system contains the same data elements as would be found when doing a
transaction look up in the gateway's endpoint or directly from Backoffice. Merchants developers can
interface to the Out of Band system by implementing a Webservice that will consume the
transaction response message. These transaction responses would be available when the
cardholder has completed a payment to the merchant. The transaction responses are V_XML
formatted, parameters returned are defined in 5.5.2 Output Parameters per action. Out of Band
can be used across gateway products.

21.1 Prerequisite
Merchant developer has to implement a Webservice that can consume the
transaction results as and when its available from the Out of Band notification
system.
The merchant developer has to contact their local support team for Out of Band
Transaction notification to be enabled on their Test/Live application ID(s)
A Merchant developer will need to provide the target end of point of the Webservice
implemented.

NOTE:An example of the merchants webservice is available in Appendix C.

145
22. DOMAIN KNOWLEDGE

This purpose of this sections is to give some domain knowledge to people not familiar with the
payment domain.

22.1 Card Present vs. Card Not Present

A Merchant interfaces with a card holder and submits a Card Present Transaction
request whilst the card holder is waiting and the card holder authenticates the
transaction (typically via signature or PIN entry). In the event of a dispute of the
transaction, the merchant must to prove that the card holder authorized it, else
merchant is liable to refund the card holder.
A Merchant submits a Card Not Present Transaction according to previously
arranged agreement with a card holder. The card holder is not present to
authenticate the transaction. In the event of a dispute on the transaction, the
merchant must to prove the card holder authorized it, else the merchant is liable for
refunding the card holder.
Fully 3D Secure transactions are Card not present transactions with the protection
of a Card present transaction.

22.2 Online vs. Offline Transactions

When a Merchant submits an Online Transaction, s/he expects a response while
the card holder is waiting. An Online Transaction can be a Card Present or a Card
Not Present transaction. The result of such a transaction needs to be responded to
as soon as possible.
When a Merchant submits an Offline Transaction (typically with Batch of
Transactions), the merchant requires a response for the transaction within the
immediate future. The time frame of such transactions is they should preferably be
settled before the current cycle cut off. A Batch Transaction can only be a Card Not
Present transaction.

146
 PIN based cards can only be processed within online transactions. (It is possible
for the card holder's chip card to verify the card holder's PIN locally at the card
acceptance device, using the on-board cryptography of the card and the PED).

22.2.1 Online Transactions

In an Online Transaction the transfer of goods and services is ready to take place directly after the
approval. No approval means no transfer of goods and services.

A Merchant interfaces with a card holder and submits an Online Transaction request whilst the
card holder is waiting for the response.
If the transaction request is approved, there is a transfer of goods or services.
If the transaction request is denied, then either the proposed exchange of goods
and services is aborted, a parameter (e.g. amount or expiry date) is changed and
the transaction retried, or a different payment channel is used.
If the transaction experiences an error, then the transaction is retried as long as the
card holder is prepared to wait. Thereafter the transaction details are assessed if
either it should be done offline or the proposed transfer of goods and services be
aborted.

22.2.2 Offline Transactions

PIN based cards can therefore not be included in offline transactions.

An Offline Transaction is submitted when either the transfer of goods and services have already
taken place, or the transfer of goods and services is not a once off transfer that takes place
immediately (e.g. a repetitive / continuous service).

A Merchant submits a set of offline transactions (via iVeri Enterprise or iVeri Batch) according to
previously (implied) arranged agreement with a card holder.

A Merchant interfaces with a card holder. An offline transaction is initiated after one of the
following occurs:

147
 a repetitive transaction (e.g. monthly bill) is agreed to, either in advance or in
arrears
(Store and Forward): the transaction details are below a floor limit, pass hot card
and black card checking, and therefore the merchant decides to take the risk of
transferring the goods and services without guaranteed payment, since either:
• it is outweighed by the cost of going online (time or money is not worth
it), or
• an online transaction was attempted but experienced an error.
there was a problem when the transaction was attempted online.

If the transaction request is:

approved, the merchant gets paid.
denied, then if the transfer of goods and services has occurred, the merchant can
consider contacting the card holder, think about revising their offline business
rules, or contact a debt collector.
in error, then the transaction is retried until it is in a known state.

148
23. FREQUENTLY ASKED QUESTIONS
(COMMON TO .NET AND JAVA)

23.1 Problems connecting to the iVeri Gateway

Ascertain if your computer can communicate directly with the iVeri Gateway, by using telnet.
Confirm the URL of your iVeri Gateway (eg portal.nedsecure.co.za) by consulting section
Error: Reference source not found.

Open a command prompt and type:

telnet portal.nedsecure.co.za 443

If you get an error message, it means that there is a problem with the Internet connection. Please
check your connection or contact your network administrator.
Windows example:
c:\>telnet portal.nedsecure.co.za 443
Connecting To portal.nedsecure.co.za...
Could not open a connection to host on port 443 : Connect failed

Linux example:
#telnet portal.nedsecure.co.za 443
Trying xxx.xxx.xxx.xxx...
telnet: Unable to connect to remote host: Connection refused

Note: If you have a proxy server refer to section 3.6

If you are using windows and get a blank screen, it means that you have successfully connected to
the iVeri Gateway.
Linux will inform you if the connection is successful.

149
23.2 Request timed out when network pinging the
gateway
Using iVeri Client's ClientConfig utility (option 1: Network Ping iVeri Gateway), or via a command
line ping, you may get Request timed out error messages.
Example:
Choice [1]: 1

Network Ping iVeri Gateway

Gateway to network ping [xxxx]:

xxxx Gateway address: gateway.xxx.xxx

Pinging gateway.xxx.xxx [xxx.xxx.xxx.xxx] with 32 bytes of data:

Request timed out.
Request timed out.

This is because ICMP packets have been disabled on the some iVeri Gateways, and therefore
network pings will always timeout.
iVeri Client 2.3.1 and later does not employ network pings.
Check network connectivity by one of the following approaches:
Navigate to the gateway url via a browser (see section Error: Reference source not
found for URL)
Telnet to the gateway (see section Error: Reference source not found)
Use option 5 “Validate certificate”
Use option 6 “ApplicationID Ping iVeri Gateway”

23.3 Execute () or executeAsync() must be called before

this method is allowed
Applicable Version:
Any iVeri Client (.NET or. Java)
Context:
See below

150
Response:
The error "execute () or executeAsync() must be called before this method is allowed" is given
when the following two condition hold:

1. One of the following methods or get properties are called:

methods: isEOF(), getAttribute(), getTag(), getXml()
get properties: ResultStatus, ResultNumber, ResultCode, ResultSource,
ResultDescription
2. Either:
a. execute () or executeAsync() has not been called, or
b. an exception was thrown.

If you think the problem is that one of the above methods / get properties was called before
execute / executeAsync was called, then make sure that you call them only after execute /
executeAsync is called.

If you think the problem is that an exception was thrown, then either:

1. Turn exception throwning off by using

ResultExceptionAction.ResultExceptionThrowingOff, or
2. catch ResultException and query its attributes (instead of the Enterprise class) for
the execution results.

151
24. CONTACT INFORMATION

24.1 Distributors
An iVeri Distributor markets the services of the iVeri Gateway and products within a locality.
South Africa specific: The Nedbank Merchant agreement allows for the acceptance of Visa and
MasterCard credit cards only. A Merchant that wishes to accept Diners Club and American Express
cards, will need to contact these organisations separately and enter into Merchant Agreements
with them. On receipt of Merchant numbers from these organisations, the merchant must contact
Nedbank Card Division and ask them to update their Nedbank Merchant profile to include Diners
and American Express.

24.1.1 Nedbank South Africa

Location South Africa
Telephone 0860 114 966
Web sites http://www.iveri.co.za http://www.nedbank.co.za
Email Technical Assistance [email protected]
Non-technical (i.e. product information etc) [email protected]

24.1.2 Nedbank Namibia

Location Namibia
Web sites http://www.iveri.co.za http://www.nedbank.co.za
Email Technical Assistance [email protected]
Non-technical (product information etc) [email protected]
24.1.3 CBZ Zimbabwe
Location Zimbabwe
Web sites http://www.iveri.com https://www.cbzbank.co.zw/
Email Technical Assistance [email protected]
Non-technical (product information etc) [email protected]

24.1.4 I&M Bank Kenya

Location Kenya
Web sites http://www.iveri.com http://www.imbank.com/
Email Technical Assistance [email protected]
Non-technical (product information etc) [email protected]

24.1.5 CSC/CSC247 Bank

Location Lebanon & Cyprus
Web sites http://www.iveri.com http://www.cscacquiring.com
Email Technical Assistance [email protected]
Non-technical (product information etc) [email protected]

24.1.6 CIM
Location Lebanon & Cyprus
Web sites http://www.iveri.com http://www.cim.mu
Email Technical Assistance [email protected]
Non-technical (product information etc) [email protected]

152
24.2 Websites
An iVeri merchant has access to 3 iVeri websites: Gateway, Certificate and BackOffice.
Website Description
Gateway Used whenever the Client Configuration utility performs gateway task, and whenever the execute method is called in the Enterprise /
FileTransfer class
Certificate Used when necessary by the Client Configuration utility to download the iVeri root certificate, and by Enterprise / FileTransfer class
to perform crl validation
BackOffice Manually navigated to by a merchant (or card holder). Not used by iVeri Client

iVeri Client uses the term “gateway” to refer to the institution that a merchant has an agreement
with.
24.2.1 Nedbank
Website URL Po
rt
Gateway https://portal.nedsecure.co.za 443
Certificate http://ca.iveri.com 80
BackOffice https://backoffice.nedsecure.co.za 443

iVeri Client “gateway” nedbank

Root Certificate http://ca.iveri.com/PRODRootCA.crt

24.2.2 CBZ Bank

Website URL Port
Gateway https://portal.host.iveri.com 443
Certificate http://ca.iveri.com 80
BackOffice https://backoffice.host.iveri.com 443

iVeri Client “gateway” host

Root Certificate http://ca.iveri.com/PRODRootCA.crt

24.2.3 I&M Bank

Website URL Po
rt
Gateway https://portal.host.iveri.com 443
Certificate http://ca.veri.com 80
BackOffice https://backoffice.host.iveri.com 443

iVeri Client “gateway” host

Root Certificate http://ca.iveri.com/PRODRootCA.crt
24.2.4 CSC/CSC247 Bank
Website URL Po
rt
Gateway https:///portal.cscacquiring.com 443
Certificate http://ca.veri.com 80
BackOffice https://backoffice.cscacquiring.com 443

iVeri Client “gateway” host

Root Certificate http://ca.iveri.com/PRODRootCA.crt

153
24.2.5 CIM

Website URL Port

Gateway https://portal.merchant.cim.mu 443
Certificate http://ca.veri.com 80
BackOffice https://Backoffice.merchant.cim.mu 443

24.2.6 DNS configuration

The current IP address of a website can be determined by pinging the DNS domain name.
iVeri reserves the right to change the DNS mapping to IP address at any time, however iVeri would
endeavor to notify merchants timeously of such a change.

154
25. APPENDIX A: V_XML MESSAGE EXAMPLES

The examples provided in this apply when using the web service interface to perform various
transactions.
Because of the large number of elements present in the schema definition, these examples
highlight the element that are most used to perform various transactions. It is important to note
that the elements must appear in the same order they appear in the schema definition.

For a further explanation of each individual elements, see Section 7.

The examples cover the following messages:

1. Comprehensive Request and Response.

a. The Request message shows all of the elements that are most commonly
used. The examples that follow will use the Mandatory elements from
this message necessary to perform the respective transaction covered in
the example.
b. The response message is a typical response received from the web
service to the various request messages.
2. Credit Card Authorisation
3. Credit Card Sale
4. Credit Card Follow-up Sale (converting a previous authorisation into a sale)
5. Debit Card Sale
6. Void by Merchant Reference
7. Void by Trace
8. Void by Follow-up
9. Sale with 3D Secure Elements
10. Request for Debit

155
1. Comprehensive Request and Response

Request Message
<V_XML Version="2.0" CertificateID="A8CBF8DA-92C8-4DF0-93C4-BFA285D66346" Direction="Request">
<Transaction ApplicationID="8B2101C2-88A2-11D4-BCCF-0000E884F861" Command="Debit" Mode="Test">
<CardHolderAuthenticationID />
<CardHolderAuthenticationData />
<CashAmount />
<OriginalMerchantTrace />
<AccountType />
<KeySerialNumber />
<DeviceSerialNumber />
<DeviceMake />
<DeviceCycle />
<MerchantTrace>b5181eb0-b3b6-4811-a960-0000c4a0ae63</MerchantTrace>
<PurchaseDate />
<PurchaseTime />
<PurchaseIdentifier />
<Amount>123</Amount>
<AuthorisationCode />
<BudgetPeriod />
<Currency />
<ElectronicCommerceIndicator />
<ExpiryDate>122012</ExpiryDate>
<MerchantReference>2010-08-18 16:43:40.275</MerchantReference>
<Terminal />
<TransactionIndex />
<OriginalRequestID />
<CardSecurityCode>...</CardSecurityCode>
<PINBlock />
<Track2 />
<PAN>4242........4242</PAN>
</Transaction>
</V_XML>

Response Message
<V_XML Version="2.0" Direction="Response">
<Transaction ApplicationID="{8B2101C2-88A2-11D4-BCCF-0000E884F861}" Command="Debit" Mode="Test" RequestID="{59B08CCE-ACF8-
48C4-9E4C-E3134640DC2D}">
<Result Status="0" AppServer="BOROMIR" DBServer="ARWEN" Gateway="iVeri Client "gateway"" />
<MerchantTrace>b5181eb0-b3b6-4811-a960-0000c4a0ae63</MerchantTrace>
<Amount>123</Amount>
<AuthorisationCode>615232</AuthorisationCode>
<Currency>ZAR</Currency>
<ExpiryDate>122012</ExpiryDate>
<MerchantReference>2010-08-18 16:43:40.275</MerchantReference>
<Terminal>11111111</Terminal>
<TransactionIndex>{0505EC40-65CA-4F81-A806-FA1F2C45BA37} </TransactionIndex>

156
 <MerchantName>iVeri Payment Technology</MerchantName>
<MerchantAddress>Wierda Valley</MerchantAddress>
<MerchantCity>Sandton</MerchantCity>
<MerchantCountryCode>ZA</MerchantCountryCode>
<MerchantCountry>South Africa</MerchantCountry>
<MerchantUSN>0000000000</MerchantUSN>
<Acquirer>Nedcor</Acquirer>
<AcquirerReference>10081:16406407</AcquirerReference>
<AcquirerDate>20100818</AcquirerDate>
<AcquirerTime>164033</AcquirerTime>
<DisplayAmount>R 1.23</DisplayAmount>
<BIN>4</BIN>
<Association>VISA</Association>
<CardType>Unknown CardType</CardType>
<Issuer>Citibank</Issuer>
<Jurisdiction>International</Jurisdiction>
<PANMode>Keyed</PANMode>
<ReconReference>00323841</ReconReference>
<CCNumber>4242........4242</CCNumber>
<PAN>4242........4242</PAN>
</Transaction>
</V_XML>

2. Credit Card Authorisation

Request Message
<V_XML Version="2.0" CertificateID="{1DE2555B-5958-487C-A882-A3A10AE7C22A}" ProductType="Enterprise"
ProductVersion="iVeriWebService" Direction="Request">
<Transaction ApplicationID="{AF8E6E69-ADC5-4D4F-B446-43D2E1E598D3}" Command="Authorisation" Mode="Test/Live">
<CashAmount />
<AccountType />
<Amount>1000</Amount>
<AuthorisationCode />
<BudgetPeriod />
<Currency />
<ExpiryDate>072019</ExpiryDate>
<MerchantReference>348004809</MerchantReference>
<Terminal />
<CardSecurityCode />
<Track2 />
<PAN>4242424242424242</PAN>
</Transaction>
</V_XML>

3. Credit Card Sale

Request Message
<V_XML Version="2.0" CertificateID="{issued certificate id}" Direction="Request">
<Transaction ApplicationID="{associated application id}" Command="Debit" Mode="Test">
<Amount>1000</Amount>

157
 <BudgetPeriod>0</BudgetPeriod>
<ExpiryDate>072019</ExpiryDate>
<MerchantReference>348004809</MerchantReference>
<PAN>4242424242424242</PAN>
</Transaction>
</V_XML>

4. Credit Card Follow-up Sale (converting a previous authorisation into a sale)

Request Message
<V_XML Version="2.0" CertificateID="{issued certificate id}" Direction="Request">
<Transaction ApplicationID="{associated application id}" Command="Debit" Mode="Test">
<Amount></Amount>
<AuthorisationCode></AuthorisationCode>
<MerchantReference></MerchantReference>
<Track2></Track2>
</Transaction>
</V_XML>

5. Debit Card Sale

Request Message
<V_XML Version="2.0" CertificateID="{issued certificate id}" Direction="Request">
<Transaction ApplicationID="{associated application id}" Command="Debit" Mode="Test">
<AccountType>Cheque</AccountType>
<KeySerialNumber></KeySerialNumber>
<DeviceSerialNumber></DeviceSerialNumber>
<DeviceMake></DeviceMake>
<DeviceCycle></DeviceCycle>
<Amount>1000</Amount>
<MerchantReference></MerchantReference>
<PINBlock></PINBlock>
<Track2></Track2>
</Transaction>
</V_XML>

6. Void by Merchant Reference

Request Message
<V_XML Version="2.0" CertificateID="{1DE2555B-5958-487C-A882-A3A10AE7C22A}" ProductType="Enterprise"
ProductVersion="iVeriWebservice" Direction="Request">
<Transaction ApplicationID="{AF8E6E69-ADC5-4D4F-B446-43D2E1E598D3}" Command="Void" Mode="Live">
<MerchantReference>merchRef</MerchantReference>
</Transaction>
</V_XML>

158
 Response Message
<V_XML Version="2.0" Direction="Response">
<Transaction ApplicationID="{AF8E6E69-ADC5-4D4F-B446-43D2E1E598D3}" Command="Void" Mode="Live"
RequestID="{03AACDCD-5EA1-4961-B7C3-14CFC26D2B6F}">
<Result Status="0" AppServer="BOROMIR" DBServer="ARWEN" Gateway="iVeri Client "gateway"" />
<MerchantReference>merchRef</MerchantReference>
</Transaction>
</V_XML>

7. Void by Trace

Request Message
<V_XML Version="2.0" CertificateID="{1DE2555B-5958-487C-A882-A3A10AE7C22A}" ProductType="Enterprise"
ProductVersion="iVeriWebservice" Direction="Request">
<Transaction ApplicationID="{AF8E6E69-ADC5-4D4F-B446-43D2E1E598D3}" Command="Void" Mode="Live">
<OriginalMerchantTrace>b5181eb0-b3b6-4811-a960-0000c4a0ae63</OriginalMerchantTrace>
</Transaction>
</V_XML>

Response Message
<V_XML Version="2.0" Direction="Response">
<Transaction ApplicationID="{AF8E6E69-ADC5-4D4F-B446-43D2E1E598D3}" Command="Void" Mode="Live"
RequestID="{03AACDCD-5EA1-4961-B7C3-14CFC26D2B6F}">
<Result Status="0" AppServer="BOROMIR" DBServer="ARWEN" Gateway="iVeri Client "gateway"" />
<OriginalMerchantTrace>b5181eb0-b3b6-4811-a960-0000c4a0ae63</OriginalMerchantTrace>
</Transaction>
</V_XML>

8. Void by Follow-up

Request Message
<V_XML Version="2.0" CertificateID="{1DE2555B-5958-487C-A882-A3A10AE7C22A}" ProductType="Enterprise"
ProductVersion="iVeriWebservice" Direction="Request">
<Transaction ApplicationID="{AF8E6E69-ADC5-4D4F-B446-43D2E1E598D3}" Command="Void" Mode="Live">
<OriginalRequestID>{BDB162C6-D1CE-494E-BD66-ED40DF2B2B70} </OriginalRequestID>
</Transaction>
</V_XML>

Response Message
<V_XML Version="2.0" Direction="Response">
<Transaction ApplicationID="{AF8E6E69-ADC5-4D4F-B446-43D2E1E598D3}" Command="Void" Mode="Live"
RequestID="{03AACDCD-5EA1-4961-B7C3-14CFC26D2B6F}">
<Result Status="0" AppServer="BOROMIR" DBServer="ARWEN" Gateway="iVeri Client "gateway"" />
<OriginalRequestID>{BDB162C6-D1CE-494E-BD66-ED40DF2B2B70} </OriginalRequestID>
</Transaction>
</V_XML>

159
 9. Sale with 3D Secure Elements

Request Message
<V_XML Version="2.0" CertificateID="{}" Direction="Request">
<Transaction ApplicationID="" Command="Void" Mode="Test">
<CardHolderAuthenitcationID></CardHolderAuthenitcationID>
<CardHolderAuthenticationData></CardHolderAuthenticationData>
<Amount></Amount>
<ElectroniceCommerceIndicator></ElectroniceCommerceIndicator>
<MerchantReference></MerchantReference>
<PAN></PAN>
</Transaction>
</V_XML>

10. Request for Debit

Request Message
<V_XML CertificateID="172bc42c-7ffb-44d0-a1e4-441444e1274c" Direction="Request" ProductType="Enterprise"
ProductVersion="iVeriClient.JAVA v4.0.2" Version="2.0">
<Enquiry ApplicationID="1e983347-de24-406f-9a63-db63bc922f54" Command="RequestForDebit" Mode="Test">
<CardHolderName>John</CardHolderName>
<CardholderEmail>[email protected]</CardholderEmail>
<Amount>2000</Amount>
<Currency>ZAR</Currency>
<MerchantReference>1477917063526</MerchantReference>
<OrderDescription/>
<RequestExpiryDate>20161209</RequestExpiryDate>
<CreateTransactionUrl>False</CreateTransactionUrl>
</Enquiry>
</V_XML>

Response Message
<V_XML Direction="Response" Version="2.0">
<Enquiry ApplicationID="{1E983347-DE24-406F-9A63-DB63BC922F54}" Command="RequestForDebit" Mode="Test"
RequestID="{1D0AA3F7-F355-486C-B11B-367A6D070E8E}">
<Result Status="0" AppServer="BOROMIR" DBServer="ARWEN" Gateway="iVeri Client "gateway"" />
<MerchantReference>1477917063526</MerchantReference>
</Enquiry>
</V_XML>

160
26. APPENDIX B: ACS REDIRECT EXAMPLE
PAGE

26.1 Authenticating Enrolled Cards

You need to redirect the customer to the URL of the ACS with an HTTP form POST that contains
the PAReq, TermURL, and MD. To do so, create a Web page with hidden content:

TermUrl Termination URL on your Web site where the card-issuing bank posts the

payer authentication response (PARes) message.

MD Merchant data that you can use to match the response to the customer’s

order. Although iVeri recommend that you use the RequestID, you can

also use an order number. This field is required, but including a value is

optional. The value, which has no meaning for the bank, is returned to you

as is.

26.2 POST Form

This code has two functions: a page that receives the reply fields for the enrollment check service
and a form containing the required data for the card-issuing bank. The page typically includes
JavaScript (an onLoad script) that automatically posts the form. In your implementation, you
would replace the variables and values by your own values.

<body onload="document.PAEnrollForm.submit ();">

<form id="PAEnrollForm" action="acsURL value" method="post” target="paInlineFrame">
<input type="hidden" name="PaReq" value="ThreeDSecure_PAReq value" />
<input type="hidden" name="TermUrl" value="http://myPAValidationPage.ext" />
<input type="hidden" name="MD" value="<ThreeDSecure_RequestID value>" />
</form>
</body>

26.3 Authentication Frame

When redirected to the ACS URL, the customer’s browser displays the frame that contains the
card-issuing bank’s password authentication dialog or the option to sign up for the program. On
the page that contains the inline frame for the ACS URL, add an HTML frame large enough to
accommodate either form or text to inform your customers of the

161
process:
HTML code: – Card issuer's authentication form: display an inline frame in a
browser page that does not contain other content, such as promotional
information. The frame must be large enough to show the entire 400 x 400 pixels
without scrolling. You are not allowed to use a pop-up window.

<h2>Payer Authentication Inline Window</h2>

<iframe name="paInlineFrame" height="400px" width="400px">
</iframe>

Outside the frame, you must provide a brief message, for example:
Please wait while we process your request. Do not click the Back button or refresh the
page. Otherwise this transaction may be interrupted.

Activation form: complete Web page. Ensure that your customers can see the entire form or can
scroll if necessary.

162
Example Text:
To increase the security of your online purchase, <business name> has partnered with
<Visa, MasterCard>.
If you have signed up for Verified by <Visa, MasterCard>, please complete your bank's
form to authenticate your card. The process takes about 15 seconds. If you do not
currently participate in this authentication program, you can sign up now by completing
your card issuer's form. If your issuing bank does not require this service, you can
cancel or bypass the service. While testing your integration, verify that the frames are
large enough.

26.4 PARes Message

The card-issuing bank sends to your TermURL (http://myPAValidationPage.ext in this example) a
POST that contains the results of the authentication in a PARes message.

variable paRes = <signedPARes replied field>

The base 64 string contains this information:

PaRes Digitally signed PARes message that contains the authentication result. Note

that the field name has a lowercase a (PaRes), but the message name has an uppercase A (PARes).

MD Value included only if you provided one in the outgoing page.

163
After authentication is completed, the customer is redirected to your TermURL.

26.5 Response Messages

You need to ensure that the response messages shown to your customers are accurate and
complete and that they encompass all possible scenarios for enrolled cards and for cards that are
not enrolled. For example, when authentication fails, display a message such as this:

Authentication Failed
Because your card issuer cannot authenticate this card, please select
another card or form of payment to complete your purchase.

164
27. APPENDIX C: OUT OF BAND - MERCHANT
WEBSERVICE

Below is a Webservice example which the merchant can implement in order to consume the transaction responses as
and when they are available from the Out of Band notification system.

namespace Sample Response

public class Response: IResponse

public string TransactionResponse(Response_message message)

string decoded_response = null;

string response_message = null;

string response = message.message;

//Deserialize the message and get the response

dynamic dynJson = JsonConvert.DeserializeObject(response);

string deserialized_response = dynJson.Response;

//Decode the response from base64

byte [] response_data = System.Convert.FromBase64String(deserialized_response);

decoded_response = System.Text.ASCIIEncoding.ASCII.GetString(response_data);

response_message = decoded_response;

Log.WriteLog(response_message);

return response_message;

165
28. APPENDIX D: UPOP AUTHENTICATION
REDIRECT EXAMPLE PAGE

28.1 Authenticating UnionPay Cards

You need to redirect the customer to the UPOP Endpoint an HTTP form POST that contains the
ACPReq. To do so, create a Web page with hidden content:

28.2 POST Form

This code has two functions: a page that receives the reply fields for the enrollment check service
and a form containing the required data for the card-issuing bank. The page typically includes
JavaScript (an onLoad script) that automatically posts the form. In your implementation, you
would replace the variables and values by your own values.

<body onload="document.PAEnrollForm.submit ();">

<form id="PAEnrollForm" action="UPOP_Endpoint value" method="post”
target="paInlineFrame">
<input type="hidden" name="ACPReq" value="UPOP_ACPReq value" />
</form>
</body>

28.3 Use of Authentication Page

Merchant or its payment gateway can show this webpage as a framed inline, pop-up window or a
browser redirection to UPOP’s authentication webpage. The authentication page is 500×600px.
To
implement a framed inline page, the frame opened for the Authentication window must be large
enough to present the entire 500 pixel width by 600 pixel length authentication page, without
scrolling.

<h2>Payer Authentication Inline Window</h2>

<iframe name="paInlineFrame" height="600px" width="500px">
</iframe>

166
28.3.1 Timing between Authentication and Authorization
Upon receipt of the authentication response, less than 3 minutes. Otherwise, the authorization
may fail.

28.3.2 Failed Authentication Processing

Merchant could terminate transaction or submit ElectronicCommerceIndicator value 10 for
authorization request for failed authentication request.
28.3.3 Data Required in Authentication Messages
Merchant must accurately populate the data in authentication request message. Certain
authorization request field values must exactly match corresponding values in the original
authentication request message.

28.4 Full Transaction Flow

This section describes the transaction flow of messages between UPI systems and external
systems.

Steps 1 and 2 involve the Cardholder placing an order with the Merchant and the Merchant making an authorization request.
Steps 3 – 6 involve UPOP authenticating the Cardholder.

167
 *Note: For credit card, you can skip Steps 2 – 3 and collect card CVN2 and Expiration date to initial authorization request
directly3.

Step 1–The Cardholder submits an order

The Cardholder submits an online order to the Merchant and chooses the UnionPay online payment (UPOP) method. After
the Cardholder enters the card number4, the Merchant server or gateway determines whether or not it is UnionPay card.

Figure 2.2-2 Example dialog where Cardholder chooses a UnionPay card to pay online.

Step 2–The Merchant server sends an authentication request

The Merchant server sends an authentication request to the UPOP server via the Cardholder’s device (PC, tablet,
or smart phone), using the URL provided by UPI. For more information, see 3. Authentication Messages

Step 3–The Cardholder’s device displays an authentication webpage

The Cardholder’s device displays a webpage that contains purchase details and prompts the cardholder to enter
their SMS verification code and card information as necessary. This webpage may be on a framed inline, a pop-
up window or a browser redirection to UPOP’s authentication webpage.

168
Figure 2.2-3 UPOP Authentication Page where Cardholder chooses a UnionPay card to pay

Figure 2.2-4 UPOP Authentication Page where Cardholder chooses a UnionPay debit card to pay

Step 4–The Cardholder enters the SMS verification code

The Cardholder receives a verification code by SMS. The Cardholder enters their SMS verification
code and additional credit card information as necessary and then clicks the Submit button.

Step 5–The UPOP server builds and forwards the authentication request

169
The UPOP server builds an authentication request with the entered information and forwards the
request to the Issuer server.

Step 6–The Issuer server responds and the UPOP server builds an authentication response

The Issuer server responds by sending the authentication result to the UPOP server, which
displays the authentication result to the Cardholder. If successfully authenticated, the UPOP server
builds an authentication response.

Step 7–The Merchant server receives and processes the authentication response

UPOP sends to the merchant server both a back-end notification via system interaction and a
front-end notification via the cardholders device. a POST that contains the results of the
authentication in a ACPRes message.

variable acpRes = <signedACPRes replied field>

The base 64 string contains this information:

ACPRes Digitally signed ACPRes message that contains the authentication result.

Step 8–The Merchant server sends the received Authentication Response message to iVeri
The merchant sends the ACPRes back to iVeri in the field:
UPOP_ACPRes
UPOP_RequestID
UPOP_TransactionTime

170