2. KnowSystem
  3. Tokenization

Tokenization

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

COF and Debit with PAN

Process a COF transactions by setting CardHolderPrense to “COF” and providing the full card details.

  • CardHolderPresence": "COF”
  • PAN:  
  • ExpiryDate: 

COF and Debit with TransactionIndex 

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

  • CardHolderPresence": "COF”
  • 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

CIT - COF & MOTO

 

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 “COF, MOTO” and providing the full card details.

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


COF and Debit with TransactionIndex 

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

  • CardHolderPresence": "COF, MOTO”
  • 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 - COF & Recurring

 

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 “COF, Recurring ” and providing the full card details.

  • CardHolderPresence": "COF, Recurring”
  • PAN:  
  • ExpiryDate: 


Debit with TransactionIndex 

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

  • CardHolderPresence": "COF, Recurring”
  • 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 “COF, 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.


Subsequent Recurring Transaction Message

In the sample below "CardHolderPresence" is set by the merchant on the Debit instruction:

 REST

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": "Ned20221214_1117",

        "Currency": "ZAR", 

        "Amount": "1600",

        "ExpiryDate": "1230",

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

        "CardHolderPresence": "Recurring",

        "PANFormat": "TransactionIndex",

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

        

 

    } 


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

        }

    }

}

 

SOAP

Request 

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

 


Response 

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

Network Tokens

What is Tokenisation?

Tokenization is a process in which the customers sensitive card information is replaced by a unique identifier ("token") which can be used to make online payments. 

What are Network Tokens?

Card Networks like Visa, Mastercard offer tokenization services, where the card network holds the card number (PAN) and replaces with a network token which can be used to effect online payments.

Benefits of Network Tokens

  • Seamless checkout experience and reduced customer friction as the payment token is carried across the payment ecosystem 
  • Reduces transaction failures attributed to expired or stolen cards

iVeri Gateway Token Vs Network Token

  • Network Tokens - Merchants or Payment Service Providers can do a direct integration for tokenization services with the card networks and only make use of the network token during payment instruction to the iVeri Gateway 
  • iVeri Tokens - Merchants processing iVeri tokenised transactions can be enabled for network tokens, the iVeri Gateway will manage the tokenRequest onbehalf of the merchant to the brand networks.

Use Cases

  • Online, ecommerce merchants where card acceptance is processed on web or mobile applications
  • Where merchants have customer profiles, along with card on file payment credentials

Network Token Flows

 

Network Token Parameters -  Auth/Debit to the Gateway

Non 3D Secure Transactions

3D Secure Transactions

Comments

PAN = “Token”

PAN  = “Token”

 As returned by the network scheme

ExpiryDate= “expiry date”

ExpiryDate= “expiry date”

 As returned by the network scheme

CardHolderAuthenticationID  = “TAVV”

 

 

 

CardHolderAuthenticationID = “XID”

 

TAVV as returned by the network scheme for non-3D secure transactions, while for 3D secure the XID value should be passed( if available)

As a note, from an acquirer perspective, and with Visa Tokens, there is only one field that can handle the XID and TAVV values.  In a nutshell, the merchant can either process a 3D secure transaction or Non-3Dsecure transaction. One transaction cannot carry both values at the same time.

ElectronicCommerceIndicator = “SecureChannel”

 

ElectronicCommerceIndicator = “ ECI "

​

 

For 3D secure transactions, existing ECI's should be passed

  • ThreeDSecure ( "05")
  • ThreeDSecureAttempted ( "06")
  • SecureChannel ("07")

For non 3D secure transactions - only ECI value "SecureChannel" should used

CardHolderPresence =” COF, SecureChannel”

 CardHolderPresence ="COF"

Expected when Non-3D/3D secure transactions are processed.

 

 

 CardHolderAuthenticationData

 For 3D secure transaction, the CardholderAuthenticationData ("CAVV") should be included in the Auth/Debit as is to-date 

The following table outlines applicable parameters when 3D secure or non 3D secure transactions are processed to the iVeri Gateway.

To note, all existing parameters that are applicable for 3D secure transactions remain unchanged. To add, merchants that do not support card on file payment credentials with their customers can still continue to accept and process payments using full card details.

iVeri Token Flows

iVeri Token Parameters -  Auth/Debit to the Gateway

The following table outlines applicable parameters when 3D secure or non 3D secure transactions are processed to the iVeri Gateway. 

Non 3D Secure

3D secure

Comments

PAN =  “first 4 last 4”

PAN  = “first 4 last 4”

As returned by the iVeri Gateway on the initial transaction or token response

ExpiryDate= “expiry date”

ExpiryDate= “expirydate”

 

PANFormat = “TransactionIndex”

” PANFormat =“TransactionIndex”

 

TransactionIndex = iVeri Token (“TransactionIndexValue”)

TransactionIndex = ”  iVeri Token (“TransactionIndexValue”)

 

As returned by the iVeri Gateway

 

CardHolderAuthenticationID = “XID value ”

 

If available, should be included on the Auth/Debit for 3D Secure authenticated transactions

 

ElectronicCommerceIndicator = “ ECI "

For 3D secure transactions, existing ECI's should be passed

  • ThreeDSecure ( "05")
  • ThreeDSecureAttempted ( "06")
  • SecureChannel ("07")

For non 3D secure transactions - only ECI value "SecureChannel" should used

 

 

CardHolderAuthenticationData = "CardHolderAuthenticationData"

For 3D secure transaction, the CardholderAuthenticationData ("CAVV") should be included in the Auth/Debit as is to-date 

CardHolderPresence= "COF"

CardHolderPresence= "COF"

For additional uses cases where tokens can be used, refer to the Card On File - Recurring/Adhoc section.