Introduction


Introduction

 
The iVeri range of payment solutions, developed by iVeri Payment Technologies (Pty) Ltd (www.iveri.com) provides proven credit card payment solutions for businesses that have online or physical presence. The use of Enterprise API's is ideal for merchants that want complete control & flexibility of the payment page and transaction mechanisms supported.
Enterprise API’s currently support the following Webservices.


Query Code


Query Code

 Function: Query a code that has been created. 

Query Code 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. 


Query Code – REST Sample

 

Request 

Response 

{ 

    "Version": "2.0", 

    "CertificateID": "{xxxxxxxx-71dd-4044-802d-xxxxxxxxxxxx}", 

    "ProductType": "Enterprise", 

    "Direction": "Request", 

    "Enquiry": { 

      "ApplicationID": "{xxxxxxxx-68e0-42eb-aba9-xxxxxxxxxxxx}", 

      "Mode": "Live", 

      "command":"MasterPassQuickResponseCode", 

      "MasterPassMerchantID": "xxxxx", 

      "MasterPassAction": "QueryCode", 

      "MerchantReference": "Ref_001", 

      "MasterPassCode":"xxx2720xxx" 

   } 

} 

 

{ 

    "Version": "2.0", 

    "Direction": "Response", 

    "Enquiry": { 

        "Currency": "R", 

        "MerchantReference": "Ref_001", 

        "Amount": "1075", 

        "MasterPassAction": "QueryCode", 

        "MasterPassShortDescription": "Basket of goods", 

        "MasterPassCodeExpiryDate": "1645187074000", 

        "MasterPassMerchantName": "Retail Merchant 001", 

        "ApplicationID": "{xxxxxxxx-68E0-42EB-ABA9-xxxxxxxxxxxx}", 

        "Command": "MasterPassQuickResponseCode", 

        "Mode": "Live", 

        "RequestID": "{xxxxxxxx-2207-4C11-A89C-xxxxxxxxxxxx}", 

        "Result": { 

            "Status": "0", 

            "Code": "0", 

            "Description": "", 

            "AppServer": "QAGW2012APP1", 

            "DBServer": "QAGW2012DB2", 

            "Gateway": "QA" 

        } 

    } 

} 

 


Query Code –SOAP Sample

Request  

Response 

<soap:Envelopexmlns: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> 

  <Executexmlns="http://iveri.com/"> 

  <validateRequest>false</validateRequest> 

  <protocol>V_XML</protocol> 

  <protocolVersion>7.0</protocolVersion> 

  <request>&lt;V_XML Version="2.0" CertificateID="xxxxxxxx-71dd-4044-802d-xxxxxxxxxxxx" ProductType="Enterprise" 

ProductVersion="iVeriWebService" Direction="Request"&gt; 

&lt;Enquiry ApplicationID="xxxxxxxx-68e0-42eb-aba9-xxxxxxxxxxxx" Command="MasterPassQuickResponseCode" Mode="LIVE"&gt; 

&lt;MerchantReference&gt;Ref_002&lt;/MerchantReference&gt; 

&lt;MasterPassMerchantID&gt;xxxxx&lt;/MasterPassMerchantID&gt; 

&lt;MasterPassAction&gt;QueryCode&lt;/MasterPassAction&gt; 

&lt;MasterPassCode&gt;xxx5104xxx&lt;/MasterPassCode&gt; 

&lt;/Enquiry&gt; 

&lt;/V_XML&gt; 

</request> 

  </Execute> 

  </soap:Body> 

  </soap:Envelope> 

 

<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body><ExecuteResponse xmlns="http://iveri.com/"><ExecuteResult>&lt;V_XML Version="2.0" Direction="Response"&gt; &lt;Enquiry ApplicationID="{xxxxxxxx-68E0-42EB-ABA9-xxxxxxxxxxxx}" Command="MasterPassQuickResponseCode" Mode="Live" RequestID="{xxxxxxxx-55EC-4835-9817-xxxxxxxxxxxx}"&gt; &lt;Result Status="0" Code="0" Description="" AppServer="QAGW2012APP1" DBServer="QAGW2012DB2" Gateway="QA" /&gt; &lt;Currency&gt;R&lt;/Currency&gt; &lt;MerchantReference&gt;Ref_002&lt;/MerchantReference&gt; &lt;Amount&gt;1075&lt;/Amount&gt; &lt;MasterPassAction&gt;QueryCode&lt;/MasterPassAction&gt; &lt;MasterPassShortDescription&gt;TestProduct&lt;/MasterPassShortDescription&gt; &lt;MasterPassCodeExpiryDate&gt;1647898033000&lt;/MasterPassCodeExpiryDate&gt; &lt;MasterPassMerchantName&gt;Sample Merchant Enterprise Enterprise&lt;/MasterPassMerchantName&gt; &lt;/Enquiry&gt; 

&lt;/V_XML&gt;</ExecuteResult></ExecuteResponse></soap:Body></soap:Envelope 





Delete Code


Delete Code

 Function: Delete a code that has been created 

Delete Code 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 

Delete Code – REST Sample

 

Request 

Response 

{ 

    "Version": "2.0", 

    "CertificateID": "{xxxxxxxx-71dd-4044-802d-xxxxxxxxxxxx}", 

    "ProductType": "Enterprise", 

    "Direction": "Request", 

    "Enquiry": { 

      "ApplicationID": "{xxxxxxxx-68e0-42eb-aba9-xxxxxxxxxxxx}", 

      "Mode": "Live", 

      "command":"MasterPassQuickResponseCode", 

      "MasterPassMerchantID": "xxxxx", 

      "MasterPassAction": "DeleteCode", 

      "MerchantReference": "Ref_001", 

      "MasterPassCode":"0790455080" 

   } 

} 

 

{ 

    "Version": "2.0", 

    "Direction": "Response", 

    "Enquiry": { 

        "MasterPassAction": "DeleteCode", 

        "ApplicationID": "{xxxxxxxx-68E0-42EB-ABA9-xxxxxxxxxxxx}", 

        "Command": "MasterPassQuickResponseCode", 

        "Mode": "Live", 

        "RequestID": "{xxxxxxxx-1DC1-4D06-A632-xxxxxxxxxxxx}", 

        "Result": { 

            "Status": "0", 

            "Code": "0", 

            "Description": "", 

            "AppServer": "QAGW2012APP1", 

            "DBServer": "QAGW2012DB2", 

            "Gateway": "QA" 

        } 

    } 

} 

 


Delete Code – SOAP  Sample

 

Request 

Response 

<soap:Envelopexmlns: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> 

  <Executexmlns="http://iveri.com/"> 

  <validateRequest>false</validateRequest> 

  <protocol>V_XML</protocol> 

  <protocolVersion>7.0</protocolVersion> 

  <request>&lt;V_XML Version="2.0" CertificateID="xxxxxxxx-71dd-4044-802d-xxxxxxxxxxxx" ProductType="Enterprise" 

ProductVersion="iVeriWebService" Direction="Request"&gt; 

&lt;Enquiry ApplicationID="xxxxxxxx-68e0-42eb-aba9-xxxxxxxxxxxx" Command="DeleteCode" Mode="LIVE"&gt; 

&lt;MerchantReference&gt;Ref_002&lt;/MerchantReference&gt; 

&lt;MasterPassMerchantID&gt;xxxxx&lt;/MasterPassMerchantID&gt; 

&lt;MasterPassAction&gt;DeleteCode&lt;/MasterPassAction&gt; 

&lt;MasterPassCode&gt;xxx5104xxx&lt;/MasterPassCode&gt; 

&lt;/Enquiry&gt; 

&lt;/V_XML&gt; 

</request> 

  </Execute> 

 

<?xml version="1.0" encoding="utf-8"?><soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema"><soap:Body><ExecuteResponse xmlns="http://iveri.com/"><ExecuteResult>&lt;V_XML Version="2.0" Direction="Response"&gt; &lt;Enquiry ApplicationID="{xxxxxxxx-68E0-42EB-ABA9-xxxxxxxxxxxx}" Command="DeletCode Mode="Live" RequestID="{xxxxxxxx-304D-4EB0-882D-xxxxxxxxxxxx}"&gt; &lt;Result Status="0" Code="0" Description="" AppServer="QAGW2012APP1" DBServer="QAGW2012DB2" Gateway="QA" /&gt; &lt;MasterPassAction&gt;DeleteCode&lt;/MasterPassAction&gt; &lt;/Enquiry&gt; &lt;/V_XML&gt;</ExecuteResult></ExecuteResponse></soap:Body></soap:Envelope> 



Foreign Exchange


Foreign Exchange

 
Dynamic Currency Conversion (DCC)
DCC is 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.

DCC Transaction Flow

  • Perform an enquiry DCC rate request using a PAN and Amount to the iVeri Gateway 
  • Merchant presents the returned DCC rate offer to the customer
  • Perform a transaction using the customers elected currency 


Sample – DCC/MCP Request with Specified PAN and Base Amount


Sample – DCC/MCP Request with Specified PAN and Base Amount

 

REST

SOAP

Request

{

    "Version""2.0",

    "CertificateID""{4c96973f-71dd-4044-802d-6e234effe8f2}",

    "ProductType""Enterprise",

    "ProductVersion""WebAPI",

    "Direction""Request",

    "Enquiry": {

        "ApplicationID""{56cdf444-b238-4609-9137-148a34b08f59}",

        "Command""DynamicCurrencyConversion",

        "Mode""LIVE",

        "MerchantReference""Farm_1709",

        "MerchantTrace""20220520_1706",

        "Currency""ZAR",

        "Amount""5000",

        "ExpiryDate""1225",

        "CardSecurityCode""001",

        "PAN""5185520050000010"

    }

}

 

<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>false</validateRequest>

  <protocol>V_XML</protocol>

  <protocolVersion>7.0</protocolVersion>

  <request>

    &lt;V_XML Version="2.0" CertificateID="{4c96973f-71dd-4044-802d-6e234effe8f2}" 

    ProductType="Enterprise" ProductVersion="iVeriWebService" Direction="Request"&gt;

    &lt;Enquiry ApplicationID="{56cdf444-b238-4609-9137-148a34b08f59}" Command="DynamicCurrencyConversion" Mode="Live"&gt;

    &lt;MerchantTrace&gt;240X568VFEEE&lt;/MerchantTrace&gt;

    &lt;Amount&gt;2000&lt;/Amount&gt;

    &lt;Currency&gt;ZAR&lt;/Currency&gt;

    &lt;ExpiryDate&gt;1225&lt;/ExpiryDate&gt;

    &lt;MerchantReference&gt;20220104.1525&lt;/MerchantReference&gt;

    &lt;CardSecurityCode&gt;001&lt;/CardSecurityCode&gt;

    &lt;PAN&gt;5185520050000010&lt;/PAN&gt;

    &lt;/Enquiry&gt;&lt;/V_XML&gt;

</request>

  </Execute>

  </soap:Body>

  </soap:Envelope>

 

Response

{

    "Version""2.0",

    "Direction""Response",

    "Enquiry": {

        "MerchantName""Busiswa",

        "MerchantUSN""1732460",

        "Acquirer""NBPostilionNBSouthAfrica",

        "AcquirerReference""02848:09021748",

        "AcquirerDate""20221230",

        "AcquirerTime""151154",

        "Currency""ZAR",

        "Amount""5000",

        "MerchantAddress""MERCHANT ADDRESS",

        "MerchantCity""Sandton",

        "MerchantCountryCode""ZA",

        "MerchantCountry""South Africa",

        "DistributorName""Nedbank",

        "ForeignExchange": {

            "ForeignExchangeItem": [

                {

                    "Version""1.0",

                    "ForeignExchangeID""{3056511A-360E-4C57-8437-4BEBE5CF0CD4}",

                    "ForeignExchangeProvider""Fexco",

                    "BaseCurrency""ZAR",

                    "BaseAmount""50.00",

                    "ForeignCurrency""KES",

                    "ForeignAmount""405.29",

                    "ExchangeRate""8.1058",

                    "ExpiryDateTime""2023-12-30 15:10:21",

                    "MarginPercentage""3.5",

                    "CommissionPercentage""0.000000",

                    "Source""REUTERS WHOLESALE INTERBANK",

                    "SourceTimestamp""2022-03-29 17:31:06"

                }

            ]

        },

        "ApplicationID""{56CDF444-B238-4609-9137-148A34B08F59}",

        "Command""DynamicCurrencyConversion",

        "Mode""Live",

        "RequestID""{E575AA65-8C06-4814-B9CC-A99AD4C06EB1}",

        "Result": {

            "Status""0",

            "Code""0",

            "Description""",

            "AppServer""QA2019GWAPP01",

            "DBServer""QA2019GWDB02",

            "Gateway""QA",

            "AcquirerCode""00",

            "AcquirerDescription"""

        }

    }

}

 

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <soap:Body>

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

            <ExecuteResult>&lt;V_XML Version="2.0" Direction="Response"&gt;

  &lt;Enquiry ApplicationID="{56CDF444-B238-4609-9137-148A34B08F59}" Command="DynamicCurrencyConversion" Mode="Live" RequestID="{0192B92C-E645-4E67-877D-4EEB71492818}"&gt;

    &lt;Result Status="0" Code="0" Description="" AppServer="QA2019GWAPP01" DBServer="QA2019GWDB02" Gateway="QA" AcquirerCode="00" AcquirerDescription="" /&gt;

    &lt;MerchantName&gt;Busiswa&lt;/MerchantName&gt;

    &lt;MerchantUSN&gt;1732460&lt;/MerchantUSN&gt;

    &lt;Acquirer&gt;NBPostilionNBSouthAfrica&lt;/Acquirer&gt;

    &lt;AcquirerReference&gt;02848:09021749&lt;/AcquirerReference&gt;

    &lt;AcquirerDate&gt;20221230&lt;/AcquirerDate&gt;

    &lt;AcquirerTime&gt;153200&lt;/AcquirerTime&gt;

    &lt;Currency&gt;ZAR&lt;/Currency&gt;

    &lt;Amount&gt;2000&lt;/Amount&gt;

    &lt;MerchantAddress&gt;MERCHANT ADDRESS&lt;/MerchantAddress&gt;

    &lt;MerchantCity&gt;Sandton&lt;/MerchantCity&gt;

    &lt;MerchantCountryCode&gt;ZA&lt;/MerchantCountryCode&gt;

    &lt;MerchantCountry&gt;South Africa&lt;/MerchantCountry&gt;

    &lt;DistributorName&gt;Nedbank&lt;/DistributorName&gt;

    &lt;ForeignExchange&gt;

      &lt;ForeignExchangeItem Version="1.0"&gt;

        &lt;ForeignExchangeID&gt;{62EC3B82-BD4A-40D0-9AB1-79996761A17E}&lt;/ForeignExchangeID&gt;

        &lt;ForeignExchangeProvider&gt;Fexco&lt;/ForeignExchangeProvider&gt;

        &lt;BaseCurrency&gt;ZAR&lt;/BaseCurrency&gt;

        &lt;BaseAmount&gt;20.00&lt;/BaseAmount&gt;

        &lt;ForeignCurrency&gt;KES&lt;/ForeignCurrency&gt;

        &lt;ForeignAmount&gt;162.12&lt;/ForeignAmount&gt;

        &lt;ExchangeRate&gt;8.1058&lt;/ExchangeRate&gt;

        &lt;ExpiryDateTime&gt;2023-12-30 15:30:27&lt;/ExpiryDateTime&gt;

        &lt;MarginPercentage&gt;3.5&lt;/MarginPercentage&gt;

        &lt;CommissionPercentage&gt;0.000000&lt;/CommissionPercentage&gt;

        &lt;Source&gt;REUTERS WHOLESALE INTERBANK&lt;/Source&gt;

        &lt;SourceTimestamp&gt;2022-03-29 17:31:06&lt;/SourceTimestamp&gt;

      &lt;/ForeignExchangeItem&gt;

    &lt;/ForeignExchange&gt;

  &lt;/Enquiry&gt;

&lt;/V_XML&gt;</ExecuteResult>

        </ExecuteResponse>

    </soap:Body>

</soap:Envelope>

 

 Perform a transaction using the customers elected currency

 

REST

SOAP

Request

 

{

    "Version""2.0",

    "CertificateID""{4c96973f-71dd-4044-802d-6e234effe8f2}",

    "ProductType""Enterprise",

    "ProductVersion""WebAPI",

    "Direction""Request",

    "Transaction": {

        "ApplicationID""{56cdf444-b238-4609-9137-148a34b08f59}",

        "Command""Debit",

        "Mode""LIVE",

        "MerchantReference""Farm_12098",

        "MerchantTrace""20220520_1631",

        "Currency""ZAR",

        "Amount""5000",

        "ExpiryDate""1225",

        "CardSecurityCode""001",

        "PAN""5185520050000010",

        "ForeignAmount""40529",

        "ForeignCurrency""KES",

        "ForeignExchangeID":"{3056511A-360E-4C57-8437-4BEBE5CF0CD4}"

 

    }

}

 

<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>false</validateRequest>

  <protocol>V_XML</protocol>

  <protocolVersion>7.0</protocolVersion>

  <request>

    &lt;V_XML Version="2.0" CertificateID="{4c96973f-71dd-4044-802d-6e234effe8f2}" 

    ProductType="Enterprise" ProductVersion="iVeriWebService" Direction="Request"&gt;

    &lt;Enquiry ApplicationID="{56cdf444-b238-4609-9137-148a34b08f59}" Command= Mode="Live"&gt;

    &lt;MerchantTrace&gt;240X568VFEEE&lt;/MerchantTrace&gt;

    &lt;Amount&gt;2000&lt;/Amount&gt;

    &lt;Currency&gt;ZAR&lt;/Currency&gt;

    &lt;ExpiryDate&gt;1225&lt;/ExpiryDate&gt;

    &lt;MerchantReference&gt;20220104.1525&lt;/MerchantReference&gt;

    &lt;CardSecurityCode&gt;001&lt;/CardSecurityCode&gt;

    &lt;PAN&gt;5185520050000010&lt;/PAN&gt;

    &lt;/Enquiry&gt;&lt;/V_XML&gt;

        &lt;ForeignExchangeID&gt;{62EC3B82-BD4A-40D0-9AB1-79996761A17E}&lt;/ForeignExchangeID&gt;

        &lt;ForeignCurrency&gt;KES&lt;/ForeignCurrency&gt;

        &lt;ForeignAmount&gt;16212&lt;/ForeignAmount&gt;

 

</request>

  </Execute>

  </soap:Body>

  </soap:Envelope>

 

 

Response

{

    "Version""2.0",

    "Direction""Response",

    "Transaction": {

        "MerchantTrace""20220520_1631",

        "Amount""5000",

        "AuthorisationCode""012247",

        "CCNumber""5185........0010",

        "Currency""ZAR",

        "ExpiryDate""122025",

        "MerchantReference""Farm_12098",

        "Terminal""Default",

        "TransactionIndex""{C4BF6D8A-E6DF-4B92-8B40-056CA516A5FE}",

        "MerchantName""Busiswa",

        "MerchantUSN""1732460",

        "Acquirer""NBPostilionNBSouthAfrica",

        "AcquirerReference""02848:09021750",

        "AcquirerDate""20221230",

        "AcquirerTime""155823",

        "DisplayAmount""R 50.00",

        "BIN""5",

        "Association""MasterCard",

        "CardType""Unknown Card Type",

        "Issuer""Unknown Issuer",

        "Jurisdiction""International",

        "PAN""5185........0010",

        "PANMode""Keyed",

        "ReconReference""09021750",

        "CardHolderPresence""CardNotPresent,MOTO",

        "MerchantAddress""MERCHANT ADDRESS",

        "MerchantCity""Sandton",

        "MerchantCountryCode""ZA",

        "MerchantCountry""South Africa",

        "DistributorName""Nedbank",

        "ForeignAmount""40529",

        "ForeignCurrency""KES",

        "DisplayForeignAmount""KSh 405.29",

        "ApplicationID""{56CDF444-B238-4609-9137-148A34B08F59}",

        "Command""Debit",

        "Mode""Live",

        "RequestID""{F9EE9359-9D62-46C3-AE4E-97E151A8EB6E}",

        "Result": {

            "Status""0",

            "Code""0",

            "Description""",

            "AppServer""QA2019GWAPP01",

            "DBServer""QA2019GWDB02",

            "Gateway""QA",

            "AcquirerCode""00",

            "AcquirerDescription"""

        }

    }

}

 

 



Multi-Currency Pricing (MCP)


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.

MCP Transaction Flow

  • Perform an enquiry message using MCP enquiry message.
  • Merchant makes use of the returned list of MPC rates and perform transactions based on the customers elected currency. 


NB: Support of MCP is not yet publicly available to merchants.


MCP - SAMPLES


MCP - SAMPLES

 

REST

SOAP

Request

{

    "Version""2.0",

    "CertificateID""{4c96973f-71dd-4044-802d-6e234effe8f2}",

    "ProductType""Enterprise",

    "ProductVersion""WebAPI",

    "Direction""Request",

    "Enquiry": {

        "ApplicationID""{56cdf444-b238-4609-9137-148a34b08f59}",

        "Command"" MultiCurrencyPricing ",

        "Mode""LIVE",

        "MerchantReference""Farm_1709",

        "MerchantTrace""20220520_1706",

        "Currency""ZAR",

        "Amount""5000",

        "ExpiryDate""1225",

        "CardSecurityCode""001",

        "PAN""5185520050000010"

    }

}

 

<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>false</validateRequest>

  <protocol>V_XML</protocol>

  <protocolVersion>7.0</protocolVersion>

  <request>

    &lt;V_XML Version="2.0" CertificateID="{4c96973f-71dd-4044-802d-6e234effe8f2}" 

    ProductType="Enterprise" ProductVersion="iVeriWebService" Direction="Request"&gt;

    &lt;Enquiry ApplicationID="{56cdf444-b238-4609-9137-148a34b08f59}" Command=" MultiCurrencyPricing " Mode="Live"&gt;

    &lt;MerchantTrace&gt;240X568VFEEE&lt;/MerchantTrace&gt;

    &lt;Amount&gt;2000&lt;/Amount&gt;

    &lt;Currency&gt;ZAR&lt;/Currency&gt;

    &lt;ExpiryDate&gt;1225&lt;/ExpiryDate&gt;

    &lt;MerchantReference&gt;20220104.1525&lt;/MerchantReference&gt;

    &lt;CardSecurityCode&gt;001&lt;/CardSecurityCode&gt;

    &lt;PAN&gt;5185520050000010&lt;/PAN&gt;

    &lt;/Enquiry&gt;&lt;/V_XML&gt;

</request>

  </Execute>

  </soap:Body>

  </soap:Envelope>

 

Response

{

    "Version""2.0",

    "Direction""Response",

    "Enquiry": {

        "MerchantName""Busiswa",

        "MerchantUSN""1732460",

        "Acquirer""NBPostilionNBSouthAfrica",

        "AcquirerReference""02848:09021748",

        "AcquirerDate""20221230",

        "AcquirerTime""151154",

        "Currency""ZAR",

        "Amount""5000",

        "MerchantAddress""MERCHANT ADDRESS",

        "MerchantCity""Sandton",

        "MerchantCountryCode""ZA",

        "MerchantCountry""South Africa",

        "DistributorName""Nedbank",

        "ForeignExchange": {

            "ForeignExchangeItem": [

                {

                    "Version""1.0",

                    "ForeignExchangeID""{3056511A-360E-4C57-8437-4BEBE5CF0CD4}",

                    "ForeignExchangeProvider""Fexco",

                    "BaseCurrency""ZAR",

                    "BaseAmount""50.00",

                    "ForeignCurrency""KES",

                    "ForeignAmount""405.29",

                    "ExchangeRate""8.1058",

                    "ExpiryDateTime""2023-12-30 15:10:21",

                    "MarginPercentage""3.5",

                    "CommissionPercentage""0.000000",

                    "Source""REUTERS WHOLESALE INTERBANK",

                    "SourceTimestamp""2022-03-29 17:31:06"

                }

            ]

        },

        "ApplicationID""{56CDF444-B238-4609-9137-148A34B08F59}",

        "Command""DynamicCurrencyConversion",

        "Mode""Live",

        "RequestID""{E575AA65-8C06-4814-B9CC-A99AD4C06EB1}",

        "Result": {

            "Status""0",

            "Code""0",

            "Description""",

            "AppServer""QA2019GWAPP01",

            "DBServer""QA2019GWDB02",

            "Gateway""QA",

            "AcquirerCode""00",

            "AcquirerDescription"""

        }

    }

}

 

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <soap:Body>

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

            <ExecuteResult>&lt;V_XML Version="2.0" Direction="Response"&gt;

  &lt;Enquiry ApplicationID="{56CDF444-B238-4609-9137-148A34B08F59}" Command="DynamicCurrencyConversion" Mode="Live" RequestID="{0192B92C-E645-4E67-877D-4EEB71492818}"&gt;

    &lt;Result Status="0" Code="0" Description="" AppServer="QA2019GWAPP01" DBServer="QA2019GWDB02" Gateway="QA" AcquirerCode="00" AcquirerDescription="" /&gt;

    &lt;MerchantName&gt;Busiswa&lt;/MerchantName&gt;

    &lt;MerchantUSN&gt;1732460&lt;/MerchantUSN&gt;

    &lt;Acquirer&gt;NBPostilionNBSouthAfrica&lt;/Acquirer&gt;

    &lt;AcquirerReference&gt;02848:09021749&lt;/AcquirerReference&gt;

    &lt;AcquirerDate&gt;20221230&lt;/AcquirerDate&gt;

    &lt;AcquirerTime&gt;153200&lt;/AcquirerTime&gt;

    &lt;Currency&gt;ZAR&lt;/Currency&gt;

    &lt;Amount&gt;2000&lt;/Amount&gt;

    &lt;MerchantAddress&gt;MERCHANT ADDRESS&lt;/MerchantAddress&gt;

    &lt;MerchantCity&gt;Sandton&lt;/MerchantCity&gt;

    &lt;MerchantCountryCode&gt;ZA&lt;/MerchantCountryCode&gt;

    &lt;MerchantCountry&gt;South Africa&lt;/MerchantCountry&gt;

    &lt;DistributorName&gt;Nedbank&lt;/DistributorName&gt;

    &lt;ForeignExchange&gt;

      &lt;ForeignExchangeItem Version="1.0"&gt;

        &lt;ForeignExchangeID&gt;{62EC3B82-BD4A-40D0-9AB1-79996761A17E}&lt;/ForeignExchangeID&gt;

        &lt;ForeignExchangeProvider&gt;Fexco&lt;/ForeignExchangeProvider&gt;

        &lt;BaseCurrency&gt;ZAR&lt;/BaseCurrency&gt;

        &lt;BaseAmount&gt;20.00&lt;/BaseAmount&gt;

        &lt;ForeignCurrency&gt;KES&lt;/ForeignCurrency&gt;

        &lt;ForeignAmount&gt;162.12&lt;/ForeignAmount&gt;

        &lt;ExchangeRate&gt;8.1058&lt;/ExchangeRate&gt;

        &lt;ExpiryDateTime&gt;2023-12-30 15:30:27&lt;/ExpiryDateTime&gt;

        &lt;MarginPercentage&gt;3.5&lt;/MarginPercentage&gt;

        &lt;CommissionPercentage&gt;0.000000&lt;/CommissionPercentage&gt;

        &lt;Source&gt;REUTERS WHOLESALE INTERBANK&lt;/Source&gt;

        &lt;SourceTimestamp&gt;2022-03-29 17:31:06&lt;/SourceTimestamp&gt;

      &lt;/ForeignExchangeItem&gt;

    &lt;/ForeignExchange&gt;

  &lt;/Enquiry&gt;

&lt;/V_XML&gt;</ExecuteResult>

        </ExecuteResponse>

    </soap:Body>

</soap:Envelope>

 


3D Secure


3D Secure

 
3D secure is an EMVCO standard which is made up of 6 major card brand networks, allowing merchants to accept and process authenticated online transactions by cardholders with their bank prior to the actual authorization of the payment.
Through the iVeri Gateway, the following 3D secure authentication services from the card schemes are supported 


  • Verified by VISA (VbV),
  • SecureCode by Mastercard, 
  • SafeKey by American Express, 
  • UPOP by UPI
  • Protect Buy by Diners
  • SPA

Also, important to note, the Gateway currently supports two version of 3D secure – 3D secure V1.x and 3D Secure V2.x, support however is subject to acquirer and regional mandates where the Gateway has a footprint.

Merchant Benefits

  • Acceptance of authenticated transactions via 3D secure deters unauthorized card use.
  • Enables the merchants to receive protection, liability shift from fraudulent chargeback activity


Integrate 3D Secure


Integrate 3D Secure

 
Integrate 3D Secure functions via the iVeri Gateway

  • Implement a form post with the required data 
  • When received, the Gateway will process and handle the enrollment lookups, authentication with the 3DS provider on your behalf 
  • On completion, of the authentication, the merchant can submit payment instruction with the 3D 2 authentication data


Integrate 3D Secure directly with the 3DSecure MPI vendor 


  • Contact 3D secure Vendor
  • Integrate the 3D secure using the 3D secure integration specification from the MPI/3D Secure  vendor
  • On completion of the 3D secure process, merchants, or Payment service Provider (PSP) can include 3D secure authentication data on the payment instructions to the iVeri Gateway.
  • When received, the Gateway will process the payment to the appropriate acquirer


3DS 2
3D secure 2 is the latest standard released by EMVCo that allows merchants and payment service providers to send additional data elements to the issuing bank of the cardholder, which in turn, makes it possible for the issuer of the card to perform frictionless authentication and offer an improved, better, user experience to the cardholder. With the additional data elements relating to the cardholder, issuers can apply Frictionless Authentication flows or “Challenged” authentication flows.


Frictionless Authentication Flows:  issuers can apply risk-based decisions using the additional data received and trust that the real cardholder is making the purchase and auto authenticate the transaction in the background without requesting any additional information from the cardholder.
Challenged Authentication Flows:  When the issuer cannot apply risk-based decision using the data on record, additional information to authenticate the payment is then requested from the cardholder.


Integration Prerequisites 

  • Merchant must request a certificate in the merchant portal Backoffice.
    • The certificate ID of the generated certificate is only applicable on the Authorisation message, upon completion of the 3DS process.
  • A merchant profile, where the test application ID must be enabled for 3DS 2


3DS 2 Endpoint:  https:// [portal base URL]/threedsecure/EnrollmentInitial 

Implementation of 3DS 2 to the iVeri Gateway can be done by either using as a form Post or Pop-up


3DS 2 Parameters


3DS 2 Parameters

 

Response Parameters

Parameter

Description

Merchant ReturnUrl 

Mandatory: The URL which the Gateway will post return response parameters to 

ApplicationID 

Mandatory: Merchant Application ID generated upon the creation of the merchant profile on the iVeri Gateway  

MerchantReference

Mandatory: A merchant generated identifier that is unique within a specified time that identifies a transaction sequence.

Amount

Mandatory: The total value of the transaction in the smallest unit of the currency specified (eg in cents)

Currency

Mandatory: The ISO 4217 currency code of the value of the transaction. e.g., USD or ZAR or GBP

PAN

Mandatory: Card number used for transaction

ExpiryDate

Mandatory: The last month of the validity period of the card, formatted as MMYY or   MMYYYY

CardSecurityCode

The 3 or 4 digits printed on the card which are not contained on the magnetic strip. Usually printed after the Card number on the signature strip. Corresponds to American Express CIV, MasterCard CVC2 and VISA CVV2

Note:  Depending on the result of 3D secure authentication, the following fields will be returned

 

Parameter

Description

ApplicationID

Identification of the merchant profile performing the transaction

MerchantReference 

 

Amount

 

Currency

 

JWT 

 

PAN 

 

ExpiryDate 

 

ResultCode

 

ResultDescription 

 

ThreeDSecure_AuthenticationType

Expected Value: 01

CardHolderAuthenticationID 

Commonly known XID: Unique identifier generated during the 3DS process

CardHolderAuthenticationData 

 

ElectronicCommerceIndicator 

Commonly known as “ECI”: Indicates if the cardholder was fully authenticated, attempted or not.

Possible values: ThreeDSecure (ECI “05”, “02”), ThreeDSecureAttempted (“ECI “06” or “01”) or SecureChannel (ECI “07”)

ThreeDSecure_VEResEnrolled 

Possible values:  Y|N|U - Indicates if the card is enrolled.

ThreeDSecure_RequestID 

 

ThreeDSecure_ProtocolVersion

Indicates the version of 3D secure used

ThreeDSecure_DSTransID 

Directory Server Transaction ID returned for the transaction



3D Secure 2 implementation using the Pop-Up Method


3D Secure 2 implementation using the Pop-Up Method

 
Mandatory Requirements
 
Merchants can use the from the Gateway or they can build their own:
 
jQuery =  [portal domain]/scripts/jquery/js/https://jquery.min.js/ 
Bootstrap = [portal domain] /scripts/jquery/js/https://jquery.tdsbox.js/

 
Step1:  Initialize the popup   

Include the following javascript code on your webpage that you want to initiate 3DS from:



$(document).ready(function () { 
    tdsboxInitialise('[portal domain]',  
    tdsboxComplete); 
}); 
 

 

Step2:  Load the popup and shows the modal dialog  
       
function loadModal() { 
    var jsonObject = { 
            ApplicationID : $("#ApplicationID").val(), 
            MerchantReference : $("#MerchantReference").val(), 
            Amount : $("#Amount").val(), 
            Currency : $("#Currency").val(), 
            PAN : $("#PAN").val(), 
            ExpiryDate : $("#ExpiryDate").val() 
        }; 
    var data = JSON.stringify(jsonObject);             
    tdsboxSubmit(data);             




Step 3:  Gets the response back after 3D 2 Completes
       
function tdsboxComplete(data) {
alert(data);
 



3D Secure 2 implementation using the Form Post


3D Secure 2 implementation using the Form Post


Merchant can POST Form variables to the 3DS 2 endpoint, which is redirect over the browser. On completion of the 3D secure process, the Gateway will return the result to the merchant ReturnURL. The result returned to the merchant will either allow for the continuation of the Authorisation/debit instruction or result in the termination of the transaction by the merchant to the customer.

Format: Form Data

Form Post request Sample

<form name="Form1" method="post"action="https://portal.iveri.net/threedsecure/EnrollmentInitial" id="Form1">

                                             <input type="hidden" name="ApplicationID" id="ApplicationID" value="{ca8a6eae-a469-4b39-bef3-aa029ca3a806}" />

                                             <input type="hidden" name="ReturnUrl" id="ReturnUrl" value="https://[domain]/Lite/Result.asp" />

                                             <div>Amount:</div><input type="text" name="Amount" id="Amount" value="2000" /></br>

                                             <input type="hidden" name="Currency" id="Currency" value="ZAR" />

                                             <div>Reference:</div><input type="text" name="MerchantReference" id="MerchantReference" value="3DS2:20210920.001" /></br>

                                             <div>PAN:</div><input type="text" name="PAN" id="PAN" value="5192602720584796" /></br>

                                             <div>Expiry:</div><input type="text" name="ExpiryDate" id="ExpiryDate" value="012023" /></br>

                                             <br />

                                             <input type="submit" name="buttonPostData" value="Post Data" id="buttonPostData" class="clsButton" style="width:90px;" />

                             

</form>

 

 


Authorisation/Debit with 3DS 2 Data


Authorisation/Debit with 3DS 2 Data

 

Merchants can POST payment instructions with 3D secure authentication (where applicable) using the SOAP or REST webservice. 

Debit/Authorisation Payment Parameters
The applicable set of 3DS 2 parameters expected in the Authorisation/Debit message are as follows

Parameter

Description

CardHolderAuthenticationID 

Mandatory for 3DS 1 and 2: Commonly known as an XID: Unique identifier generated during the 3D secure process

CardHolderAuthenticationData 

Mandatory for 3DS 1 and 2: Commonly known as UCAF -(universal cardholder authentication field) for Mastercard or CAVV( cardholder authentication verification value)generated on completion of the authentication  between cardholder and card issuer

ElectronicCommerceIndicator 

Mandatory for 3DS 1 and 2: Commonly known as “ECI”: Indicates if the cardholder was fully authenticated, attempted or not.

Possible values: ThreeDSecure (ECI “05”, “02”), ThreeDSecureAttempted (“ECI “06” or “01”) or SecureChannel (ECI “07”)

ThreeDSecure_VEResEnrolled 

Optional: Possible values:  Y|N|U - Indicates if the card is enrolled.

ThreeDSecure_RequestID 

Optional: Unique identifier returned by the Gateway on completion of the 3D secure authentication process 

New 3D Secure 2 Parameters

ThreeDSecure_AuthenticationType

Optional: Possible values( not limited to) "01", "02", "03". Must be as generated on completion of the 3D secure authentication process. indicates the method of authentication used.

ThreeDSecure_ProtocolVersion

Mandatory: Indicates the version of 3D secure used


ThreeDSecure_DSTransID 

Mandatory: Directory Server Transaction ID returned on completion of the 3D secure authentication process  

 

 


Webservice Service Payment Samples
For submission of transactions to the Gateway the merchant can post to the existing Portal URL's . The Portal URL's are listed in the  REST and SOAP sections by acquiring bank. As a note, the submission of the Debit/Authorisation message assumes the following:

  • 3DS 2 authentication was a success.
  • The merchant is making use of the test application ID with mode "Test" for integration testing 
REST Webservice
SOAP Webservice

Format: JSON

Transaction Endpoint - https://[portal domain]/api/transactions

 

 

 

{

    "Version": "2.0",

    "CertificateID": "{4c96973f-71dd-4044-802d-6e234effe8f2}",

    "ProductType": "Enterprise",

    "ProductVersion": "WebAPI",

    "Direction": "Request",

    "Transaction": {

        "ApplicationID": "{ca8a6eae-a469-4b39-bef3-aa029ca3a806}",

        "Command": "Debit",

        "Mode": "Test",

        "Amount": "1500",

        "ExpiryDate": "0123",

        "MerchantReference": "3DS2:20210920.004",

        "Currency": "ZAR",

        "PAN": "4069425217889137",

        "ThreeDSecure_ProtocolVersion": "2.1.0",

        "CardHolderAuthenticationID": "xVyRZy0bYuN69j1pZi/zlmC68Vw=",

        "CardHolderAuthenticationData": "AJkBCWhygQAAAAEDhXKBAAAAAAA=",

        "ElectronicCommerceIndicator": "ThreeDSecure",

        "ThreeDSecure_DSTransID": "2e962032-0499-4fb6-9cf3-e640ceebeb63",

        "ThreeDSecure_AuthenticationType":  "01"

        "ThreeDSecure_VEResEnrolled": "Y"

    }

}

 

 

 

 

Format: XML

Transaction Endpoint - https://[portal domain] /iVeriWebservice/Service.asmx

 

 

 

<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>false</validateRequest>

  <protocol>V_XML</protocol>

  <protocolVersion>7.0</protocolVersion>

  <request>&lt;V_XML Version="2.0" CertificateID="b2fd980c-f61a-473e-a685-5e8d38595d84" ProductType="Enterprise"

ProductVersion="iVeriWebService" Direction="Request"&gt;

&lt;Transaction ApplicationID="66bc5003-88dd-4cd5-9b27-2b5cdb7a8b73" Command="Debit" Mode="Test"&gt;

&lt;MerchantTrace&gt;9AE2405C07E7227568BEEE5A58E890&lt;/MerchantTrace&gt;

&lt;Amount&gt;2000&lt;/Amount&gt;

&lt;Currency&gt;ZAR&lt;/Currency&gt;

&lt;ExpiryDate&gt;012023&lt;/ExpiryDate&gt;

&lt;MerchantReference&gt;3DS2:202112.002&lt;/MerchantReference&gt;

&lt;CardSecurityCode&gt;123&lt;/CardSecurityCode&gt;

&lt;PAN&gt;4069425217889137&lt;/PAN&gt;

&lt;ElectronicCommerceIndicator&gt;ThreeDSecure&lt;/ElectronicCommerceIndicator&gt;

&lt;CardHolderAuthenticationID&gt;nhkWtFs6DlxCbpAyOFmjjxTtZOc=&lt;/CardHolderAuthenticationID&gt;

&lt;CardHolderAuthenticationData&gt;AJkBCIZ1CQAAAAfQcQADdISCkYQ=&lt;/CardHolderAuthenticationData&gt;

&lt;ThreeDSecure_ProtocolVersion&gt;2.1.0&lt;/ThreeDSecure_ProtocolVersion&gt;

&lt;ThreeDSecure_DSTransID&gt;c43c9d4a-3461-46e9-be29-3c7a0e033e11&lt;/ThreeDSecure_DSTransID&gt;

&lt;ThreeDSecure_AuthenticationType&gt;01&lt;/ThreeDSecure_AuthenticationType&gt;

&lt;ThreeDSecure_VEResEnrolled&gt;Y&lt;/ThreeDSecure_VEResEnrolled&gt;

&lt;/Transaction&gt;

&lt;/V_XML&gt;

</request>

  </Execute>

  </soap:Body>

  </soap:Envelope>

 

Response:

 

{

    "Version": "2.0",

    "CertificateID": "{4c96973f-71dd-4044-802d-6e234effe8f2}",

    "ProductType": "Enterprise",

    "ProductVersion": "WebAPI",

    "Direction": "Request",

    "Transaction": {

        "ApplicationID": "{ca8a6eae-a469-4b39-bef3-aa029ca3a806}",

        "Command": "Debit",

        "Mode": "Test",

        "Amount": "1500",

        "ExpiryDate": "0123",

        "MerchantReference": "3DS2:20210920.004",

        "Currency": "ZAR",

        "PAN": "4069425217889137",

        "ThreeDSecure_ProtocolVersion": "2.1.0",

        "CardHolderAuthenticationID": "xVyRZy0bYuN69j1pZi/zlmC68Vw=",

        "CardHolderAuthenticationData": "AJkBCWhygQAAAAEDhXKBAAAAAAA=",

        "ElectronicCommerceIndicator": "ThreeDSecure",

        "ThreeDSecure_DSTransID": "2e962032-0499-4fb6-9cf3-e640ceebeb63",

        "ThreeDSecure_AuthenticationType":  "01"

        "ThreeDSecure_VEResEnrolled": "Y"

    }

}

 

 

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <soap:Body>

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

            <ExecuteResult>&lt;V_XML Version="2.0" Direction="Response"&gt;

  &lt;Transaction ApplicationID="{66BC5003-88DD-4CD5-9B27-2B5CDB7A8B73}" Command="Debit" Mode="Test" RequestID="{AF5214BF-878E-4691-A124-96E0748CF062}"&gt;

    &lt;Result Status="0" Code="0" Description="" AppServer="QAGW2012APP1" DBServer="QAGW2012DB2" Gateway="QA" AcquirerCode="00" AcquirerDescription="" /&gt;

    &lt;MerchantTrace&gt;9AE2405C07E7227568BEEE5A58E890&lt;/MerchantTrace&gt;

    &lt;Amount&gt;2000&lt;/Amount&gt;

    &lt;AuthorisationCode&gt;315669&lt;/AuthorisationCode&gt;

    &lt;CCNumber&gt;4069........9137&lt;/CCNumber&gt;

    &lt;Currency&gt;ZAR&lt;/Currency&gt;

    &lt;ElectronicCommerceIndicator&gt;ThreeDSecure&lt;/ElectronicCommerceIndicator&gt;

    &lt;ExpiryDate&gt;012023&lt;/ExpiryDate&gt;

    &lt;MerchantReference&gt;3DS2:202112.002&lt;/MerchantReference&gt;

    &lt;Terminal&gt;Default&lt;/Terminal&gt;

    &lt;TransactionIndex&gt;{F9401D94-4CA7-46EF-A007-9883950A80D3}&lt;/TransactionIndex&gt;

    &lt;MerchantName&gt;iVeri Payment Technology&lt;/MerchantName&gt;

    &lt;MerchantUSN&gt;7771777&lt;/MerchantUSN&gt;

    &lt;Acquirer&gt;NBPostilionNBSouthAfrica&lt;/Acquirer&gt;

    &lt;AcquirerReference&gt;81774:09170322&lt;/AcquirerReference&gt;

    &lt;AcquirerDate&gt;20220103&lt;/AcquirerDate&gt;

    &lt;AcquirerTime&gt;154109&lt;/AcquirerTime&gt;

    &lt;DisplayAmount&gt;R 20.00&lt;/DisplayAmount&gt;

    &lt;BIN&gt;4&lt;/BIN&gt;

    &lt;Association&gt;VISA&lt;/Association&gt;

    &lt;CardType&gt;Unknown Card Type&lt;/CardType&gt;

    &lt;Issuer&gt;Unknown Issuer&lt;/Issuer&gt;

    &lt;Jurisdiction&gt;International&lt;/Jurisdiction&gt;

    &lt;PAN&gt;4069........9137&lt;/PAN&gt;

    &lt;PANMode&gt;Keyed,CVV&lt;/PANMode&gt;

    &lt;ReconReference&gt;09170322&lt;/ReconReference&gt;

    &lt;CardHolderPresence&gt;CardNotPresent,eCommerce,ThreeDSecure&lt;/CardHolderPresence&gt;

    &lt;MerchantAddress&gt;MERCHANT ADDRESS&lt;/MerchantAddress&gt;

    &lt;MerchantCity&gt;Sandton&lt;/MerchantCity&gt;

    &lt;MerchantCountryCode&gt;ZA&lt;/MerchantCountryCode&gt;

    &lt;MerchantCountry&gt;South Africa&lt;/MerchantCountry&gt;

    &lt;DistributorName&gt;Nedbank&lt;/DistributorName&gt;

  &lt;/Transaction&gt;

&lt;/V_XML&gt;</ExecuteResult>

        </ExecuteResponse>

    </soap:Body>

</soap:Envelope>

 

 

 




3D Secure 2 Test Cases BY 3D secure Vendor/MPI


3D Secure 2 Test Cases BY 3D secure Vendor/MPI

 
The MPI test cases that should be used are depended on the acquiring bank that holds the merchant agreement or PSP that will be processing the payments on the Gateway on behalf of the merchant


Things to note about the test cards:

  • CVV not required
  • Expiry must be current or future date 


BANKSERV

 

Frictionless Full authentication

Scenario 1

Authenticated Frictionless Transaction

Test Values

Visa:4069425217889137

MC:5163426869252246

DINERS:36135230403232

Expected results - Lookup

EnrolledStatus: Y

paresTxStatus: Y

TDS2.transStatus: Y

ECI (Visa): 05

ECI (MCI): 02

ECI (DINERS): 05

PARESVERIFIED: true

PROTOCOL: 3DS 2.1.0

 MD_STATUS: 1

MD_ERROR_MESSAGE: Authenticated

Action:  Merchant should proceed with the authorization message Note Pan supplied configured for frictionless authentication

Failed Frictionless Authentication

Scenario 2

Failed Frictionless Transaction

Test Values

Visa: 4069421358347845

MC: 5178872338408971

DINERS: 36135234130393

Expected results - Lookup

EnrolledStatus: Y

paresTxStatus: N

TDS2.transStatus: N

ECI (Visa): Blank, (will default to ECI 07)

ECI (MCI): Blank, will default to ECI 00) (DINERS): Blank, (will default to ECI 07)

PARESVERIFIED: True

PROTOCOL: 3DS 2.1.0

MD_STATUS: 0

MD_ERROR_MESSAGE: NOT Authenticated

Action:  Merchant should NOT proceed with the authorization message Note Pan supplied configured for frictionless authentication


CYBERSOURCE

 

Frictionless Full Authentication

Scenario 1

Authenticated Frictionless Transaction

Test Values

Visa: 445653 00 0000 1005

445653 00 0000 0001 007

 

MC: 520000 00 0000 1005

520000 00 0000 3001

 

 

Expected results - Lookup

Reason code = 100

 ics_pa_enroll service was successful.

VERes enrolled = Y

PARes status = Y

 CAVV = AVV = (Mastercard only)

 

Action:  Merchant should proceed with the authorization message Note Pan supplied configured for frictionless authentication


Failed Frictionless Authentication

Scenario 2

Failed Frictionless Transaction

Test Values

Visa: 445653 00 0000 1013

445653 00 0000 3019

MC: 520000 00 0000 1013

520000 00 0000 3019

 

Expected results - Lookup

VERes enrolled = Y

PARes status = N

Reason code = 476

User failed authentication.

Action:  Merchant should NOT proceed with the authorization message. Ask the customer for another form of payment




Out of band transaction notification


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.

Prerequisite

  1. 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.
  2. 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)
  3. A Merchant developer will need to provide the target end of point of the Webservice


Merchant Webservice 


The sections covers the Webservice example which the merchant can implement in order to consume the transaction responses as and when they are delivered by the Gateway's out of band notification system.

Out of Band Sample

Sample from a merchant view point

namespace 

{

  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;

         }

     }

}

 


Card on File


Card on File

 

This section applies to transactions that are first initiated by the cardholder where 3D secure is enforced, whereafter monthly debits can be processed by the merchant. The same principle may be applied for the Batch (product) recurring transactions, even though in the below example we have used a second Enterprise application ID which is not 3DS enforced.


CIT with 3D Secure


CIT with 3D Secure

 
First 3DS Transaction
When performing your first transaction using application id: 00000000-263b-4315-b2cd-000000000000, the gateway will return the TransactionIndex, masked PAN and Expiry Date, which you will need to store in your database.

The following field response values need to be stored on your database, linked to the card holder details.

  • TransactionIndex
  • PAN
  • ExpiryDate


Subsequent - Recurring Transactions
Now comes the time you want to debit the same card.  You will need to pass the following using application id 01010101-7694-4343-95EE-010101010101 which is not 3DS enforced.
Note that this is a different Application ID to the one used for initial transaction but must reside within the same user group.

For this transaction you need to also include the following fields on your request:

  • PANFormat: This must always be fixed to TransactionIndex
  • PAN: You must provide the previous transaction ‘s response value. The masked PAN must be populated.
  • ExpiryDate: You must provide the previous transaction ‘s response value.

The combination of the above are used by the gateway to retrieve the missing digits of the card. Should the above not match to the previous transaction then your transaction will fail.

Subsequent Recurring Transaction Message
In the sample below "CardholderPresence" is set by the merchant on the Debit instruction:

 

REST

SOAP

{

    "Version""2.0",

    "CertificateID""{5c4b9c74-0063-4240-9cff-f730675c5bd0}",

    "ProductType""Enterprise",

    "ProductVersion""WebAPI",

    "Direction""Request",

    "Transaction": {

        "ApplicationID""{d8d5a94-8fa0-428d-a539-3a5baf166f7f}",

        "Command""Debit ",

        "Mode""Test",

        "MerchantReference""Ned20221214_1117",

        "Currency""ZAR"

        "Amount""1600",

        "ExpiryDate""1230",

        "PAN""4242........4242",

        "CardholderPresence""Recurring",

        "PANFormat""TransactionIndex",

        "TransactionIndex""7C256903-9097-41AE-81B6-54681B33301F"

        

 

    }

 

<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>false</validateRequest>

  <protocol>V_XML</protocol>

  <protocolVersion>7.0</protocolVersion>

  <request>

    &lt;V_XML Version="2.0" CertificateID="{5c4b9c74-0063-4240-9cff-f730675c5bd0}" 

    ProductType="Enterprise" ProductVersion="iVeriWebService"

 Direction="Request"&gt; &lt;Transaction ApplicationID="{6d8d5a94-8fa0-428d-a539-3a5baf166f7f}" Command="Debit" Mode="Test"&gt;

    &lt;MerchantTrace&gt;24AZNXBEEE&lt;/MerchantTrace&gt;

    &lt;Amount&gt;2000&lt;/Amount&gt;

    &lt;Currency&gt;ZAR&lt;/Currency&gt;

    &lt;ExpiryDate&gt;042024&lt;/ExpiryDate&gt;

    &lt;MerchantReference&gt;20220104.0931&lt;/MerchantReference&gt;

    &lt;CardholderPresence&gt;Recurring&lt;/CardholderPresence&gt;

    &lt;PANFormat&gt;TransactionIndex&lt;/PANFormat&gt;

    &lt;TransactionIndex&gt;7C256903-9097-41AE-81B6-54681B33301F&lt;/TransactionIndex&gt;

    &lt;PAN&gt;4242........4242&lt;/PAN&gt;

    &lt;/Transaction&gt;&lt;/V_XML&gt;

</request>

  </Execute>

  </soap:Body>

  </soap:Envelope>

 

REST Response

SOAP Response

{

    "Version""2.0",

    "Direction""Response",

    "Transaction": {

        "Amount""1600",

        "AuthorisationCode""811045",

        "CCNumber""4242........4242",

        "Currency""ZAR",

        "ExpiryDate""122030",

        "MerchantReference""Ned20221214_1117",

        "Terminal""Default",

        "TransactionIndex""{550B0E5C-AA2A-4A46-B7A4-9543338188D6}",

        "MerchantName""iVeri Payment Technology",

        "MerchantUSN""7771777",

        "Acquirer""NBPostilionNBSouthAfrica",

        "AcquirerReference""95713:04649948",

        "AcquirerDate""20230109",

        "AcquirerTime""091725",

        "DisplayAmount""R 16.00",

        "BIN""4",

        "Association""VISA",

        "CardType""Unknown CardType",

        "Issuer""Unknown Issuer",

        "Jurisdiction""International",

        "PAN""4242........4242",

        "PANMode""Tokenized",

        "ReconReference""04649948",

        "CardHolderPresence""CardNotPresent,Recurring",

        "MerchantAddress""MERCHANT ADDRESS",

        "MerchantCity""Sandton",

        "MerchantCountryCode""ZA",

        "MerchantCountry""South Africa",

        "DistributorName""Nedbank",

        "ApplicationID""{6D8D5A94-8FA0-428D-A539-3A5BAF166F7F}",

        "Command""Debit",

        "Mode""Test",

        "RequestID""{3ED8E51C-24AC-4959-8E8E-F3952DEF019A}",

        "Result": {

            "Status""0",

            "Code""0",

            "Description""",

            "AppServer""105IVERIAPPPR1N",

            "DBServer""105iveridbpr01n",

            "Gateway""Nedbank",

            "AcquirerCode""00",

            "AcquirerDescription"""

        }

    }

}

 

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

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

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <soap:Body>

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

            <ExecuteResult>&lt;V_XML Version="2.0" Direction="Response"&gt;

  &lt;Transaction ApplicationID="{6D8D5A94-8FA0-428D-A539-3A5BAF166F7F}" Command="Debit" Mode="Test" RequestID="{24A1FCA2-69F0-41ED-B5B7-AB07521EE5B6}"&gt;

    &lt;Result Status="0" Code="0" Description="" AppServer="105IVERIAPPPR2N"

 DBServer="105iveridbpr01n" Gateway="Nedbank" AcquirerCode="00" 

AcquirerDescription="" /&gt;

    &lt;MerchantTrace&gt;24AZNXBEEE&lt;/MerchantTrace&gt;

    &lt;Amount&gt;2000&lt;/Amount&gt;

    &lt;AuthorisationCode&gt;811887&lt;/AuthorisationCode&gt;

    &lt;CCNumber&gt;4242........4242&lt;/CCNumber&gt;

    &lt;Currency&gt;ZAR&lt;/Currency&gt;

    &lt;ExpiryDate&gt;042024&lt;/ExpiryDate&gt;

    &lt;MerchantReference&gt;20220104.0931&lt;/MerchantReference&gt;

    &lt;Terminal&gt;Default&lt;/Terminal&gt;

    &lt;TransactionIndex&gt;{C888BD10-0474-495B-84E7-A113C4C74C76}&lt;/TransactionIndex&gt;

    &lt;MerchantName&gt;iVeri Payment Technology&lt;/MerchantName&gt;

    &lt;MerchantUSN&gt;7771777&lt;/MerchantUSN&gt;

    &lt;Acquirer&gt;NBPostilionNBSouthAfrica&lt;/Acquirer&gt;

    &lt;AcquirerReference&gt;95713:04649951&lt;/AcquirerReference&gt;

    &lt;AcquirerDate&gt;20230109&lt;/AcquirerDate&gt;

    &lt;AcquirerTime&gt;093127&lt;/AcquirerTime&gt;

    &lt;DisplayAmount&gt;R 20.00&lt;/DisplayAmount&gt;

    &lt;BIN&gt;4&lt;/BIN&gt;

    &lt;Association&gt;VISA&lt;/Association&gt;

    &lt;CardType&gt;Unknown CardType&lt;/CardType&gt;

    &lt;Issuer&gt;Unknown Issuer&lt;/Issuer&gt;

    &lt;Jurisdiction&gt;International&lt;/Jurisdiction&gt;

    &lt;PAN&gt;4242........4242&lt;/PAN&gt;

    &lt;PANMode&gt;Tokenized&lt;/PANMode&gt;

    &lt;ReconReference&gt;04649951&lt;/ReconReference&gt;

    &lt;CardHolderPresence&gt;CardNotPresent,Recurring

&lt;/CardHolderPresence&gt;

    &lt;MerchantAddress&gt;MERCHANT ADDRESS&lt;/MerchantAddress&gt;

    &lt;MerchantCity&gt;Sandton&lt;/MerchantCity&gt;

    &lt;MerchantCountryCode&gt;ZA&lt;/MerchantCountryCode&gt;

    &lt;MerchantCountry&gt;South Africa&lt;/MerchantCountry&gt;

    &lt;DistributorName&gt;Nedbank&lt;/DistributorName&gt;

  &lt;/Transaction&gt;

&lt;/V_XML&gt;</ExecuteResult>

        </ExecuteResponse>

    </soap:Body>

</soap:Envelope>

 


Note in the above response you will receive a new TransactionIndex, each time a recurring payment is made, you can keep the new Transaction and daisy chain or use the original/first transaction



CIT - MOTO & COF


CIT - MOTO & COF

 
First Transaction
When performing your first transaction using application id: 00000000-263b-4315-b2cd-000000000000, the following options are available in

COF and Debit with PAN
Process a COF transactions by setting CardholderPrense to “MOTO, COF” and providing the full card details.

  • CardholderPresence": "MOTO, COF”
  • PAN:  
  • ExpiryDate: 


COF and Debit with TransactionIndex 

Process a COF transactions by setting the PANFormat and “Sanitised/tokenised card details. 

  • PANFormat 
  • PAN:  
  • ExpiryDate: 
  • TransactionIndex 


The gateway will return the TransactionIndex, masked PAN and Expiry Date, which you will need to store in your database. The following field response values should be stored on your database, linked to the card holder details.

  • TransactionIndex
  • PAN
  • ExpiryDate


Subsequent/COF Transaction
Now comes the time you want to debit the same card.  You will need to pass the following using application id 01010101-7694-4343-95EE-010101010101 which is not 3DS enforced.
Note that this is a different Application ID to the one used for initial transaction but must reside within the same user group.

For this transaction you need to also include the following fields on your request:

  • PANFormat: This must always be fixed to TransactionIndex
  • PAN: You must provide the previous transaction ‘s response value. The masked PAN must be populated.
  • ExpiryDate: You must provide the previous transaction ‘s response value.


The combination of the above are used by the gateway to retrieve the missing digits of the card. Should the above not match to the previous transaction then your transaction will fail.


MIT - Recurring & MOTO


MIT - Recurring & MOTO

 
First Transaction
When performing your first transaction using application id: 00000000-263b-4315-b2cd-000000000000, the gateway will return the TransactionIndex, masked PAN and Expiry Date, which you will need to store in your database.

Debit with PAN
Process a COF transactions by setting CardholderPrense to “MOTO, Recurring ” and providing the full card details.

  • CardholderPresence": "MOTO, Recurring”
  • PAN:  
  • ExpiryDate: 


Debit with TransactionIndex 

Process a Recurring transactions by setting the PANFormat and “Sanitised/tokenised card details. 

  • PANFormat 
  • PAN:  
  • ExpiryDate: 
  • TransactionIndex 



The following field response values need to be stored on your database, linked to the card holder details.

  • TransactionIndex
  • PAN
  • ExpiryDate


Subsequent - Recurring Transactions
Now comes the time you want to debit the same card.  You will need to pass the following using application id 01010101-7694-4343-95EE-010101010101 which is not 3DS enforced.
Note that this is a different Application ID to the one used for initial transaction but must reside within the same user group.

For this transaction you need to also include the following fields on your request:

  • PANFormat: This must always be fixed to TransactionIndex
  • PAN: You must provide the previous transaction ‘s response value. The masked PAN must be populated.
  • ExpiryDate: You must provide the previous transaction ‘s response value.
  • CardholderPresence: must be set to “Recurring”

The combination of the above are used by the gateway to retrieve the missing digits of the card. Should the above not match to the previous transaction then your transaction will fail.


Gateway Domain Knowledge


Gateway Domain Knowledge

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


Card Present vs. Card Not Present


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


Online vs. Offline Transactions


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

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.


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:

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

  1. approved, the merchant gets paid.
  2. 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.
  3. in error, then the transaction is retried until it is in a known state.


Ensuring End To End Transaction Integrity


Ensuring End To End Transaction Integrity

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


Individual transactions


Individual transactions

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

Examples of “something goes wrong” are:

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



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


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

Enterprise users call Void with the syntax like:    
enterprise.prepare("Transaction", "Void", applicationID, mode);
A Void request must set one of the following parameters: OriginalMerchantTrace or OriginalRequestID, for example:
enterprise.setTag("OriginalRequestID", requestID)

Result Code

Result Description

Action

0

Void successful

Transaction successfully voided.

13

Void unsuccessful

Too late to void the transaction.

1

Timeout

Void can be automatically retried a minute later

\9

Unable to process

Void can be automatically retried a minute later

255

General Error (Exception)

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


A Void has one of the following responses

If the iVeri Gateway receives a Void request referring to a MerchantTrace or RequestID that it has no knowledge of, then “Void successful” is replied.
A merchant implementing “Void” command requires a void repeat mechanism which only ends upon receiving a “Void successful” or “Void unsuccessful” response.


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

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


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


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

Result Code

Result Description

Action

1

Timeout

Transaction can be automatically retried a minute later

9

Unable to process

Transaction can be automatically retried a minute later

255

General Error (Exception)

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




A retry is relevant after the above responses because then one would expect a different result code. Nevertheless, a retry is supported after other result codes (eg Successful / Denied / Hot card / Black card) for when there is some change that could cause the transaction to be approved, or when the original reply is unknown to the merchant.
The following shows three different approaches to retries. A retry is only recommended in using the first approach, however all these approaches are supported.

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

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

The possible responses are:

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

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

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

Retry without Merchant Trace
It is not recommended to retry a transaction without a MerchantTrace.
Nevertheless, if the same Command, Amount, PAN, and MerchantReference as a previous transaction are specified (with no Merchant Trace given), then the possible responses are:

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

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

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

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

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


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


Duplicate transactions


Duplicate transactions

 
A problem of a duplicate transaction can occur if a merchant submits a previously successful transaction in a new request. A duplicate transaction of this nature is typically due to a user's unintentional mistake, e.g. pressing the “Submit” button twice, or submitting the same batch twice. It is responsibility of the merchant to ensure that a single transaction request is not submitted successfully more than once.
Nevertheless, the iVeri Gateway provides three mechanisms to protect against duplicate transactions. Specifying a unique MerchantTrace is a client-side configuration, while the latter to require contacting your local distributor.

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


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

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

Merchant Reference validity period

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


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

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


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


Specialized Techniques


Specialized Techniques

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

The Ping command checks that:

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

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

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

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

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


The Ping code of conduct:

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


Ping Flow


The following is a diagram showing how a Ping can be effectively used.
“S&F” refers to “Store and Forward”, otherwise known as an Offline transaction.


Mod-10 Checking
PANs are checked for validity using the Luhn check-digit algorithm (also known as “Mod-10 checking”). If the iVeri Gateway receives a transaction that fails Mod-10 checking, then “Invalid Card Number” (ResultCode 14) if returned.
A merchant may perform Mod-10 checking up front before sending the transaction to the iVeriGateway.

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

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


The following example uses the PAN of: 4287 9478

Step

Description

Example

1

Example account number

 4     2     8     7     9     4     7     (8)

2

Multiplier
Products

x2    x1    x2    x1    x2    x1    x2
 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


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

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

  • HotCard
  • BINLookup
  • BINManagement
  • BlackCard


Transaction Terminology


Transaction Terminology

 
An iVeri transaction is the combination of a transaction request (command: Authorisation, AuthorisationReversal, Debit, Credit, Void), and its corresponding response. A transaction sequence relates to the complete set of movement of goods and services and can include many related transactions.
An iVeri transaction involves communication between the following players:
Card Holder .>Merchant > iVeri Gateway > Acquirer > Association > Issuer

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

Player

Individual transaction identifier

Merchant

Merchant Trace

iVeri Gateway

RequestID

Acquirer

Acquirer Reference

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

 

Player

Transaction sequence identifier

Merchant

Merchant Reference

iVeri Gateway

Transaction Index


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

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

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

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

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


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


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

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

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


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

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


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


A reversal should not be confused with a Void


Payment Mechanisms: Pan Vs Track2 Vs Pin


Payment Mechanisms: Pan Vs Track2 Vs Pin

iVeri Gateway separates accounts into 3 different payment mechanisms:

  • PAN
  • Track2
  • PIN

To process a transaction with an account you need to know which payment mechanism you are going to use
Note that independent of the payment mechanism is used, the iVeri Gateway returns a dotted out “PAN” which can be used for display purposes.

PAN (also known as “Card Not Present” or “Keyed”)
The Primary Account Number (PAN) is given by the card holder to the merchant.
Either the card is not present with the Merchant, or the Merchant does not have a card reader to “swipe” the card.
The account can be any card that has the PAN embossed or printed on the card but does not require a PIN.
Mandatory Input Parameters: PAN, ExpiryDate.
Optional Input Parameters: StartDate, CardSecurityCode.

Track2 (also known as “Card Present” or “Swiped”)
A card reader is available to “swipe” the cardholder’s card and read the Track2 from it.
The account can be any card that has a Track2 on the magnetic strip but does not require a PIN.
Mandatory Input Parameter: Track2

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

The account is a card that requires a PIN (eg debit card) and a card reader is available to “swipe” the cardholder’s card and read the Track2 from it.
A PED (PIN entry device) is available to securely capture the cardholders PIN and encrypt it.
See “PIN based transactions” (section Error: Reference source not found) for more 
.


Mode: Test Vs Live


Mode: Test Vs Live

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

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

PAN

Result

4242424242424242

returns "Authorised"

2121212121212121

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

5454545454545454

randomly returns "Unable to process" or times out

All other card numbers
(eg "1111222233334444")

returns "Invalid card number"

For information on testing PIN based accounts, see “PIN based transactions”.
Merchants are requested not to abuse the test environment more than their realistic requirements.
A merchant abusing the Test environment may have their use of it suspended

Budget Period 

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

Field

Description

Length (bytes)

Format

SS

Start Sentinel

1

;

PAN

Primary Account Number

19 max

Digits

FS

Field Separator

1

=

DATE

Expiration Date (YYMM)

4

Digits

SVC CD

Service Code

3

Digits

Discretionary Data

Optional Issuer Data

variable

Digits

ES

End Sentinel

1

?

 

Total cannot exceed 39 bytes

39

 


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


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

SS

PAN

FS

DATE

SVC CD

Descretionary Data

ES

LRC


The e 1-byte Longitudinal Redundancy Check (LRC) should not be sent to the iVeriGateway.
The End Sentinel (ES) may need to be converted to? (0x3F)
 
Track2 Service Code values
The following tables can be used to determine the meaning of the 3-digit service code.
See section 17.6.4 for algorithm to determine if a card is PIN based or not. 
Note that a transaction may not decline or rejected solely because of the value of the service code.

Value Position#1

Description

MasterCard

Visa

1

International Card

Yes

Yes

2

International Card – Integrated Circuit Card

Yes

Yes

5

National Use Only

Yes

Yes

6

National Use Only – Integrated Circuit Card

Yes

Yes

7

Private Label or Proprietary Card

Yes

No

Value Position#2

Description

MasterCard

Visa

0

Normal Authorisation

Yes

Yes

2

Positive Online Authorisation Required

Yes

Yes


Value Position#3

Description

MasterCard

Visa

0

PIN Required

Yes

Yes

1

Normal Cardholder Verification, No Restrictions

Yes

Yes

2

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

Yes

No

3

ATM Only, PIN Required

Yes

Yes

5

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

Yes

No

6

Prompt for PIN if PIN Pad Present

Yes

Yes

7

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

Yes

No


Advanced Settings


Advanced Settings

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

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

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

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


Starting position

Length

Direction

MerchantReference

Derived ReconReference
(last 7 digits)

12

7

left-to-right

March01Rref10

0000010

12

7

right-to-left

100Rref01March

0000100

5

4

left-to-right

Rref1000March01

1000


Transaction Type repetition within transaction sequence

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


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


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


Transaction Result Codes


Transaction Result Codes

 

Result Status

Result Code

Result Description

Only relevant when

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)

 


 


PAYD


PAYD

 
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.

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

PayD Process

  • Customer selects payD as payment method for the transaction. (The payment selection process is provided by the merchant)
    • Customer enters their mobile number instead of their card details. (Card details are not present in the V_XML)
    • 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.
  • Transaction is sent to the gateway as a normal enterprise transaction.
  • The gateway identifies the transaction as a payD transaction and forwards the transaction to payD.
  • payD determines the registration status of the user. (See respective sections below on how the process changes)

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
  7. payD performs the user registration.
  8. ...continue as a registered user.


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

Voiding payD Transactions 

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.


POS Device Intergration


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 https://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.


PINBlock encryption via Triple DES DUKPT encryption


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

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 Numbe
The Test values are:
IKSN: FFFF0000030000000000
IPEK: 02B50748B58B7C4452E22E39DE560CE2


PINBlock encryption via Master/Session encryption


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.

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)

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 https://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


Track2 encryption via Master/Session encryption


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

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)


PAN encryption via Dukpt encryption


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:

  1. DeviceSerialNumber
  2. DeviceMake
  3. PANKeySerialNumber


EMV Transactions


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 can offer their customers the utmost in security. EMV chip technology prevents unauthorized access to card information and helps fight fraud.


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


Transaction Message Examples


Transaction Message Examples

 
The examples apply when using the web service interface to perform various transactions. The examples serve to showcase a set of parameters that are largely used when performing transactions using the schema definition available in the SOAP interface which are also commonly used on the REST API. The functionality and related parameter definitions, elements supported are standard in the SOAP schema and REST API


Further insights on the transaction types and their meanings, refer to the “Commands” and 
“Actions” sections and these have to be used in conjunction with the input parameters per actions. For the corresponding transaction flows per transactions type refer to transaction sequence


The examples cover the following messages:
The transaction Request and Response cover the following:
The Request message shows all the elements that are most used. The examples that follow will use the mandatory elements from this message necessary to perform the respective transaction covered in the example.
The response message is a typical response received from the web service to the various request messages.


Sale – “Debit with PAN”


Sale – “Debit with PAN”

 
This where the cardholder is debited, and merchant account is credited by the acquiring bank or PSP that holds the merchant agreement

 

REST

SOAP

Request

{

    "Version""2.0",

    "CertificateID""{5c4b9c74-0063-4240-9cff-f730675c5bd0}",

    "ProductType""Enterprise",

    "ProductVersion""WebAPI",

    "Direction""Request",

    "Transaction": {

        "ApplicationID""{d8d5a94-8fa0-428d-a539-3a5baf166f7f}",

        "Command""Debit",

        "Mode""TEST",

        "MerchantReference""20221108_1029",

        "MerchantTrace""DIAAAY4734",

        "Currency""ZAR"

        "Amount""3000",

        "ExpiryDate""1025",

        "PAN""4242424242424242"

 

    }

}

 

<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>false</validateRequest>

  <protocol>V_XML</protocol>

  <protocolVersion>7.0</protocolVersion>

  <request>

    &lt;V_XML Version="2.0" CertificateID="cf4b7e7a-4fec-43b4-a2cb-221263c0a34b" 

    ProductType="Enterprise" ProductVersion="iVeriWebService" Direction="Request"&gt;

    &lt;Transaction ApplicationID="7c523a4-7da7-4e59-b888-569fe65c535b" Command="Debit" Mode="Test"&gt;

    &lt;MerchantTrace&gt;2407E27568BEEE&lt;/MerchantTrace&gt;

    &lt;Amount&gt;2000&lt;/Amount&gt;

    &lt;Currency&gt;ZAR&lt;/Currency&gt;

    &lt;ExpiryDate&gt;042024&lt;/ExpiryDate&gt;

    &lt;MerchantReference&gt;20220104.0942&lt;/MerchantReference&gt;

    &lt;CardSecurityCode&gt;183&lt;/CardSecurityCode&gt;

    &lt;PAN&gt;4242424242424242&lt;/PAN&gt;

    &lt;/Transaction&gt;&lt;/V_XML&gt;

</request>

  </Execute>

  </soap:Body>

  </soap:Envelope>

Response

{

    "Version""2.0",

    "Direction""Response",

    "Transaction": {

        "MerchantTrace""DIAAAY4734",

        "Amount""3000",

        "AuthorisationCode""543305",

        "CCNumber""4242........4242",

        "Currency""ZAR",

        "ExpiryDate""102025",

        "MerchantReference""20221108_1029",

        "Terminal""Default",

        "TransactionIndex""{7C256903-9097-41AE-81B6-54681B33301F}",

        "MerchantName""iVeri Payment Technology",

        "MerchantUSN""7771777",

        "Acquirer""NBPostilionNBSouthAfrica",

        "AcquirerReference""95702:04641684",

        "AcquirerDate""20221229",

        "AcquirerTime""102825",

        "DisplayAmount""R 30.00",

        "BIN""4",

        "Association""VISA",

        "CardType""Unknown CardType",

        "Issuer""Unknown Issuer",

        "Jurisdiction""International",

        "PAN""4242........4242",

        "PANMode""Keyed",

        "ReconReference""04641684",

        "CardHolderPresence""CardNotPresent",

        "MerchantAddress""MERCHANT ADDRESS",

        "MerchantCity""Sandton",

        "MerchantCountryCode""ZA",

        "MerchantCountry""South Africa",

        "DistributorName""Nedbank",

        "ApplicationID""{D8D5A94-8FA0-428D-A539-3A5BAF166F7F}",

        "Command""Debit",

        "Mode""Test",

        "RequestID""{B6308E50-4337-4DFE-A0DC-A4B3C4732139}",

        "Result": {

            "Status""0",

            "Code""0",

            "Description""",

            "AppServer""105IVERIAPPPR2N",

            "DBServer""105iveridbpr01n",

            "Gateway""Nedbank",

            "AcquirerCode""00",

            "AcquirerDescription"""

        }

    }

}

 

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

<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <soap:Body>

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

            <ExecuteResult>&lt;V_XML Version="2.0" Direction="Response"&gt;  &lt;Transaction ApplicationID="{7C523A4-7DA7-4E59-B888-569FE65C535B}" Command="Debit" Mode="Test" RequestID="{E01B8439-05B0-4B68-A22F-903D8CB5CC67}"&gt;

    &lt;Result Status="0" Code="0" Description="" AppServer="105IVERIAPPPR1N" DBServer="105iveridbpr01n" Gateway="Nedbank" AcquirerCode="00" AcquirerDescription="" /&gt;

    &lt;MerchantTrace&gt;2407E27568BEEE&lt;/MerchantTrace&gt;

    &lt;Amount&gt;2000&lt;/Amount&gt;

    &lt;AuthorisationCode&gt;540565&lt;/AuthorisationCode&gt;

    &lt;CCNumber&gt;4242........4242&lt;/CCNumber&gt;

    &lt;Currency&gt;ZAR&lt;/Currency&gt;

    &lt;ExpiryDate&gt;042024&lt;/ExpiryDate&gt;

    &lt;MerchantReference&gt;20220104.0942&lt;/MerchantReference&gt;

    &lt;Terminal&gt;Default&lt;/Terminal&gt;

    &lt;TransactionIndex&gt;{F20B545A-B2CC-40E9-8C9B-40030AC50B31}&lt;/TransactionIndex&gt;

    &lt;MerchantName&gt;iVeri Payment Technology&lt;/MerchantName&gt;

    &lt;MerchantUSN&gt;7771777&lt;/MerchantUSN&gt;

    &lt;Acquirer&gt;NBPostilionNBSouthAfrica&lt;/Acquirer&gt;

    &lt;AcquirerReference&gt;95702:04641678&lt;/AcquirerReference&gt;

    &lt;AcquirerDate&gt;20221229&lt;/AcquirerDate&gt;

    &lt;AcquirerTime&gt;094245&lt;/AcquirerTime&gt;

    &lt;DisplayAmount&gt;R 20.00&lt;/DisplayAmount&gt;

    &lt;BIN&gt;4&lt;/BIN&gt;

    &lt;Association&gt;VISA&lt;/Association&gt;

    &lt;CardType&gt;Unknown CardType&lt;/CardType&gt;

    &lt;Issuer&gt;Unknown Issuer&lt;/Issuer&gt;

    &lt;Jurisdiction&gt;International&lt;/Jurisdiction&gt;

    &lt;PAN&gt;4242........4242&lt;/PAN&gt;

    &lt;PANMode&gt;Keyed&lt;/PANMode&gt;

    &lt;ReconReference&gt;04641678&lt;/ReconReference&gt;

    &lt;CardHolderPresence&gt;CardNotPresent&lt;/CardHolderPresence&gt;

    &lt;MerchantAddress&gt;MERCHANT ADDRESS&lt;/MerchantAddress&gt;

    &lt;MerchantCity&gt;Sandton&lt;/MerchantCity&gt;

    &lt;MerchantCountryCode&gt;ZA&lt;/MerchantCountryCode&gt;

    &lt;MerchantCountry&gt;South Africa&lt;/MerchantCountry&gt;

    &lt;DistributorName&gt;Nedbank&lt;/DistributorName&gt;

  &lt;/Transaction&gt;

&lt;/V_XML&gt;</ExecuteResult>

        </ExecuteResponse>

    </soap:Body>

</soap:Envelope>

 


Pre-Auth Completion – Follow-up Debit


Pre-Auth Completion – Follow-up Debit

 
Allows the merchant to instruct the cardholders bank to release and debit the funds previously reserved or pre-authorized

REST 

SOAP 

Request 

{ 

    "Version": "2.0", 

    "CertificateID": "{5c4b9c74-0063-4240-9cff-f730675c5bd0}", 

    "ProductType": "Enterprise", 

    "ProductVersion": "WebAPI", 

    "Direction": "Request", 

    "Transaction": { 

        "ApplicationID": "{d8d5a94-8fa0-428d-a539-3a5baf166f7f}", 

        "Command": "Debit", 

        "Mode": "Test", 

        "Amount": "1000", 

        "MerchantTrace":"20220812_1044", 

        "TransactionIndex": "{5C8F61BE-15AD-4201-B361-66AD52D2EFAE}" 

         

 

    } 

} 

 

<soap:Envelopexmlns: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> 

  <Executexmlns="http://iveri.com/"> 

  <validateRequest>false</validateRequest> 

  <protocol>V_XML</protocol> 

  <protocolVersion>7.0</protocolVersion> 

  <request>&lt;V_XML Version="2.0" CertificateID="cf4b7e7a-4fec-43b4-a2cb-221263c0a34b" 

   ProductType="Enterprise" ProductVersion="iVeriWebService" Direction="Request"&gt; 

&lt;Transaction ApplicationID="7c523a4-7da7-4e59-b888-569fe65c535b" Command="Debit" Mode="Test"&gt; 

&lt;MerchantTrace&gt;9AE405C07E7)7568BEEE&lt;/MerchantTrace&gt; 

&lt;Amount&gt;1000&lt;/Amount&gt; 

&lt;MerchantReference&gt;20220104.1057&lt;/MerchantReference&gt; 

&lt;TransactionIndex&gt;{1D638328-7A15-4937-9818-C3F9C9B96E52}&lt;/TransactionIndex&gt; 

&lt;/Transaction&gt; 

&lt;/V_XML&gt; 

</request> 

  </Execute> 

  </soap:Body> 

  </soap:Envelope> 

 

                                                               Response 

{ 

    "Version": "2.0", 

    "CertificateID": "{5c4b9c74-0063-4240-9cff-f730675c5bd0}", 

    "ProductType": "Enterprise", 

    "ProductVersion": "WebAPI", 

    "Direction": "Request", 

    "Transaction": { 

        "ApplicationID": "{d8d5a94-8fa0-428d-a539-3a5baf166f7f}", 

        "Command": "Debit", 

        "Mode": "Test", 

        "Amount": "1000", 

        "MerchantTrace":"20220812_1044", 

        "TransactionIndex": "{5C8F61BE-15AD-4201-B361-66AD52D2EFAE}" 

         

 

    } 

} 

 

<?xmlversion="1.0"encoding="utf-8"?> 

<soap:Envelopexmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 

    <soap:Body> 

        <ExecuteResponsexmlns="http://iveri.com/"> 

            <ExecuteResult>&lt;V_XML Version="2.0" Direction="Response"&gt; 

  &lt;Transaction ApplicationID="{7C523A4-7DA7-4E59-B888-569FE65C535B}" Command="Debit" Mode="Test" RequestID="{7549E81F-016B-4A83-B136-CEAF6A7A093A}"&gt; 

    &lt;Result Status="0" Code="0" Description="" AppServer="105IVERIAPPPR1N" DBServer="105iveridbpr01n" Gateway="Nedbank" AcquirerCode="00" AcquirerDescription="" /&gt; 

    &lt;MerchantTrace&gt;9AE405C07E7)7568BEEE&lt;/MerchantTrace&gt; 

    &lt;Amount&gt;1000&lt;/Amount&gt; 

    &lt;AuthorisationCode&gt;545108&lt;/AuthorisationCode&gt; 

    &lt;CCNumber&gt;4242........4242&lt;/CCNumber&gt; 

    &lt;Currency&gt;ZAR&lt;/Currency&gt; 

    &lt;ExpiryDate&gt;042024&lt;/ExpiryDate&gt; 

    &lt;MerchantReference&gt;20220104.1057&lt;/MerchantReference&gt; 

    &lt;Terminal&gt;Default&lt;/Terminal&gt; 

    &lt;TransactionIndex&gt;{1D638328-7A15-4937-9818-C3F9C9B96E52}&lt;/TransactionIndex&gt; 

    &lt;MerchantName&gt;iVeri Payment Technology&lt;/MerchantName&gt; 

    &lt;MerchantUSN&gt;7771777&lt;/MerchantUSN&gt; 

    &lt;Acquirer&gt;NBPostilionNBSouthAfrica&lt;/Acquirer&gt; 

    &lt;AcquirerReference&gt;95702:04641686&lt;/AcquirerReference&gt; 

    &lt;AcquirerDate&gt;20221229&lt;/AcquirerDate&gt; 

    &lt;AcquirerTime&gt;105828&lt;/AcquirerTime&gt; 

    &lt;DisplayAmount&gt;R 10.00&lt;/DisplayAmount&gt; 

    &lt;BIN&gt;4&lt;/BIN&gt; 

    &lt;Association&gt;VISA&lt;/Association&gt; 

    &lt;CardType&gt;Unknown CardType&lt;/CardType&gt; 

    &lt;Issuer&gt;Unknown Issuer&lt;/Issuer&gt; 

    &lt;Jurisdiction&gt;International&lt;/Jurisdiction&gt; 

    &lt;PAN&gt;4242........4242&lt;/PAN&gt; 

    &lt;PANMode&gt;Keyed&lt;/PANMode&gt; 

    &lt;ReconReference&gt;04641686&lt;/ReconReference&gt; 

    &lt;CardHolderPresence&gt;CardNotPresent&lt;/CardHolderPresence&gt; 

    &lt;MerchantAddress&gt;MERCHANT ADDRESS&lt;/MerchantAddress&gt; 

    &lt;MerchantCity&gt;Sandton&lt;/MerchantCity&gt; 

    &lt;MerchantCountryCode&gt;ZA&lt;/MerchantCountryCode&gt; 

    &lt;MerchantCountry&gt;South Africa&lt;/MerchantCountry&gt; 

    &lt;DistributorName&gt;Nedbank&lt;/DistributorName&gt; 

  &lt;/Transaction&gt; 

&lt;/V_XML&gt;</ExecuteResult> 

        </ExecuteResponse> 

    </soap:Body> 

</soap:Envelope> 

 



Pre-Auth Reversal – “Authorisation Reversal”


Pre-Auth Reversal – “Authorisation Reversal”

 
Allows merchants to submit an instruction to cancel/reverse a pre-authorized amount on the cardholder’s card

 

REST  

SOAP 

Request 

{ 

    "Version": "2.0", 

    "CertificateID": "{5c4b9c74-0063-4240-9cff-f730675c5bd0}", 

    "ProductType": "Enterprise", 

    "ProductVersion": "WebAPI", 

    "Direction": "Request", 

    "Transaction": { 

        "ApplicationID": "{8d5a94-8fa0-428d-a539-3a5baf166f7f}", 

        "Command": "AuthorisationReversal", 

        "Mode": "Test", 

        "TransactionIndex": "{34799783-6A61-4EFB-8E1C-DA3D73C27F05}" 

         

 

    } 

} 

 

<soap:Envelopexmlns: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> 

  <Executexmlns="http://iveri.com/"> 

  <validateRequest>false</validateRequest> 

  <protocol>V_XML</protocol> 

  <protocolVersion>7.0</protocolVersion> 

  <request> 

    &lt;V_XML Version="2.0" CertificateID="cf4b7e7a-4fec-43b4-a2cb-221263c0a34b"  

    ProductType="Enterprise" ProductVersion="iVeriWebService" Direction="Request"&gt; 

    &lt;Transaction ApplicationID="7c523a4-7da7-4e59-b888-569fe65c535b" Command="AuthorisationReversal" Mode="Test"&gt; 

    &lt;TransactionIndex&gt;{258A91D9-2B0B-4445-ADB2-E5DF210E9054}&lt;/TransactionIndex&gt; 

    &lt;/Transaction&gt;&lt;/V_XML&gt; 

</request> 

  </Execute> 

  </soap:Body> 

  </soap:Envelope> 

 

Response 

{ 

    "Version": "2.0", 

    "Direction": "Response", 

    "Transaction": { 

        "Amount": "3000", 

        "AuthorisationCode": "551260", 

        "CCNumber": "4242........4242", 

        "Currency": "ZAR", 

        "ExpiryDate": "102025", 

        "MerchantReference": "20221108_1242", 

        "Terminal": "Default", 

        "TransactionIndex": "{34799783-6A61-4EFB-8E1C-DA3D73C27F05}", 

        "MerchantName": "iVeri Payment Technology", 

        "MerchantUSN": "7771777", 

        "Acquirer": "NBPostilionNBSouthAfrica", 

        "AcquirerReference": "95702:04641695", 

        "AcquirerDate": "20221229", 

        "AcquirerTime": "124130", 

        "DisplayAmount": "R 30.00", 

        "BIN": "4", 

        "Association": "VISA", 

        "CardType": "Unknown CardType", 

        "Issuer": "Unknown Issuer", 

        "Jurisdiction": "International", 

        "PAN": "4242........4242", 

        "PANMode": "Keyed", 

        "ReconReference": "04641695", 

        "CardHolderPresence": "CardNotPresent", 

        "MerchantAddress": "MERCHANT ADDRESS", 

        "MerchantCity": "Sandton", 

        "MerchantCountryCode": "ZA", 

        "MerchantCountry": "South Africa", 

        "DistributorName": "Nedbank", 

        "ApplicationID": "{8D5A94-8FA0-428D-A539-3A5BAF166F7F}", 

        "Command": "AuthorisationReversal", 

        "Mode": "Test", 

        "RequestID": "{2D4A81AB-2214-4983-A9EA-933AF9E04612}", 

        "Result": { 

            "Status": "0", 

            "Code": "0", 

            "Description": "", 

            "AppServer": "105IVERIAPPPR1N", 

            "DBServer": "105iveridbpr01n", 

            "Gateway": "Nedbank", 

            "AcquirerCode": "00", 

            "AcquirerDescription": "" 

        } 

    } 

} 

 

<?xmlversion="1.0"encoding="utf-8"?> 

<soap:Envelopexmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 

    <soap:Body> 

        <ExecuteResponsexmlns="http://iveri.com/"> 

            <ExecuteResult>&lt;V_XML Version="2.0" Direction="Response"&gt; 

  &lt;Transaction ApplicationID="{7C523A4-7DA7-4E59-B888-569FE65C535B}" Command="AuthorisationReversal" Mode="Test" RequestID="{6ED66FD3-6F77-48A4-9CF7-80CB8E8DE50F}"&gt; 

    &lt;Result Status="0" Code="0" Description="" AppServer="105IVERIAPPPR2N" DBServer="105iveridbpr01n" Gateway="Nedbank" AcquirerCode="00" AcquirerDescription="" /&gt; 

    &lt;Amount&gt;1000&lt;/Amount&gt; 

    &lt;AuthorisationCode&gt;551388&lt;/AuthorisationCode&gt; 

    &lt;CCNumber&gt;4242........4242&lt;/CCNumber&gt; 

    &lt;Currency&gt;ZAR&lt;/Currency&gt; 

    &lt;ExpiryDate&gt;042024&lt;/ExpiryDate&gt; 

    &lt;MerchantReference&gt;20220104.1251&lt;/MerchantReference&gt; 

    &lt;Terminal&gt;Default&lt;/Terminal&gt; 

    &lt;TransactionIndex&gt;{258A91D9-2B0B-4445-ADB2-E5DF210E9054}&lt;/TransactionIndex&gt; 

    &lt;MerchantName&gt;iVeri Payment Technology&lt;/MerchantName&gt; 

    &lt;MerchantUSN&gt;7771777&lt;/MerchantUSN&gt; 

    &lt;Acquirer&gt;NBPostilionNBSouthAfrica&lt;/Acquirer&gt; 

    &lt;AcquirerReference&gt;95702:04641696&lt;/AcquirerReference&gt; 

    &lt;AcquirerDate&gt;20221229&lt;/AcquirerDate&gt; 

    &lt;AcquirerTime&gt;125040&lt;/AcquirerTime&gt; 

    &lt;DisplayAmount&gt;R 10.00&lt;/DisplayAmount&gt; 

    &lt;BIN&gt;4&lt;/BIN&gt; 

    &lt;Association&gt;VISA&lt;/Association&gt; 

    &lt;CardType&gt;Unknown CardType&lt;/CardType&gt; 

    &lt;Issuer&gt;Unknown Issuer&lt;/Issuer&gt; 

    &lt;Jurisdiction&gt;International&lt;/Jurisdiction&gt; 

    &lt;PAN&gt;4242........4242&lt;/PAN&gt; 

    &lt;PANMode&gt;Keyed&lt;/PANMode&gt; 

    &lt;ReconReference&gt;04641696&lt;/ReconReference&gt; 

    &lt;CardHolderPresence&gt;CardNotPresent&lt;/CardHolderPresence&gt; 

    &lt;MerchantAddress&gt;MERCHANT ADDRESS&lt;/MerchantAddress&gt; 

    &lt;MerchantCity&gt;Sandton&lt;/MerchantCity&gt; 

    &lt;MerchantCountryCode&gt;ZA&lt;/MerchantCountryCode&gt; 

    &lt;MerchantCountry&gt;South Africa&lt;/MerchantCountry&gt; 

    &lt;DistributorName&gt;Nedbank&lt;/DistributorName&gt; 

  &lt;/Transaction&gt; 

&lt;/V_XML&gt;</ExecuteResult> 

        </ExecuteResponse> 

    </soap:Body> 

</soap:Envelope> 

 



Refund – “Follow-Credit”


Refund – “Follow-Credit”

 
Allows for a previously debited amount to be returned to the cardholders account using a detail of a previously processed transaction.

 

REST 

SOAP 

Request 

{ 

    "Version": "2.0", 

    "CertificateID": "{5c4b9c74-0063-4240-9cff-f730675c5bd0}", 

    "ProductType": "Enterprise", 

    "ProductVersion": "WebAPI", 

    "Direction": "Request", 

    "Transaction": { 

        "ApplicationID": "{d8d5a94-8fa0-428d-a539-3a5baf166f7f}", 

        "Command": "Credit", 

        "Mode": "Test", 

        "Amount": "1000", 

        "MerchantTrace":"20220812_1107", 

        "MerchantReference": "20221123_1106", 

        "TransactionIndex": "{CB7A9E38-4797-4513-85EE-AFE63C957ED3}" 

         

 

    } 

} 

 

<soap:Envelopexmlns: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> 

  <Executexmlns="http://iveri.com/"> 

  <validateRequest>false</validateRequest> 

  <protocol>V_XML</protocol> 

  <protocolVersion>7.0</protocolVersion> 

  <request>&lt;V_XML Version="2.0" CertificateID="cf4b7e7a-4fec-43b4-a2cb-221263c0a34b" ProductType="Enterprise" 

ProductVersion="iVeriWebService" Direction="Request"&gt; 

&lt;Transaction ApplicationID="7c523a4-7da7-4e59-b888-569fe65c535b" Command="Credit" Mode="Test"&gt; 

&lt;MerchantTrace&gt;9AE405C07E7227568BEEE&lt;/MerchantTrace&gt; 

&lt;Amount&gt;2000&lt;/Amount&gt; 

&lt;MerchantReference&gt;20220104.0942&lt;/MerchantReference&gt; 

&lt;TransactionIndex&gt;{F20B545A-B2CC-40E9-8C9B-40030AC50B31}&lt;/TransactionIndex&gt; 

&lt;/Transaction&gt; 

&lt;/V_XML&gt; 

</request> 

  </Execute> 

  </soap:Body> 

  </soap:Envelope> 

 

Response 

{ 

    "Version": "2.0", 

    "Direction": "Response", 

    "Transaction": { 

        "MerchantTrace": "20220812_1107", 

        "Amount": "1000", 

        "AuthorisationCode": "545684", 

        "CCNumber": "4242........4242", 

        "Currency": "ZAR", 

        "ExpiryDate": "102025", 

        "MerchantReference": "20221123_1106", 

        "Terminal": "Default", 

        "TransactionIndex": "{CB7A9E38-4797-4513-85EE-AFE63C957ED3}", 

        "MerchantName": "iVeri Payment Technology", 

        "MerchantUSN": "7771777", 

        "Acquirer": "NBPostilionNBSouthAfrica", 

        "AcquirerReference": "95702:04641688", 

        "AcquirerDate": "20221229", 

        "AcquirerTime": "110804", 

        "DisplayAmount": "R 10.00", 

        "BIN": "4", 

        "Association": "VISA", 

        "CardType": "Unknown CardType", 

        "Issuer": "Unknown Issuer", 

        "Jurisdiction": "International", 

        "PAN": "4242........4242", 

        "PANMode": "", 

        "ReconReference": "04641688", 

        "CardHolderPresence": "CardNotPresent", 

        "MerchantAddress": "MERCHANT ADDRESS", 

        "MerchantCity": "Sandton", 

        "MerchantCountryCode": "ZA", 

        "MerchantCountry": "South Africa", 

        "DistributorName": "Nedbank", 

        "ApplicationID": "{D8D5A94-8FA0-428D-A539-3A5BAF166F7F}", 

        "Command": "Credit", 

        "Mode": "Test", 

        "RequestID": "{A8BCFF58-C35B-40ED-8F5D-01FFFA14FD19}", 

        "Result": { 

            "Status": "0", 

            "Code": "0", 

            "Description": "", 

            "AppServer": "105IVERIAPPPR2N", 

            "DBServer": "105iveridbpr01n", 

            "Gateway": "Nedbank", 

            "AcquirerCode": "00", 

            "AcquirerDescription": "" 

        } 

    } 

} 

 

<?xmlversion="1.0"encoding="utf-8"?> 

<soap:Envelopexmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 

    <soap:Body> 

        <ExecuteResponsexmlns="http://iveri.com/"> 

            <ExecuteResult>&lt;V_XML Version="2.0" Direction="Response"&gt; 

  &lt;Transaction ApplicationID="{7C523A4-7DA7-4E59-B888-569FE65C535B}" Command="Credit" Mode="Test" RequestID="{1EDD5EF7-D27C-4D68-95FA-7627E42AFE6E}"&gt; 

    &lt;Result Status="0" Code="0" Description="" AppServer="105IVERIAPPPR2N" DBServer="105iveridbpr01n" Gateway="Nedbank" AcquirerCode="00" AcquirerDescription="" /&gt; 

    &lt;MerchantTrace&gt;9AE405C07E7227568BEEE&lt;/MerchantTrace&gt; 

    &lt;Amount&gt;2000&lt;/Amount&gt; 

    &lt;AuthorisationCode&gt;541742&lt;/AuthorisationCode&gt; 

    &lt;CCNumber&gt;4242........4242&lt;/CCNumber&gt; 

    &lt;Currency&gt;ZAR&lt;/Currency&gt; 

    &lt;ExpiryDate&gt;042024&lt;/ExpiryDate&gt; 

    &lt;MerchantReference&gt;20220104.0942&lt;/MerchantReference&gt; 

    &lt;Terminal&gt;Default&lt;/Terminal&gt; 

    &lt;TransactionIndex&gt;{F20B545A-B2CC-40E9-8C9B-40030AC50B31}&lt;/TransactionIndex&gt; 

    &lt;MerchantName&gt;iVeri Payment Technology&lt;/MerchantName&gt; 

    &lt;MerchantUSN&gt;7771777&lt;/MerchantUSN&gt; 

    &lt;Acquirer&gt;NBPostilionNBSouthAfrica&lt;/Acquirer&gt; 

    &lt;AcquirerReference&gt;95702:04641681&lt;/AcquirerReference&gt; 

    &lt;AcquirerDate&gt;20221229&lt;/AcquirerDate&gt; 

    &lt;AcquirerTime&gt;100222&lt;/AcquirerTime&gt; 

    &lt;DisplayAmount&gt;R 20.00&lt;/DisplayAmount&gt; 

    &lt;BIN&gt;4&lt;/BIN&gt; 

    &lt;Association&gt;VISA&lt;/Association&gt; 

    &lt;CardType&gt;Unknown CardType&lt;/CardType&gt; 

    &lt;Issuer&gt;Unknown Issuer&lt;/Issuer&gt; 

    &lt;Jurisdiction&gt;International&lt;/Jurisdiction&gt; 

    &lt;PAN&gt;4242........4242&lt;/PAN&gt; 

    &lt;PANMode /&gt; 

    &lt;ReconReference&gt;04641681&lt;/ReconReference&gt; 

    &lt;CardHolderPresence&gt;CardNotPresent&lt;/CardHolderPresence&gt; 

    &lt;MerchantAddress&gt;MERCHANT ADDRESS&lt;/MerchantAddress&gt; 

    &lt;MerchantCity&gt;Sandton&lt;/MerchantCity&gt; 

    &lt;MerchantCountryCode&gt;ZA&lt;/MerchantCountryCode&gt; 

    &lt;MerchantCountry&gt;South Africa&lt;/MerchantCountry&gt; 

    &lt;DistributorName&gt;Nedbank&lt;/DistributorName&gt; 

  &lt;/Transaction&gt; 

&lt;/V_XML&gt;</ExecuteResult> 

        </ExecuteResponse> 

    </soap:Body> 

</soap:Envelope> 

 



Refund – “Initial Credit”


Refund – “Initial Credit”

 
Allows the merchants to essentially “pay” or “credit” the cardholder without referencing any original or previously processed transaction

 

REST 

SOAP 

Request 

{ 

    "Version": "2.0", 

    "CertificateID": "{cf4b7e7a-4fec-43b4-a2cb-221263c0a34b}", 

    "ProductType": "Enterprise", 

    "ProductVersion": "WebAPI", 

    "Direction": "Request", 

    "Transaction": { 

        "ApplicationID": "e7c523a4-7da7-4e59-b888-569fe65c535b", 

        "Command": "Credit", 

        "Mode": "TEST", 

        "MerchantReference": "20211014_0129", 

        "MerchantTrace": "NAHSI-1112", 

        "Currency": "ZAR",  

        "Amount": "1000", 

        "ExpiryDate": "1025", 

        "PAN": "4242424242424242" 

 

    } 

} 

 

<soap:Envelopexmlns: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> 

  <Executexmlns="http://iveri.com/"> 

  <validateRequest>false</validateRequest> 

  <protocol>V_XML</protocol> 

  <protocolVersion>7.0</protocolVersion> 

  <request> 

    &lt;V_XML Version="2.0" CertificateID="cf4b7e7a-4fec-43b4-a2cb-221263c0a34b"  

    ProductType="Enterprise" ProductVersion="iVeriWebService" Direction="Request"&gt; 

    &lt;Transaction ApplicationID="e7c523a4-7da7-4e59-b888-569fe65c535b" Command="Credit" Mode="Test"&gt; 

    &lt;MerchantTrace&gt;2407E295EEE&lt;/MerchantTrace&gt; 

    &lt;Amount&gt;1000&lt;/Amount&gt; 

    &lt;Currency&gt;ZAR&lt;/Currency&gt; 

    &lt;ExpiryDate&gt;042024&lt;/ExpiryDate&gt; 

    &lt;MerchantReference&gt;20220104.1213&lt;/MerchantReference&gt; 

    &lt;CardSecurityCode&gt;183&lt;/CardSecurityCode&gt; 

    &lt;PAN&gt;4242424242424242&lt;/PAN&gt; 

    &lt;/Transaction&gt;&lt;/V_XML&gt; 

</request> 

  </Execute> 

  </soap:Body> 

  </soap:Envelope> 

Response 

{ 

    "Version": "2.0", 

    "Direction": "Response", 

    "Transaction": { 

        "MerchantTrace": "NAHSI-1112", 

        "Amount": "1000", 

        "AuthorisationCode": "550310", 

        "CCNumber": "4242........4242", 

        "Currency": "ZAR", 

        "ExpiryDate": "102025", 

        "MerchantReference": "20211014_0129", 

        "Terminal": "Default", 

        "TransactionIndex": "{B1BF566A-23FE-43A4-A5A0-DBF648C1D94F}", 

        "MerchantName": "iVeri Payment Technology", 

        "MerchantUSN": "7771777", 

        "Acquirer": "NBPostilionNBSouthAfrica", 

        "AcquirerReference": "95702:04641691", 

        "AcquirerDate": "20221229", 

        "AcquirerTime": "122510", 

        "DisplayAmount": "R 10.00", 

        "BIN": "4", 

        "Association": "VISA", 

        "CardType": "Unknown CardType", 

        "Issuer": "Unknown Issuer", 

        "Jurisdiction": "International", 

        "PAN": "4242........4242", 

        "PANMode": "Keyed", 

        "ReconReference": "04641691", 

        "CardHolderPresence": "CardNotPresent", 

        "MerchantAddress": "MERCHANT ADDRESS", 

        "MerchantCity": "Sandton", 

        "MerchantCountryCode": "ZA", 

        "MerchantCountry": "South Africa", 

        "DistributorName": "Nedbank", 

        "ApplicationID": "{E7C523A4-7DA7-4E59-B888-569FE65C535B}", 

        "Command": "Credit", 

        "Mode": "Test", 

        "RequestID": "{61F85F10-5E7B-40C8-A18C-DD1EE595665D}", 

        "Result": { 

            "Status": "0", 

            "Code": "0", 

            "Description": "", 

            "AppServer": "105IVERIAPPPR1N", 

            "DBServer": "105iveridbpr01n", 

            "Gateway": "Nedbank", 

            "AcquirerCode": "00", 

            "AcquirerDescription": "" 

        } 

    } 

} 

 

<?xmlversion="1.0"encoding="utf-8"?> 

<soap:Envelopexmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 

    <soap:Body> 

        <ExecuteResponsexmlns="http://iveri.com/"> 

            <ExecuteResult>&lt;V_XML Version="2.0" Direction="Response"&gt;  &lt;Transaction ApplicationID="{E7C523A4-7DA7-4E59-B888-569FE65C535B}" Command="Credit" Mode="Test" RequestID="{69F6E0B8-BDA0-4586-8185-815F95A15FE4}"&gt; 

    &lt;Result Status="0" Code="0" Description="" AppServer="105IVERIAPPPR2N" DBServer="105iveridbpr01n" Gateway="Nedbank" AcquirerCode="00" AcquirerDescription="" /&gt; 

    &lt;MerchantTrace&gt;2407E295EEE&lt;/MerchantTrace&gt; 

    &lt;Amount&gt;1000&lt;/Amount&gt; 

    &lt;AuthorisationCode&gt;550367&lt;/AuthorisationCode&gt; 

    &lt;CCNumber&gt;4242........4242&lt;/CCNumber&gt; 

    &lt;Currency&gt;ZAR&lt;/Currency&gt; 

    &lt;ExpiryDate&gt;042024&lt;/ExpiryDate&gt; 

    &lt;MerchantReference&gt;20220104.1213&lt;/MerchantReference&gt; 

    &lt;Terminal&gt;Default&lt;/Terminal&gt; 

    &lt;TransactionIndex&gt;{89CCE679-E1B1-497C-8684-C6080EB61B00}&lt;/TransactionIndex&gt; 

    &lt;MerchantName&gt;iVeri Payment Technology&lt;/MerchantName&gt; 

    &lt;MerchantUSN&gt;7771777&lt;/MerchantUSN&gt; 

    &lt;Acquirer&gt;NBPostilionNBSouthAfrica&lt;/Acquirer&gt; 

    &lt;AcquirerReference&gt;95702:04641692&lt;/AcquirerReference&gt; 

    &lt;AcquirerDate&gt;20221229&lt;/AcquirerDate&gt; 

    &lt;AcquirerTime&gt;122607&lt;/AcquirerTime&gt; 

    &lt;DisplayAmount&gt;R 10.00&lt;/DisplayAmount&gt; 

    &lt;BIN&gt;4&lt;/BIN&gt; 

    &lt;Association&gt;VISA&lt;/Association&gt; 

    &lt;CardType&gt;Unknown CardType&lt;/CardType&gt; 

    &lt;Issuer&gt;Unknown Issuer&lt;/Issuer&gt; 

    &lt;Jurisdiction&gt;International&lt;/Jurisdiction&gt; 

    &lt;PAN&gt;4242........4242&lt;/PAN&gt; 

    &lt;PANMode&gt;Keyed&lt;/PANMode&gt; 

    &lt;ReconReference&gt;04641692&lt;/ReconReference&gt; 

    &lt;CardHolderPresence&gt;CardNotPresent&lt;/CardHolderPresence&gt; 

    &lt;MerchantAddress&gt;MERCHANT ADDRESS&lt;/MerchantAddress&gt; 

    &lt;MerchantCity&gt;Sandton&lt;/MerchantCity&gt; 

    &lt;MerchantCountryCode&gt;ZA&lt;/MerchantCountryCode&gt; 

    &lt;MerchantCountry&gt;South Africa&lt;/MerchantCountry&gt; 

    &lt;DistributorName&gt;Nedbank&lt;/DistributorName&gt; 

  &lt;/Transaction&gt; 

&lt;/V_XML&gt;</ExecuteResult> 

        </ExecuteResponse> 

    </soap:Body> 

</soap:Envelope> 

 



Void


Void

 
Void should be performed on an event where transactions are not responded to or not completed to the merchant’s application which could be due to a timeout scenario. When used the void message should be performed closer to the time it relates. For more on the use of Void messages, refer to the Ensuring end to end Transaction Integrity 

 

REST 

SOAP 

Request 

{ 

    "Version": "2.0", 

    "CertificateID": "{5c4b9c74-0063-4240-9cff-f730675c5bd0}", 

    "ProductType": "Enterprise", 

    "ProductVersion": "WebAPI", 

    "Direction": "Request", 

    "Transaction": { 

        "ApplicationID": "{d8d5a94-8fa0-428d-a539-3a5baf166f7f}", 

        "Command": "Void", 

        "Mode": "Test", 

        "OriginalMerchantTrace": "DIAAAY22734", 

        "OriginalRequestID": "{9667792F-635A-4121-AC85-E06856ADC3EF}" 

 

    } 

} 

 

<soap:Envelopexmlns: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> 

  <Executexmlns="http://iveri.com/"> 

  <validateRequest>false</validateRequest> 

  <protocol>V_XML</protocol> 

  <protocolVersion>7.0</protocolVersion> 

  <request> 

    &lt;V_XML Version="2.0" CertificateID="cf4b7e7a-4fec-43b4-a2cb-221263c0a34b"  

    ProductType="Enterprise" ProductVersion="iVeriWebService" Direction="Request"&gt; 

    &lt;Transaction ApplicationID="7c523a4-7da7-4e59-b888-569fe65c535b" Command="Void" Mode="Test"&gt; 

    &lt;MerchantTrace&gt;240X568BEEE&lt;/MerchantTrace&gt; 

    &lt;OriginalRequestID&gt;{B3C46039-5B4D-402A-82A7-A37BC0161167}&lt;/OriginalRequestID&gt; 

    &lt;/Transaction&gt;&lt;/V_XML&gt; 

</request> 

  </Execute> 

  </soap:Body> 

  </soap:Envelope> 

 

Response 

 

{ 

    "Version": "2.0", 

    "Direction": "Response", 

    "Transaction": { 

        "OriginalMerchantTrace": "DIAAAY22734", 

        "OriginalRequestID": "{9667792F-635A-4121-AC85-E06856ADC3EF}", 

        "ApplicationID": "{D8D5A94-8FA0-428D-A539-3A5BAF166F7F}", 

        "Command": "Void", 

        "Mode": "Test", 

        "RequestID": "{F096A71F-75D0-4F0C-A150-0AF181A86445}", 

        "Result": { 

            "Status": "0", 

            "Code": "0", 

            "Description": "", 

            "AppServer": "105IVERIAPPPR2N", 

            "DBServer": "105iveridbpr01n", 

            "Gateway": "Nedbank" 

        } 

    } 

} 

 

<?xmlversion="1.0"encoding="utf-8"?> 

<soap:Envelopexmlns:soap="http://schemas.xmlsoap.org/soap/envelope/"xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"xmlns:xsd="http://www.w3.org/2001/XMLSchema"> 

    <soap:Body> 

        <ExecuteResponsexmlns="http://iveri.com/"> 

            <ExecuteResult>&lt;V_XML Version="2.0" Direction="Response"&gt; 

  &lt;Transaction ApplicationID="{7C523A4-7DA7-4E59-B888-569FE65C535B}" Command="Void" Mode="Test" RequestID="{2EDCA6EC-0683-41C2-872B-CC5A01355EFD}"&gt; 

    &lt;Result Status="0" Code="0" Description="" AppServer="105IVERIAPPPR2N" DBServer="105iveridbpr01n" Gateway="Nedbank" /&gt; 

    &lt;OriginalMerchantTrace&gt;240X568BEEE&lt;/OriginalMerchantTrace&gt; 

    &lt;OriginalRequestID&gt;{B3C46039-5B4D-402A-82A7-A37BC0161167}&lt;/OriginalRequestID&gt; 

  &lt;/Transaction&gt; 

&lt;/V_XML&gt;</ExecuteResult> 

        </ExecuteResponse> 

    </soap:Body> 

</soap:Envelope> 

 


Additional Data for Procurement Transactions


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.

Coding 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 
  • 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 https://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() 

 
 
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 

Calculation when TransactionDiscount is NOT zero 

The TransactionDiscount is spread across some or all 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. 



Fleet card transactions


Fleet card 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. 

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

} 



Advanced Fraud Screening


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 https://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("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 



Airline addendum data


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 for Nedbank. In addition, the airline addendum data is currently only supported for follow-up debit (pre-authorised debit) transactions.

Coding for Airline addendum data 

The following is a code snippet in C#:

 

enterprise.openElement("AirlineData"); 

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


These following fields are not recorded on the iVeri system: 

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.


CyberSource Fraud Management


CyberSource Fraud Management

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

 
 Device Fingerprinting 

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: 

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="">   

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>  

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. 


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

 



Authenticated Collections


Authenticated Collections

 
Authenticated 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 
  • The customer has verified 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. In addition, the Authenticated Collections provider parameter must be enabled otherwise the transaction will be declined. 

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.


Contact Information


Contact Information

 
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.

 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 

https://operations@iveri.com/ 

  

Non-technical (i.e. product information etc) 

https://info@iveri.com/ 

 

23..2 Nedbank Namibia 

Location 

Namibia 

Web sites 

http://www.iveri.co.za/ 

http://www.nedbank.co.za/ 

Email 

Technical Assistance 

https://operations@iveri.com/ 

  

Non-technical (product information etc) 

https://info@namibia.nedbank.iveri.com/ 

23.3 CBZ Zimbabwe 

Location 

Zimbabwe 

Web sites 

http://www.iveri.com/ 

https://www.cbzbank.co.zw/ 

Email 

Technical Assistance 

https://operations@iveri.com/ 

  

Non-technical (product information etc) 

https://info@iveri.com/ 

 

 

 

23.4 CIM Finance 

 

 

 

 

 

 

 

23.5 I&M Bank 

Location 

Kenya 

Web sites 

http://www.iveri.com/ 

http://www.imbank.com/ 

Email 

Technical Assistance 

https://operations@iveri.com/ 

  

Non-technical (product information etc) 

https://info@iveri.com/ 

 

23.6 CSC/CSC247 Bank 

Location 

Lebanon & Cyprus 

Web sites 

http://www.iveri.com/ 

http://www.cscacquiring.com/ 

Email 

Technical Assistance 

https://operations@iveri.com/ 

  

Non-technical (product information etc) 

https://info@iveri.com/ 

 

Location 

Cim Finance 

Web sites 

http://www.iveri.com/ 

http://www.cim.mu/ 

Email 

Technical Assistance 

https://operations@iveri.com/ 

  

Non-technical (product information etc) 

https://info@iveri.com/ 

 

23.8 Gateway Websites 

Merchants has access to 3 iVeri websites: Gateway, Certificate and BackOffice. 

Website 

Description 

Portal 

Used whenever transactions are posted to the iVeri Gateway  

Certificate 

Used where applicable to validate certificate against the root certificate  

BackOffice 

Merchant portal used for accessing transaction listing, creation of users and downloading transactions reports 

 

 

 

 

 

 

23.8.1 Gateway Portal Address by acquiring institution. 

23.8.1.1 Nedbank 

 

 

 

Website 

URL 

Port 

Portal 

https://portal.nedsecure.co.za/ 

443 

Certificate 

http://ca.iveri.com/ 

80 

BackOffice 

https://backoffice.nedsecure.co.za/ 

443 

 

 

 

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

 

 

 

 

23.8.1.3 I&M Bank 

Website 

URL 

Port 

Gateway 

https://portal.host.iveri.com/ 

443 

Certificate 

http://ca.veri.com/ 

80 

BackOffice 

https://backoffice.host.iveri.com/ 

443 

 

 

 

 

23.8.1.4 CSC/CSC247 Bank 

Website 

URL 

Port 

Gateway 

https:///https://portal.cscacquiring.com/ 

443 

Certificate 

http://ca.veri.com/ 

80 

BackOffice 

https://backoffice.cscacquiring.com/ 

443 

 

 

 

 

 

 

23.8.1.5 CIM Finance 

Website 

URL 

Port 

Gateway 

https://portal.merchant.cim.mu/   

443 

Certificate 

http://ca.veri.com/ 

80 

BackOffice 

https://backoffice.merchant.cim.mu/ 

443 

 

 

 

 

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.