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.

Merchant Requirements

  • Merchants are required to enter into a “Agreement” with an authorised Acquiring Institution. Once there is a merchant agreement in place, a merchant profile can be created
  • With Enterprise calls to the Gateway, the presence of a certificate ID is required, with the actual physical certificate available as optional means to authenticate merchant requests  
  • Test Mode should used during integration, testing, and validation
  • Test application ID  must be used with Mode Test 

Terminology

This document uses certain iVeri specific terminology which can be referenced in Parameter Description




Merchant Requirements

 

  • Merchants are required to enter into a “Agreement” with an authorized Acquiring Institution. Once there is a merchant agreement in place, a merchant profile can be created.
  • With Enterprise calls to the Gateway, the presence of a certificate ID is required, with the actual physical certificate available as optional means to authenticate merchant requests. 
  • Test Mode should be used during integration, testing, and validation.
  • Test application ID must be used with Mode Test


Terminology

 
This document uses certain iVeri specific terminology which can be referenced in Parameter Description


SOAP API


 
The SOAP services allow cross platform integration with the various systems provided by iVeri, using a common interface. With the SOAP API, merchanst can implemented payment mechanisms which are supported are stated in the following sections:

Commands and Action
Payment Flow
Parameter Description
Parameter Per Action



Web Service implementation

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

  • The V_XML request and response format is defined by the V_XML.xsd schema, which can be downloaded from https://portal.nedsecure.co.za/schemas/v_xml/7.0/v_xml.xsd
  • Client code must check the respective Result fields to determine if the web service method was successful or not. (Result fields are defined by the V_XML specification)
  • For a client to call the execute method the client certificate ID must be provided with the HTTP Request



Webservice Gateway Address

 
iVeri WebService uses the Gateway addresses below with the following:

  • [portal]/iVeriWebService/Service.asmx



Message Formats

 
Communication between the client and web service is via SOAP protocol. Format supported is in XML.The SOAP requests and responses are shown for each method provided by the web service.



WebService Methods

 



Execute - (bool validateRequest, string protocol, string protocolVersion, string request)

 
Usage: For posting of transactions to the Gateway

Description

Execute

Execute the V_XML formatted request. The action to be performed is determined by the V_XML, as defined by the V_XML specifications.

 

ie. Transaction (Sale, Refund etc)

Returns

A V_XML formatted string (The return string will need to be URL decoded)

Client Certificate

Is required (provided with HTTP Request)

Parameters

ValidateRequest: boolean

true:

Will validate the V_XML request against the schema definition. If there are any schema errors processing of the request will terminate and the request will not be passed on to the relevant provider.

or

false:

Will not validate the V_XML request.

The V_XML request along with any schema errors will be passed on to the relevant provider for processing. If there are schema errors processing will terminate in the provider.

 

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

Protocol: string

Currently supported protocols

•        V_XML

 

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

ProtocolVersion: string

Currently supported protocol version

•        "7.0" (V_XML)

 

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

Request: string

A V_XML format string without any namespace declarations. Providing namespace declarations will result in an unsuccessful call.

 

The request must also be URL encoded

 

Additional

Validation Performed

The execute method will also return unsuccessful if:

 

•        No client certificate present

•        Certificate ID not provided in the V_XML request

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

 

Validation of the Client Certificate is always performed.

 

 

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

Execute SOAP Message

 

Request

Response

POST /iVeriWebService/Service.asmx HTTP/1.1

Host: portal.nedsecure.co.za

Content-Type: text/xml; charset=utf-8

Content-Length: length

 

<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="e7c523a4-7da7-4e59-b888-569fe65c535b" Command="Debit" Mode="Test"&gt;

    &lt;MerchantTrace&gt;240X5681EEE&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.14:31&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>

 

 

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

 

 

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

<soap:Envelope xmlns: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="{E7C523A4-7DA7-4E59-B888-569FE65C535B}" Command="Debit" Mode="Test" RequestID="{E7AF107F-C9F6-4086-927D-935368B504EE}"&gt;

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

    &lt;MerchantTrace&gt;240X5681EEE&lt;/MerchantTrace&gt;

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

    &lt;AuthorisationCode&gt;311507&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.14:31&lt;/MerchantReference&gt;

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

    &lt;TransactionIndex&gt;{E5E2E178-4B2D-4DD2-82F1-B26DCD34FCBE}&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;95707:04645632&lt;/AcquirerReference&gt;

    &lt;AcquirerDate&gt;20230103&lt;/AcquirerDate&gt;

    &lt;AcquirerTime&gt;143147&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;04645632&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>

 

 

 

DownloadFile Method (string fileServiceCommand)

Usage: For downloading files from the Gateway

 

Description

fileServiceCommand

Downloads a file

 

Returns

A Base64 encoded string which is the contents of the downloaded zipped file.

 

 

Client Certificate

Send as parameter

Parameters

See section File Transfer Parameters

DownloadFile SOAP Message

 

Request

Response

Transaction History Download

POST /iVeriWebService/Service.asmx HTTP/1.1

Host: portal.nedsecure.co.za

Content-Type: text/xml; charset=utf-8

Content-Length: length

 

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">

<env:Header/>

<env:Body>

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

<fileServiceCommand>

&lt;File Command=&quot;TRANSACTIONHISTORY&quot;&gt;

&lt;Gateway&gt;Nedbank&lt;/Gateway&gt;

&lt;CertificateID&gt;{2bc42c-7ffb-44d0-a1e4-441444e1274c}&lt;/CertificateID&gt;

&lt;UserGroup&gt;3**816&lt;/UserGroup&gt;

&lt;UserName&gt;administrator&lt;/UserName&gt;

&lt;Password&gt;$C***n&lt;/Password&gt;

&lt;FileName&gt;TransactionHistory.zip&lt;/FileName&gt;

&lt;Mode&gt;Test&lt;/Mode&gt;

&lt;StartDateTime&gt;2022-11-01T10:00:00&lt;/StartDateTime&gt;

&lt;EndDateTime&gt;2022-11-02T11:00:00&lt;/EndDateTime&gt;

&lt;Format&gt;XML&lt;/Format&gt;&lt;/File&gt;

</fileServiceCommand>

</DownloadFile>

</env:Body>

</env:Envelope>

 

POST /iVeriWebService/Service.asmx HTTP/1.1

Host: portal.nedsecure.co.za

Content-Type: text/xml; charset=utf-8

Content-Length: length

 

 

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

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

    <soap:Body>

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

            <DownloadFileResult>UEsDBBQAAggIAPV2I1aSB0HNoKIBAHQHDAAWABQAVHJhbnNhY3Rpb25IaXN0b3J5LnhtbFJYEABSYngxAQAIAAAAAAAAAAAA7H1pUxvJ0vVfIfzVt4falzcwEVVd1Rizr7b58oYsySDQgiVkG9+4//05JYHBY0Dd0gwgwr7PM4GkUiOaIk9lnpMnlw7//4eN9YXDZn/Q6nXfvGJ/kVcLodVv1i9Gj3ebg/Ned9B8tby026z3umlx3ht2L968kpTh2f1+rTuojVYvuPPzdqteS1+vhjev/it4YJH6PJMF05nQmmRWOZtJZymlRcgVl/97tbDRazTfvFpvfW2+wrU7nVq38eZVaH5qXbxa2G1+GTYHF6PLEaIVITZkXhKTCZ/HzClVZKJQSuU540LE/+EjbQ/79ZPaoBlqF81lRhijlLClxV+e/rlov9VpLhMjCSE3S0ZPLm0006PuBX7EenP5v8Lmmjoj8O356NsXmSmIzgotheHEUhn1/5YWf33X7fuz2m00vy//N +gCZYfEgGgBQSwECLQAUAAIICAD1diNWkgdBzaCiAQB0BwwAFgAkAAAAAAAAAIAAAAAAAAAAVHJhbnNhY3Rpb25IaXN0b3J5LnhtbAoAIAAAAAAAAQAYAPL5+69yH9kBAAAAAAAAAAAAAAAAAAAAAFBLBQYAAAAAAQABAGgAAADoogEAAAA=</DownloadFileResult>

        </DownloadFileResponse>

    </soap:Body>

</soap:Envelope>

 

 

Recon Download Sample

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">

<env:Header/><env:Body>

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

         <fileServiceCommand>

                &lt;File Command=&quot;RECON&quot;&gt;

                &lt;Gateway&gt;Nedbank&lt;/Gateway&gt;

                &lt;CertificateID&gt;{12bc42c-7ffb-44d0-a1e4-441444e1274c}&lt;/CertificateID&gt;

                &lt;UserGroup&gt;256146&lt;/UserGroup&gt;

                &lt;UserName&gt;Bu****H&lt;/UserName&gt;

                &lt;Password&gt K******NS&lt;/Password&gt;

                &lt;FileName&gt;Recon.zip&lt;/FileName&gt;

                &lt;AcquirerCycle&gt;02463&lt;/AcquirerCycle&gt;

                &lt;Mode&gt;Test&lt;/Mode&gt;

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

                &lt;MerchantUsn&gt;0092201&lt;/MerchantUsn&gt;

                &lt;Format&gt;XML&lt;/Format&gt;

                &lt;/File&gt;

</fileServiceCommand>

</DownloadFile>

</env:Body>

</env:Envelope>

 

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

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

    <soap:Body>

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

            <DownloadFileResult>UEsDBBQAAggIAKl1JVZmVbJ6TQAAAEgAAAAJABQAUmVjb24ueG1sUlgQAFJieDEBAAgAAAAAAAAAAAABSAC3/zxWX1hNTCBWZXJzaW9uPSIyLjAiIERpcmVjdGlvbj0iUmVzcG9uc2UiPjxSZWNvblhNTCBDb3VudD0iMCIgLz48L1ZfWE1MPlBLAQItABQAAggIAKl1JVZmVbJ6TQAAAEgAAAAJACQAAAAAAAAAgAAAAAAAAABSZbi54bWwKACAAAAAAAAEAGAAXnhiRAyHZAQAAAAAAAAAAAAAAAAAAAABQSwUGAAAAAAEAAQBbAAAAiAAAAAAA</DownloadFileResult>

        </DownloadFileResponse>

    </soap:Body>

</soap:Envelope>

 



UploadFile (string fileServiceCommand)

 
Usage: Upload Batch files to the iVeri Gateway

 

Description

fileServiceCommand

Uploads file

 

 

Returns

Result Status Code and Description

Parameters

Client Certificate

Send as parameter

Parameters

See section File Transfer Parameters

UploadFile SOAP Message

 

Request

Response

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">

    <env:Header/>

    <env:Body>

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

            <fileServiceCommand>

                &lt;File Command=&quot;BATCH&quot;&gt;

                &lt;Gateway&gt;Nedbank&lt;/Gateway&gt;

  &lt;CertificateID&gt;{00000000-0000-0000-0000-0000000000000}&lt;/CertificateID&gt;

  &lt;UserGroup&gt;000006&lt;/UserGroup&gt;

  &lt;UserName&gt;Administrator&lt;/UserName&gt;

  &lt;FileName&gt;****&lt;/FileName&gt;

  &lt;Password&gt;S*****3&lt;/Password&gt;&lt;/File&gt;           

          </fileServiceCommand>

           <fileData>

   PFZfWE1MIFZlcnNpb249IjIuMCIgRGlyZWN0aW9uPSJSZXF1ZXN0Ij

4gDQogIDxCYXRjaCBWZXJzaW9uPSIyLjAiIENvbW1hbmQ9IkJhdGNoVXBs

b2FkIiBDb3VudD0iMSIgQW1vdW50PSIxMDAwIj4gDQoJCTxEYXRlPjIwMjAxMTA2
PC9EYXRlPiANCgkJPEZpbGVuYW1lPkJ1c2lUZXN0QXBwbGljYXRpb24xPC9Ga

WxlbmFtZT4gDQoJCTxEZXNjcmlwdGlvbj5XZWRuZXNkYXlMb2FkPC9EZXNjcm

lwdGlvbj4gDQoJCTxCYXRjaEl0ZW0gQXBwbGljYXRpb25JRD0ie2JiMDg3M2ViLTBjOTctNGJkNS05NGZiLTNhY2Q3MmFlMGEz

M30iIE1vZGU9IlRlc3QiIENvbW1hbmQ9IlJlY3VycmluZ0RlYml0Ij4gDQoJCQk8Q0NOdW1iZXI+NDI0Mi4uLi4uLi4uNDI0MjwvQ0NOdW1iZXI+IA0KCQkJPFN0YXJ0RGF0ZT4xMTIwMjA8L1N0YX

J0RGF0ZT4NCgkJCTxFeHBpcnlEYXRlPjEyMjAyMDwvRXhwaXJ5RGF0Z

T4NCgkJCTxCdWRnZXRQZXJpb2Q+PC9CdWRnZXRQZX

Jpb2Q+IA0KCQkJPFRlcm1pbmFsPjQ3ODUyMzI2PC9UZXJtaW5

hbD4NCgkJCTxBbW91bnQ+MTAwMDwvQW1vdW50Pg0KCQkJPEN1cnJlbmN5PlpBUjwvQ3
VycmVuY3k+IA0KCQkJPE1lcmNoYW50UmVmZXJlbmNlPk9uVGhlR09XZ

WRUZXN0aW5nRnJpZGF5PC9NZXJjaGFudFJlZmVyZW5jZT4gDQoJCQk

8UHVyY2hhc2VEYXRlPjIwMjAxMTA0PC9Q

dXJjaGFzZURhdGU+IA0KCQkJPFB1cmNoYXNlVGltZT4wOTEwMTk8L1B

1cmNoYXNlVGltZT4gDQoJCQk8VHJhbnNhY3Rpb25JbmRleD57MkE2N

EI5NkQtNDkyRC00Njc4LUJFRjgtRDUyNEYyNjlBRjFGfTwvVHJhbnNhY3Rpb25JbmRleD4NCgkJPC9CYXRjaEl0ZW

0+DQoJPC9CYXRjaD4gDQo8L1ZfWE1MPg==

          </fileData>

        </UploadFile>

    </env:Body>

</env:Envelope>

 

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

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

    <soap:Body>

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

            <UploadFileResult>&lt;?xml version="1.0" encoding="utf-8" ?&gt;

    &lt;File&gt;&lt;Result Status="0" Description="File uploaded successfully."/&gt;&lt;/File&gt;

          </UploadFileResult>

        </UploadFileResponse>

    </soap:Body>

</soap:Envelope>

 



IsDataAvailable (string fileServiceCommand)

 
Usage: Check if Batch result file is available on the iVeri Gateway, works hand in hand with the UploadFile method

 

Description

IsDataAvailable

Check the availability of the Batch result file

 

 

Returns

Result Status Code and Description

Parameters

Client Certificate

Send as parameter

Parameters

See section File Transfer Parameters

IsDataAvailable SOAP Message

 

Request

Response

<env:Envelope xmlns:env="http://www.w3.org/2003/05/soap-envelope">

<env:Header/><env:Body>

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

         <fileServiceCommand>

                &lt;File Command=&quot;BATCH&quot;&gt;

                &lt;Gateway&gt;Nedbank&lt;/Gateway&gt;

                &lt;CertificateID&gt;{bc42c-7ffb-44d0-a1e4-441444e1274c}&lt;/CertificateID&gt;

                &lt;ApplicationID&gt;{b0873eb-0c97-4bd5-94fb-3acd72ae0a33}&lt;/ApplicationID&gt;

                &lt;UserGroup&gt;25***46&lt;/UserGroup&gt;

                &lt;UserName&gt;Administrator&lt;/UserName&gt;

                &lt;Password&gt;S******&lt;/Password&gt;

                &lt;FileName&gt;Test&lt;/FileName&gt;            

                &lt;Mode&gt;Test&lt;/Mode&gt;

                &lt;Format&gt;XML&lt;/Format&gt;&lt;/File&gt;

</fileServiceCommand>

</IsDataAvailable>

</env:Body>

</env:Envelope>

 

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

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

    <soap:Body>

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

            <IsDataAvailableResult>&lt;?xml version="1.0" encoding="utf-8" ?&gt;

&lt;File&gt;&lt;Result Status="101" Description="File not found"/&gt;&lt;/File&gt;

</IsDataAvailableResult>

        </IsDataAvailableResponse>

    </soap:Body>

</soap:Envelope>

 



GenerateCertificateID (string billingDetailsID)


GenerateCertificateID

Creates a new unique Certificate ID to be used when generating a new certificate signing request. Certificate status will be created. This method must be used in conjunction with the SubmitCertificateRequest method to complete request of a new certificate.

Returns

A V_XML formatted string containing the generated certificate ID.

Client Certificate

not required

Parameters

billingDetailsID: string

Merchant Profile ID /User Group ID

 

 

GenerateCertificateID SOAP Message

 

Request

Response

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

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

  <soap:Body>

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

      <billingDetailsID>string</billingDetailsID>

    </GenerateCertificateID>

  </soap:Body>

</soap:Envelope>

 

 

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

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

  <soap:Body>

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

      <GenerateCertificateIDResult>string</GenerateCertificateIDResult>

    </GenerateCertificateIDResponse>

  </soap:Body>

</soap:Envelope>

 

 

GenerateCertificateID SOAP Message

 

Request

Response

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

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

  <soap:Body>

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

      <billingDetailsID>string</billingDetailsID>

    </GenerateCertificateID>

  </soap:Body>

</soap:Envelope>

 

 

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

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

  <soap:Body>

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

      <GenerateCertificateIDResult>string</GenerateCertificateIDResult>

    </GenerateCertificateIDResponse>

  </soap:Body>

</soap:Envelope>

 

 

GetCertificate(string certificateID)

 

Description

 

GetCertificate

Download a base 64 encoded P7B certificate that has been issued

Returns

A V_XML formatted string (The return string will need to be URL decoded) containing the

Client Certificate

not required

Parameters

 

certificateID:string

Certificate ID (GUID) used to generate the certificateSigningRequest

GetCertificate SOAP Message

 

Request

Response

 

POST /iVeriWebService/Service.asmx HTTP/1.1

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "http://iveri.com/GetCertificate"

 

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

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

  <soap:Body>

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

      <certificateID>string</certificateID>

    </GetCertificate>

  </soap:Body>

</soap:Envelope>

 

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

 

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

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

  <soap:Body>

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

      <GetCertificateResult>string</GetCertificateResult>

    </GetCertificateResponse>

  </soap:Body>

</soap:Envelope>



RenewCertificateID (string certificateID)

 
Usage: Renewal of an existing certificate

Description

RenewCertificateID

Will change the certificate status of the certificate mathcing the certificate ID to "created". This method must be used in conjunction with the SubmitCertificateRequest method to complete the renewal of the certificate.

Returns

A V_XML formatted string (The return string will need to be URL decoded)

Client Certificate

not required

Parameters

certificateID: string

Certificate ID (GUID) of existing certificate.


RenewCertificateID Sample Message

 

Request

Response

 

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "http://iveri.com/RenewCertificateID"

 

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

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

  <soap:Body>

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

      <billingDetailsID>string</billingDetailsID>

      <certificateID>string</certificateID>

    </RenewCertificateID>

  </soap:Body>

</soap:Envelope>

 

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

 

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

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

  <soap:Body>

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

      <RenewCertificateIDResult>string</RenewCertificateIDResult>

    </RenewCertificateIDResponse>

  </soap:Body>

</soap:Envelope>

 



PinBlock GetPinBlock (string mode, string pan, string pin)


Description

 

Generate a PIN Block using the HSM (Hardware Security Module)

Returns

 

PinBlock data structure containing the following fields:

 

•        ResultStatusCode

•        ResultDescription

•        DeviceSerialNumber

•        DeviceMake

•        KeySerialNumber

•        PinBlock

 

ResultStatusCode see Status Codes used by V_XML

ResultDescription see Descriptions used by V_XML

Client Certificate

 

 

not required

 

 

Parameters

mode

: string

"test"

 

"live"

 

 

pan

: string

Primary Account Number

pin

: string

 

Additional

Validation Performed

•        pan length is not less than 13 chracters and not more than 19 characters

•        pan is also validated against the LUHN Formula

•        pin length is not less than 4 characters and not more than 14 characters

GetPinBlock SOAP message

 

Request

Response

POST /iVeriWebService/Service.asmx

Content-Type: text/xml; charset=utf-8

Content-Length: length

SOAPAction: "http://iveri.com/GetPinBlock"

 

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

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

  <soap:Body>

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

      <mode>string</mode>

      <pan>string</pan>

      <pin>string</pin>

    </GetPinBlock>

  </soap:Body>

</soap:Envelope>

 

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

 

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

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

  <soap:Body>

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

      <GetPinBlockResult>

        <ResultStatusCode>int</ResultStatusCode>

        <ResultDescription>string</ResultDescription>

        <DeviceSerialNumber>string</DeviceSerialNumber>

        <DeviceMake>string</DeviceMake>

        <KeySerialNumber>string</KeySerialNumber>

        <PinBlock>string</PinBlock>

      </GetPinBlockResult>

    </GetPinBlockResponse>

  </soap:Body>

</soap:Envelope>

 



SubmitCertificate (string certificateID, string certificateSigningRequest)

 

Description

SubmitCertificateRequest

Submits a PKCS10 certificate signing request. Certificate status will be pending.

Returns

A V_XML formatted string.

Client Certificate

not required

Parameters

certificateID

: string

Certificate ID (GUID) used to generate the certificateSigningRequest

certificateSigningRequest

: string

 

 

Base 64 encoded string containing the new certificate signing request

 

example of a certificate signing request

BEGIN NEW CERTIFICATE REQUEST-----

MIIDGjCCAoMCAQAwgbMxCzAJBgNVBAYTAlpBMRAwDgYDVQQIDAdHYXV0ZW5nMRAwINT8mTAfmAe4FdlY9RUv43F9jBYqsV/B6fQxRiSehqnOeS4pmK5gIXiqmfgA/NmZqRiohLwr45SNu6NjF6Bx56T9fAw7RKTsN9dYb6vEtOXew2kc

-----END NEW CERTIFICATE REQUEST-----

 

SubmitCertificate SOAP Message

 

Request

Response

POST /iVeriWebService/Service.asmx HTTP/1.1

Content-Type: text/xml;

Content-Length: length

 

 

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

  <soap:Body>

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

      <certificateID>string</certificateID>

      <certificateSigningRequest>string</certificateSigningRequest>

    </SumitCertificateRequest>

  </soap:Body>

</soap:Envelope>

 

 

HTTP/1.1 200 OK

Content-Type: text/xml; charset=utf-8

Content-Length: length

 

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

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

  <soap:Body>

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

      <SumitCertificateRequestResult>string</SumitCertificateRequestResult>

    </SumitCertificateRequestResponse>

  </soap:Body>

</soap:Envelope>

 


REST API


Getting Started

With the REST API, merchants can enable card acceptance from a card not present or card present environment, where payments can include the use of tokenised cards and 3D secure authenticated data elements.

To begin processing transactions to the iVeri Gateway, the following has to be in place:

  1. Merchant Profile
  2. Generate Certificate in Backoffice 
    1. Only the certificate ID is required on transaction request to the iVeri Gateway
    2. Before use, the certificate ID has to be linked to the merchants application on the Gateway, reach out to iVeri support on assist@iveri.com to action

To get a view of the applicable parameters per payment instruction, the following sections can be referenced

Commands and Action
Payment Flow
Parameter Description
Parameter Per Action



Requirements (REST API)

 

  • Merchant profile that contains credentials to login to the merchant portal - Backoffice
  • Merchant must login to Backoffice and request a certificate, only the certificate ID is required.


Authorisation Header


Authorisation Header

When interfacing with the Gateway endpoints, merchants can include the AuthenticationKey and AuthenticationToken in the headers for both transaction status queries and transaction submissions.

Headers


AuthenticationKey

The key consists of the username. The key and username must be in lowercase

The Username must be encoded to base64 i.e bWVyY2hhbnRwcm9maWxlPTYxNjk1NA

AuthenticationToken

The token consists of:

AuthenticationSecret

This is the secret key generated by the merchant within Backoffice, which the merchant has to store on the merchant’s system.Once the secret is generated, it remains readable in plain text for a couple of minutes, after which it is hashed.  Merchant must copy the secret immediately after the secret is generated.

 If the merchant loses their secret, a new one will have to be generated

Resource

·        Query Transaction Status & Submission of Transactions endpoint

o    REST endpoints can be referenced 

Data

  • Payload that gets posted to the PosPort URL
    • Applies to the POST method

QueryString

Query string to retrieve transactions

o   /api/transactions?applicationid={applicationid}

o   /api/transactions/{requestid}

·        only to the GET Method

Timestamp

Calculated as follows:

Timestamp

 

private static Int32 UnixTimeStampUTC()

{

    Int32 unixTimeStamp;

    DateTime currentTime = DateTime.Now;

    DateTime zuluTime = currentTime.ToUniversalTime();

    DateTime unixEpoch = new DateTime(1970, 1, 1);

    unixTimeStamp = (Int32)(zuluTime.Subtract(unixEpoch)).TotalSeconds;

    return unixTimeStamp;

}

Calculating the Token


/// <summary>

///

/// </summary>

/// <param name="sharedSecret"></param>

/// <param name="resource"></param>

/// <param name="queryString"></param>

/// <param name="data"></param>

/// <param name="time"></param>

/// <returns></returns>

public static string GenerateAuthenticationToken(string sharedSecret, string resource, string queryString, string data, string time)

{

    byte[] sourceBytes = Encoding.UTF8.GetBytes(time)

        .Concat(Encoding.UTF8.GetBytes(resource))

        .Concat(Encoding.UTF8.GetBytes(queryString))

        .Concat(Encoding.UTF8.GetBytes(data))

        .ToArray();

    return GetHmacSha256(Encoding.ASCII.GetBytes(sharedSecret), sourceBytes);

}

 

/// <summary>

///

/// </summary>

/// <param name="sharedSecret"></param>

/// <param name="source"></param>

/// <returns></returns>

public static string GetHmacSha256(byte[] sharedSecret, byte[] source)

{

    HMACSHA256 hashString = new HMACSHA256(sharedSecret);

    var hashbytes = hashString.ComputeHash(source);

    StringBuilder digestBuilder = new StringBuilder();

    foreach (byte b in hashbytes)

    {

        digestBuilder.Append(b.ToString("x2"));

    }

    return digestBuilder.ToString();

 

 


REST API


REST Endpoints

 
On all endpoints the following applies:

  • Method: Only GET, POST methods are supported
  • Format: JSON


Submission of transactions to the correct Gateway endpoint relates to the acquiring bank that holds the merchant agreement. To submit transactions to the iVeri Gateway, merchants can connect to following end points.



REST API


Endpoint Overview

 

EndPoint

Purpose

Usage

/api/transactions

HTTP Method: POST

Submit transactions to iVeri Gateway endpoint  

card processing of transactions to the Gateway

/api/merchant/authenticate

HTTP Method: GET


Returns the server UTC datetime formatted as “yyyyMMddHHmmssfff

 

/api/merchant/configuration?mode=live|test

HTTP Method: GET

Returns the user parameters configured in the BackOffice website.

Mode is optional. When not specified “live” configuration will be returned?

 

Usage: Optional, and only applicable to mPress Card Present transactions 

/api/merchant/bins

HTTP Method: GET

Returns the current bin list used by the gateway in determining whether to prompt for PIN entry on POS devices when the card service code incorrectly identifies this requirement.

 

/api/transactions?applicationid={applicationid}

HTTP Method: GET

Returns the application transaction history for the last 7 days

Optional, but can be used to fetch any transactions processed by the Gateway

/api/transactions/{requestid}

HTTP Method: GET

Returns transaction details for a particular transaction identified by the requestid

 

/api/transactions/{requestid}/receipt

HTTP Method: POST

Upload cardholder digital signature to the gateway

 only applicable in the mPress Card Present solution

 

 

 

 



Endpoints in Detail

 
/api/merchant/authenticate
Returns the current server time, in UTC, formatted as yyyyMMddHHmmssfff. This time can be used to check the client time against that of the server. A deviation of five minutes or less is allowed between the client and server time.

yyyy – four-digit year
MM – two-digit month
dd – two-digit day
HH – Hour formatted as 24-Hour time
mm – two-digit minutes 
ss – two-digit seconds
fff – current millisecond

Example
Monday, 7th October 2013, 17:02:45 PM would be formatted as 20131007150245442.

JSON Response:
20131007150245442

/api/merchant/configuration
Returns the user parameters as configured in the BackOffice website.

The user parameters consist of list of applications selected for the user
list of currencies selected for the user list of permissions selected for the user

JSON Response:

{
"Applications": [{
"Description": "mPress test application",
"ApplicationID": "1d76a36f-f10e-4388-87f4-4675c78a5511",
"CertificateID": "4c96973f-71dd-4044-802d-6e234effe8f2",
"Mode": "Live"
},
{
"Description": "mPress test application",
"ApplicationID": "1d76a36f-f10e-4388-87f4-4675c78a5511",
"CertificateID": "7dcb6189-bfad-414b-b4ed-ea9d5875ea12",
"Mode": "Live"
}],
"Currencies": [{
"Format": "SCA,.R ",
"DecimalPlaces": 2,
"Code": "ZAR"
}],
"Permissions": [{
"Name": "AUTHORISATION",
"Allowed": "true"
},
{
"Name": "REFUND",
"Allowed": "true"
},
{
"Name": "SALE",
"Allowed": "true"
}]
}

NB. If no applications are returned in the response configuration, you will need to contact the administrator of the usergroup and request the necessary configuration changes to be made to the respective user.


Application list

You will need to select only one of the applications returned.
The application id, certificate id and mode will be used when performing a transaction to the gateway. The description is returned for display use only and not when performing the transaction

NB: You cannot simply switch to mode test using an application id received for mode live. You will need to download the configuration each time you change between test and live.

Permissions list

The permissions returned in the list relate to the transaction types that the user can perform using the REST API. If the “Allowed” value for any of the transaction types is set to “false”, that transaction option should not be presented to the user.

In all cases irrespective of the allowed transaction types, the void transaction type is allowed.

/api/transactions

Submit a transaction to the gateway.
JSON Request: 
Sample request for an mPress SDK (Card Present) implementation
{
"Version": "2.0",
"CertificateID": "{7dcb6189-bfad-414b-b4ed-ea9d5875ea12}",
"ProductType": "Enterprise",
"ProductVersion": "mPress",
"Direction": "Request",
"Transaction": {
"ApplicationID": "{1d76a36f-f10e-4388-87f4-4675c78a5511}",
"Command": "Debit",
"Mode": "Live",
"MerchantReference": "{11f1167c-9112-46ca-a69d-b0e856271f4b}",
"MerchantTrace": "{76c8813c-09ad-4b48-bbf5-4a4b320d6659}",
"DeviceMake": "Miura",
"DeviceSerialNumber": "02000567",
"EMV_ApplicationIdentifier": null,
"EMV_ApplicationInterchangeProfile": null,
"EMV_ApplicationTransactionCounter": null,
"EMV_ApplicationVersion": null,
"EMV_AuthorisationRequestCryptogram": null,
"EMV_CardHolderVerificationMethodResult": null,
"EMV_CardSequenceNumber": null,
"EMV_CryptogramInformationData": null,
"EMV_IssuerApplicationData": null,
"EMV_TerminalCapabilities": null,
"EMV_TerminalType": null,
"EMV_TerminalVerificationResult": null,
"EMV_UnpredictableNumber": null,
"EMV_TransactionStatusInformation": null,
"Currency": "ZAR",
"KeySerialNumber": "FF … 14",
"Track2KeySerialNumber": "FF … 44",
"Track2": "37E ... C155",
"PINBlock": "1F … 6F",
"Amount": "2500",
"ExpiryDate": "816",
"CardSecurityCode": null
}
}


/api/merchant/bins
Returns the current bin list used by the gateway in determining whether to prompt for PIN entry while using a POS device when the card service code incorrectly identifies this requirement.

JSON Response:

[{
"BIN": "201010",
"IsOnlineOnly": 1,
"IsPinCard": 2,
"MaxLength": 20
},
{
"BIN": "225050",
"IsOnlineOnly": 1,
"IsPinCard": 2,
"MaxLength": 20
},
{
"BIN": "3045",
"IsOnlineOnly": 1,
"IsPinCard": 2,
"MaxLength": 20
},]

The section “16.6.4 Determining if a card is PIN based” of the iVeri Client Developers Guide, describes how the bin list together with the card's service code is used in determining whether to prompt for PIN.


JSON Response:
{
"Version": "2.0",
"Direction": "Response",
"Transaction": {
"MerchantTrace": "76c8813c-09ad-4b48-bbf5-4a4b320d6659",
"Amount": "2500",
"AuthorisationCode": "660156",
"Currency": "ZAR",
"ExpiryDate": "082016",
"MerchantReference": "11f1167c-9112-46ca-a69d-b0e856271f4b",
"Terminal": "11111111",
"TransactionIndex": "{63D6D3F5-1F1B-46CE-B0EC-AD6F092F51B3}",
"MerchantName": "iVeri",
"MerchantUSN": "2169017345",
"Acquirer": "NedbankPostilion",
"AcquirerReference": "31008:00660156",
"AcquirerDate": "20131007",
"AcquirerTime": "184550",
"DisplayAmount": "R 25.00",
"BIN": "504931",
"Association": "MasterCard",
“CardType": "Unknown Card Type",
"Issuer": "Unknown Issuer",
"Jurisdiction": "Local",
"PANMode": "Swiped,PIN,EncryptedTrack2",
"ReconReference": "00660156",
"CardHolderPresence": "CardPresent",
"MerchantAddress": "MERCHANT ADDRESS",
"MerchantCity": "Johannesburg",
"MerchantCountryCode": "ZA",
"MerchantCountry": "South Africa",
"ApplicationID": "{1D76A36F-F10E-4388-87F4-4675C78A5511}",
"Command": "Debit",
"Mode": "Live",
"RequestID": "{A832F735-9A17-429D-8C82-46C833271D31}",
"Result": {
"Status": "0",
"AppServer": "QAGW2012APP1",
"DBServer": "QAGW2012DB1",
"Gateway": "QA"
},
"PAN": "5049........0023"
}
}


JSON Request:
Sample request for an eCommerce/CNP transaction 
{
"Version": "2.0",
"CertificateID": "{7dcb6189-bfad-414b-b4ed-ea9d5875ea12}",
"ProductType": "Enterprise",
"ProductVersion": "mPress",
"Direction": "Request",
"Transaction": {
"ApplicationID": "{1d76a36f-f10e-4388-87f4-4675c78a5511}",
"Command": "Debit",
"Mode": "Live",
"MerchantReference": "{11f1167c-9112-46ca-a69d-b0e856271f4b}",
"MerchantTrace": "{76c8813c-09ad-4b48-bbf5-4a4b320d6659}", 
"Currency": "ZAR", 
"Amount": "2500",
"ExpiryDate": "816",
"CardSecurityCode": null,
“PAN”: ”4242424242424242”

}
}

JSON Response:
{
"Version": "2.0",
"Direction": "Response",
"Transaction": {
"MerchantTrace": "76c8813c-09ad-4b48-bbf5-4a4b320d6659",
"Amount": "2500",
"AuthorisationCode": "660156",
"Currency": "ZAR",
"ExpiryDate": "082016",
"MerchantReference": "11f1167c-9112-46ca-a69d-b0e856271f4b",
"Terminal": "11111111",
"TransactionIndex": "{63D6D3F5-1F1B-46CE-B0EC-AD6F092F51B3}",
"MerchantName": "iVeri",
"MerchantUSN": "2169017345",
"Acquirer": "NedbankPostilion",
"AcquirerReference": "31008:00660156",
"AcquirerDate": "20131007",
"AcquirerTime": "184550",
"DisplayAmount": "R 25.00",
"BIN": "504931",
"Association": "MasterCard",
“CardType": "Unknown Card Type",
"Issuer": "Unknown Issuer",
"Jurisdiction": "Local",
"PANMode": "Swiped,PIN,EncryptedTrack2",
"ReconReference": "00660156",
"CardHolderPresence": "CardPresent",
"MerchantAddress": "MERCHANT ADDRESS",
"MerchantCity": "Johannesburg",
"MerchantCountryCode": "ZA",
"MerchantCountry": "South Africa",
"ApplicationID": "{1D76A36F-F10E-4388-87F4-4675C78A5511}",
"Command": "Debit",
"Mode": "Live",
"RequestID": "{A832F735-9A17-429D-8C82-46C833271D31}",
"Result": {
"Status": "0",
"AppServer": "QAGW2012APP1",
"DBServer": "QAGW2012DB1",
"Gateway": "QA"
},
"PAN": "4242........4242"
}
}


/api/transactions?applicationid={applicationid}
Returns the application transaction history for the last 7 days.
The JSON Response is a list of transaction responses.

/api/transactions/{requestid}
Returns transaction details for a particular transaction identified by the requestid.

JSON Response:
{
"Version": "2.0",
"Direction": "Response",
"Transaction": {
"MerchantTrace": "76c8813c-09ad-4b48-bbf5-4a4b320d6659",
"Amount": "2500",
"AuthorisationCode": "660156",
"Currency": "ZAR",
"ExpiryDate": "082016",
"MerchantReference": "11f1167c-9112-46ca-a69d-b0e856271f4b",
"Terminal": "11111111",
"TransactionIndex": "{63D6D3F5-1F1B-46CE-B0EC-AD6F092F51B3}",
"MerchantName": "iVeri",
"MerchantUSN": "2169017345",
"Acquirer": "NedbankPostilion",
"AcquirerReference": "31008:00660156",
"AcquirerDate": "20131007",
"AcquirerTime": "184550",
"DisplayAmount": "R 25.00",
"BIN": "504931",
"Association": "MasterCard",
“CardType": "Unknown Card Type",
"Issuer": "Unknown Issuer",
"Jurisdiction": "Local",
"PANMode": "Swiped,PIN,EncryptedTrack2",
"ReconReference": "00660156",
"CardHolderPresence": "CardPresent",
"MerchantAddress": "MERCHANT ADDRESS",
"MerchantCity": "Johannesburg",
"MerchantCountryCode": "ZA",
"MerchantCountry": "South Africa",
"ApplicationID": "{1D76A36F-F10E-4388-87F4-4675C78A5511}",
"Command": "Debit",
"Mode": "Live",
"RequestID": "{A832F735-9A17-429D-8C82-46C833271D31}",
"Result": {
"Status": "0",
"AppServer": "QAGW2012APP1",
"DBServer": "QAGW2012DB1",
"Gateway": "QA"
},
"PAN": "5049........0023"
}
}

api/transactions/{requestid}/receipt
Upload a Cardholder signature to be added to a MerchantReceipt linked to a transaction identified by the requestid.

JSON Request:
{
"Version": "2.0",
"CertificateID": "{7dcb6189-bfad-414b-b4ed-ea9d5875ea12}",
"Direction": "Request",
"Enquiry": {
"ApplicationID": "{1d76a36f-f10e-4388-87f4-4675c78a5511}",
"Command": "Debit",
"RequestID": "{A832F735-9A17-429D-8C82-46C833271D31}",
"CardholderName", "Russel King",
"SignatureImageFormat", "jpeg",
"SignatureImage", "hexified image data"
}
}


Parameter Description & Action


This section describes the various gateway parameters available. This is followed by a table of what input and output parameters are relevant for each action. Parameters are shown grouped according to their usage.



Parameter per Acton

M

Mandatory

O

Optional

C

Conditional

blank

not relevant


Context

Parameter

Authorisation with PAN

Authorisation with Track2

Authorisation with VisaCheckoutCallID

Additional Authorisation with TransactionIndex

AuthorisationReversal with TransactionIndex

Debit with PAN

Debit with Track2

Debit with PIN

Debit with VisaCheckoutCallID

Debit with TransactionIndex

Credit with PAN

Credit with Track2

Credit with TransactionIndex

Void

Balance Enquiry with PIN

PAN Enquiry with PAN

PANToken Enquiry

PAN Enquiry with Track2

Ping

Get Device PIN Key

ThreeDSecureCheckEnrollment

 

ThreeDSecureValidateAuthentication

 

RequestForDebit

MasterPassQuickResponseCode

MasterPassPaymentNotification

DynamicCurrencyConversion

MultiCurrencyPricing

Core

ApplicationID

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

 

M

M

M

M

M

M

M

Core

Category

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

Core

CertificateID

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

Core

Gateway

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

O

Core

Command

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

Core

Mode

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

M

Common

Amount

M

M

M

M

O

M

M

M

M

O

M

M

O

 

 

 

 

 

 

 

M

M

M

M

 

M

 

Common

AuthorisationCode

 

 

 

 

 

O

O

 

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

BudgetPeriod

O

O

O

O

 

O

O

 

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

CardSecurityCode

O

O

O

O

O

O

O

 

 

O

 

 

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

PAN

M

 

 

 

 

M

 

 

 

 

M

 

 

 

 

M

M

 

 

 

M

M

 

 

 

O

 

Common

Currency

O

O

O

 

 

O

O

O

O

 

O

O

 

 

O

 

 

 

 

 

M

M

M

M

 

M

 

Common

VisaCheckoutCallID

 

 

M

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

ExpiryDate

M

 

 

O

O

O

 

 

 

O

O

 

O

 

 

O

M

 

 

 

M

M

 

 

 

 

 

Common

CardholderName

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

M

 

 

 

 

Common

MerchantReference

M

M

M

M

M

M

M

M

M

M

M

M

M

 

 

 

 

 

 

 

M

M

M

M

M

 

 

Common

OriginalMerchantReference

C

 

 

 

 

C

 

 

 

 

C

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

MerchantTrace

O

O

O

O

O

O

O

O

O

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

OriginalMerchantTrace

 

 

 

 

 

 

 

 

 

 

 

 

 

C

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

OriginalRequestID

 

 

 

 

 

 

 

 

 

 

 

 

 

C

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

PurchaseDate

O

O

O

O

O

O

O

O

O

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

PurchaseTime

O

O

O

O

O

O

O

O

O

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

StartDate

O

 

 

O

O

O

 

 

 

O

O

 

 

 

 

O

 

 

 

 

 

 

 

 

 

 

 

Common

Terminal

O

O

O

O

O

O

O

O

O

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

Track2

 

M

 

O

O

 

M

M

 

O

 

M

O

 

M

 

 

M

 

 

 

 

 

 

 

 

 

Common

TransactionIndex

 

 

 

M

M

 

 

 

 

M

 

 

M

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

MobileMoneyID

 

 

 

 

 

 

 

 

 

 

 

 

 

O

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

MSISDN

 

 

 

 

 

C

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

PANFormat

O

 

M

 

 

O

 

 

M

 

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

PANMode

O

O

O

O

O

O

O

O

O

O

O

O

O

 

O

O

 

O

 

 

 

 

 

 

 

 

 

Common

CardHolderPresence

O

O

 

O

 

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Common

CardholderEmail

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

M

 

 

 

 

Common

OrderDescription

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

O

 

 

 

 

Common

AllowBudgetPeriod

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

O

 

 

 

 

Common

RequestExpiryDate

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

O

 

 

 

 

Common

CreateTransactionUrl

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

O

 

 

 

 

3DSecure

ElectronicCommerceIndicator

O

O

 

O

 

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

3DSecure

CardHolderAuthenticationData

O

O

 

O

 

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

3DSecure

CardHolderAuthenticationID

O

O

 

O

 

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

3DSecure

ThreeDSecure_RequestID

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

M

 

 

 

 

 

3DSecure

ThreeDSecure_SignedPARes

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

M

 

 

 

 

 

3DSecure

ThreeDSecure_DSTransID

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

3DSecure

ThreeDSecure_AuthenticationType

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

3DSecure

ThreeDSecure_VEResEnrolled

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

3DSecure

ThreeDSecure_ProtocolVersion

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

MasterPass

MasterPassAction

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

M

 

 

 

MasterPass

MasterPassMerchantID

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

M

 

 

 

MasterPass

MasterPassShortDescription

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

MasterPass

MasterPassCodeExpiryDate

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

MasterPass

MasterPassMerchantName

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

MasterPass

MasterPassCode

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

MasterPass

MasterPassTransactionID

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

POS

AccountType

 

 

 

 

 

 

 

O

 

 

 

 

 

 

O

 

 

 

 

 

 

 

 

 

 

 

 

POS

CashAmount

 

 

 

 

 

 

 

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

POS

DeviceFirmware

 

 

 

 

 

 

 

O

 

 

 

 

 

 

O

 

 

 

 

O

 

 

 

 

 

 

 

POS

DeviceFirmwareVersion

 

 

 

 

 

 

 

O

 

 

 

 

 

 

O

 

 

 

 

O

 

 

 

 

 

 

 

POS

DeviceMake

 

 

 

 

 

 

 

M

 

 

 

 

 

 

M

 

 

 

 

M

 

 

 

 

 

 

 

POS

DeviceSerialNumber

 

 

 

 

 

 

 

M

 

 

 

 

 

 

M

 

 

 

 

M

 

 

 

 

 

 

 

POS

DeviceCycle

 

 

 

 

 

O

O

O

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

POS

KeySerialNumber

 

 

 

 

 

 

 

C

 

 

 

 

 

 

C

 

 

 

 

 

 

 

 

 

 

 

 

POS

Track2KeySerialNumber

 

C

 

 

 

 

C

C

 

 

 

C

 

 

C

 

 

C

 

 

 

 

 

 

 

 

 

POS

PANKeySerialNumber

 

C

 

 

 

 

C

C

 

 

 

C

 

 

 

 

 

C

 

 

 

 

 

 

 

 

 

Procurement

CustomerReferenceIdentifier

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement

CustomerVATRegistrationNumber

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement

DestinationCountry

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement

DestinationZIPCode

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement

NationalTax

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement

NationalTaxIndicator

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement

OrderDate

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement

PurchaseIdentifier

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement

ShipFromZIPCode

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement

ShippingAmount

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement

ShippingTaxRate

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement

TransactionDiscount

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement

UniqueVATInvoiceReference Number

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement: LineItem

Discount

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement: LineItem

ItemCommodityCode

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement: LineItem

ItemDescriptor

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement: LineItem

ProductCode

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement: LineItem

Quantity

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement: LineItem

TaxRate

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement: LineItem

Total

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement: LineItem

UnitCost

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Procurement: LineItem

UnitOfMeasure

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Fleet

CustomerReferenceIdentifier

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Fleet: LineItem

ProductCode

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Fleet: LineItem

Quantity

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 

Fleet: LineItem

UnitCost

 

 

 

 

 

O

O

 

 

O

O

O

O

 

 

 

 

 

 

 

 

 

 

 

 

 

 


Point 3.

Point 4.


Ecommerce, Card Not Present


Sale/Purchase

 

M

Mandatory

O

Optional

C

Conditional

blank

not relevant

 

Context

Parameter

Debit with PAN

Debit with TransactionIndex

Void

Credit with PAN

Credit with TransactionIndex

Core

ApplicationID

M

M

M

M

M

Core

Category

M

M

M

M

M

Core

CertificateID

M

M

M

M

M

Core

Gateway

O

O

O

O

O

Core

Command

M

M

M

M

M

Core

Mode

M

M

M

M

M

Common

Amount

 M

 M

 

 M

 M

Common

CardSecurityCode

O

O


O

O

Common

PAN

M

M


M


Common

Currency

 M

 M

 

 M

 M

Common

ExpiryDate

 M

 M

 

 M

Common

MerchantReference

 M

 M

 

 M

 M

Common

OriginalMerchantReference

 

 

 M

 

 

Common

MerchantTrace

 O

 O

 

 O

 O

Common

OriginalRequestID

 

 

 M

 

 

Common

PANFormat

 

 M

 

 

 M

Common

TransactionIndex

 

 M

 

 

 M

 Common

 CardHolderPresence

 C

 C

 

 

 

Common

PaymentGatewayID

C

C

C

C

Common

WalletProvider

C

C


C

C

Common

TokenCrytogram

C

C


C

C

Common

ForeignRetailIndicator

C

C


C

C

Common

AuthorisationCode

O

O


O

O

Common

BudgetPeriod

O

O


O

O

Common

PANMode






Common

Terminal

O

O


O

O

Common

VisaCheckoutCallID

C

C


C

C

Common

PurchaseDate

O

O


O

O

Common

PurchaseTime

O

O


O

O

Common

StartDate

O

O


O

O

Common

MSISDN






Common

MobileMoney






Common

OrderDescription

O

O


O

O

ThreeDsecure

ElectronicCommerceIndicator

C

C

 

 

 

ThreeDsecure

CardHolderAuthenticationData

C

C

 

 

 

ThreeDsecure

CardHolderAuthenticationID

C

C

 

 

 

ThreeDsecure

ThreeDSecure_DSTransID

C

C

 

 

 

ThreeDsecure

ThreeDSecure_ProtocolVersion

C

C

 

 

 

ThreeDsecure

ThreeDSecure_RequestID

O

O

 

 

 

ThreeDsecure

ThreeDSecure_AuthenticationType

O

O

 

 

 

ThreeDsecure

ThreeDSecure_VEResEnrolled

O

O

 

 

 


Card Present Parameters


Sale/Purchase

 

Context

Parameter

Debit with Track2

Debit with TransactionIndex

Credit with Track2

Credit with TransactionIndex

Void

Core

ApplicationID

M

M

M

M

M

Core

Category

M

M

M

M

M

Core

CertificateID

M

M

M

M

M

Core

Gateway

O

O

O

O

O

Core

Command

M

M

M

M

M

Core

Mode

M

M

M

M

M

Common

Amount

 M

 M

 

 

 

Common

ExipiryDate

 M

 M

 

 

 

Common

Currency

 M

 M

 

 

 

Common

MerchantReference

 M

 M

 

 

 

Common

MerchantTrace

 O

 O

 

 

 

Common

BudgetPeriod

 O

 O

 

 

 

Common

OriginalMerchantTrace

 

 

 

 

 

Common

Track2

M

C

 

 

 

Common

PANMode

M

C

 

 

 

Common

Terminal

M

C

 

 

 

Common

AccountType

M

C

 

 

 

POS

CashAmount

O

O

 

 

 

POS

DeviceFirmware

O

O

 

 

 

POS

DeviceFirmwareVersion

O

O

 

 

 

POS

DeviceMake

 

 

 

 

 

POS

DeviceSerialNumber

 

 

 

 

 

POS

DeviceCycle

 

 

 

 

 

POS

KeySerialNumber

 

 

 

 

 

POS

Track2KeySerialNumber

 

 

 

 

 

POS

PANKeySerialNumber

 

 

 

 

 

POS

PinBlock

 

 

 

 

 

POS

EMV_AuthorisationRequestCryptogram

 

 

 

 

 

POS

EMV_ApplicationIdentifier

 

 

 

 

 

POS

EMV_ApplicationInterchangeProfile

 

 

 

 

 

POS

EMV_CardSequenceNumber

 

 

 

 

 

POS

EMV_ApplicationTransactionCounter

 

 

 

 

 

POS

EMV_ApplicationVersion

 

 

 

 

 

POS

EMV_CardHolderVerificationMethodRe sult

 

 

 

 

 

POS

EMV_CryptogramInformationData

 

 

 

 

 

POS

EMV_IssuerApplicationData

 

 

 

 

 

POS

EMV_IssuerApplicationData

 

 

 

 

 

POS

EMV_TerminalCapabilities

 

 

 

 

 

POS

EMV_TerminalType

 

 

 

 

 

POS

EMV_TransactionType

 

 

 

 

 

POS

EMV_TerminalVerificationResult

 

 

 

 

 

POS

EMV_UnpredictableNumber

 

 

 

 

 

POS

EMV_TransactionStatusInformation

 

 

 

 

 


QR Code - MasterPass


QR Code – MasterPass Parameters

 

Context

Parameter

MasterPassQuickResponseCode

MasterPassPaymentNotification

Credit with TransactionIndex

Void

Core

ApplicationID

M

M

M

M

Core

Category

M

M

M

M

Core

CertificateID

M

M

M

M

Core

Gateway

O

O

O

O

Core

Command

M

M

M

M

Core

Mode

M

M

M

M

Common

Amount

 

 

 

 

Common

ExipiryDate

 

 

 

 

Common

Currency

 

 

 

 

Common

MerchantReference

 

 

 

 

MasterPass

MasterPassAction

M

 

 

 

MasterPass

MasterPassMerchantID

M

 

 

 

MasterPass

MasterPassShortDescription

 

 

 

 

MasterPass

MasterPassCodeExpiryDate

 

 

 

 

MasterPass

MasterPassMerchantName

 

 

 

 

MasterPass

MasterPassCode

 

 

 

 

MasterPasss

MasterPassTransactionID

 

 

 

 



Request Payment – Divert Parameters

 

Context

Parameter

RequestForDebit

RequestForAuthorisation

Core

ApplicationID

M

M

Core

Category

M

M

Core

CertificateID

M

M

Core

Gateway

O

O

Core

Command

M

M

Core

Mode

M

M

Common

Amount

M

M

Common

Currency

M

M

Common

MerchantReference

M

M

Common

CardholderName

M

M

Common

CardholderEmail

C

C

Common

OrderDescription

O

O

Common

AllowBudgetPeriod

O

O

Common

RequestExpiryDate

O

O

Common

CreateTransactionUrl

O

O



Data Types

 
The following key table is used for data types:

Data Type

Description

A

Alpha only (A-Za-z)

AN

Alphanumeric (a-zA-Z0-9)

Base64

Base64 encryption of binary data

Boolean

True or False

Guid

Globally Unique Identifier: {[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}\}
(eg {8E51611F-E19A-4FF0-B229-6A69F42AAA62})

Hex

Hex (0-9A-Fa-f)

N

Numeric (Positive integer)

N.

Digits and dots (.) (e.g's 4242........4242, 1.0)

N:

Digits and colons

String

ANPS Free format string containing: Alpha, numeric, special and padding (printable ASCII)

Z

Positive or negative integer



Node Type

Set input parameter value

Get output parameter value

attribute

enterprise.setAttribute(..)

enterprise.getAttribute(..)

tag

enterprise.setTag(..)

enterprise.getTag(..)

parameter

enterprise.prepare(...)

N/A

attribute parameter

enterprise.prepare(...)

enterprise.getAttribute(..)

property

Use method or property of enterprise corresponding to the parameter

N/A

subtag

call enterprise.setTag(..) within
   enterprise.openElement(...)
   ...
   enterprise.closeElement()

N/A





Parameter Description 


Core Parameters


Core Parameters

 

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

ApplicationID 

Attribute 

parameter 

GUid 

38 

38 

Identification of the merchant’s configuration within the iVeri Gateway 

CertificateID 

property 

 

38 

38 

The iVeri CertificateID installed on the server communicating with the iVeri Gateway 

CertificatePath 

Property 

 

 

Valid Path to directory where the KeyStoreFile or CertificateFile exists on the filesystem 

CertificateFile 

Property 

 

 

Existing certificate file 

CertificatePassword 

Property 

 

 

Password of the certificate 

Gateway 

Property 

 

 

The name of the gateway connecting to. If not explicitly set, the default gateway is used. 

RequestID 

Attribute 

 

 

38 

38 

A unique identifier generated by the iVeri Gateway for this request 

Mode 

Attribute 

parameter 

 

The mode of the corresponding ApplicationID. See section 10.2 

 

TEST  

LIVE 

Category 

parameter  

 

 

50 

A categorisation of the request. Only required in conjunction with a prepare method. 

 

Transaction 

use if Command = 'Debit' or 'Credit' or 'Authorisation' or 'AuthorisationReversal' or 'Void' 

Enquiry 

use if Command = 'Balance', 'PAN' or 'PANToken' or ' 

‘AuthenticatedCollection' or ‘RequestForDebit’ OR  ‘AccountValidation’ 

 

System 

use if Command = 'Ping' 

Security 

use if Command = 'GetDevicePINKey' 

Command 

Attribute 

parameter 

 

 

The command specifying what should be done by the iVeri Gateway 

 

GetDevicePINKey 

Get DevicePINKey (use Category='Security') 

Ping 

Ping (use Category='System') 

Authorisation 

Authorisation (use Category='Transaction') 

AuthorisationReversal 

Authorisation Reversal (use Category='Transaction') 

Credit 

Credit (use Category='Transaction') 

Debit 

Debit (use Category='Transaction') 

Void 

Void (use Category='Transaction') 

Balance 

Balance Enquiry (use Category='Enquiry') 

PAN 

PAN Enquiry (use Category='Enquiry') 

PANToken 

PANToken Enquiry (use Category='Enquiry') 

AuthenticatedCollection 

AuthenticatedCollection:Enquiry (use Category='Enquiry') 

AccountValidation 

AccountValidation Enquiry (use Category = ‘Enquiry’) 

RequestForDebit 

RequestForDebit Enquiry (use Category = ‘Enquiry’) 

MasterPassQuickResponseCode 

MasterPass QuickResponseCode Enquiry (use Category = ‘Enquiry’) 

DynamicCurrencyConversion 

DynamicCurrencyConversion 



Common Parameters

 

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

Acquirer 

tag 

32 

The Acquiring system to which this transaction was routed by iVeri 

 

NBPostllionNBSA 

 

NBPostilion NB Zimbabwe 

 

NBPostilionUSD NB Zimbabwe 

 

CBZPostilion CBZ Zimbabwe 

 

CSCFIS CSC Lebanon 

 

NBPostilion iVeri SouthAfrica 

 

ICPSPwC CIM Mauritius 

 

OWWay4 IM Kenya 

 

NBPostilion NB Namibia 

 

 

 

AcquirerDate 

tag 

 

64 

The date that the Acquirer allocated to this transaction 

YYYYMMDD 

YearMonthDay 

AcquirerReference 

tag 

 

64 

A reference allocated by the Acquirer to this transaction with format specific to the acqiurer. It is a composite element consisting of a settlement cycle and a transaction trace. The cycle can be 5 digits (the acquirer batch number) or 8 digits (cycle end date). The trace is the significant part of the acquirer Retrieval Reference Number (RRN). The trace can be 8 digits (if the RRN starts with 0000) or 12 digits (the full RRN). 

 

CCCCC: TTTTTTTT 

CycleNumber: RRN8 (for Nedbank providers) 

yyyyMMdd:tttttttt 

CycleEndDate: RRN8 (for the TMS provider) 

yyyyMMdd:ydddhhtttttt 

CycleEndDate:RRN (for providers in general) 

 

 

AcquirerTime 

tag 

 

The time that the Acquirer allocated to this transaction 

HHMMSS 

HourMinuteSecond 

Amount 

tag 

12 

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

AuthorisationCode 

Tag 

AN 

The Authorisation Code issued by the Issuer to the Merchant either telephonically or electronically 

BudgetPeriod 

Tag 

The number of months over which the cardholder would like to pay the transaction off. See section 10.4 

 

0 

Default 

3 

 

6 

 

9 

 

12 

 

18 

 

24 

 

36 

 

 

CardSecurityCode 

Tag 

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

Currency 

Tag 

 

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

DisplayAmount 

Tag 

String 

 

30 

The Amount returned in a currency aware printable format 

ExpiryDate 

Tag 

The last month of the validity period of the card 

MMYY 

MonthYear 

 

MMYYYY 

MonthYear 

CardholderName 

Tag 

String 

 

50 

The name of the cardholder as embossed on the card. 

CardholderEmail 

Tag 

String  

 

125 

The email address of the cardholder 

OrderDescription 

Tag 

String  

 

250 

A brief description of the purchase made by the cardholder 

AllowBudgetPeriod 

Tag 

Boolean 

 

 

When this is true a ‘BudgetPeriod’ input field will be present on the CardDetails capture form. 

RequestExpiryDate 

Tag 

N 

The date after which the debit request will expire 

YYYYMMDD 

YearMonthDay 

CreateTransactionUrl 

Tag 

Boolean 

 

 

When this value is ‘true’ a ‘TransactionUrl’ will be returned to the merchant. If ‘false’ a debit request email will be sent to the ‘CardholderEmail’ 

TransactionUrl 

Tag 

String  

 

225 

The transaction url that the Cardholder must be redirected to perform a transaction when the command was ‘RequestForDebit’. This will be returned to the merchant in the response if the ‘CreateTransactionUrl’ parameter is set to ‘true’ 

MerchantName 

Tag 

String  

 

50 

The merchant name associated with the ApplicationID 

MerchantAddress 

Tag 

String  

 

50 

The merchant address associated with the ApplicationID 

MerchantCity 

Tag 

String 

 

50 

The merchant city associated with the ApplicationID 

MerchantCountryCode 

Tag 

String  

 

The merchant country code associated with the ApplicationID 

MerchantCountry 

Tag 

String 

 

50 

The merchant country name associated with the ApplicationID 

MerchantReference 

Tag 

String 

64 

A merchant generated identifier that is unique within a specified time period that identifies a transaction sequence.  In the case that the transaction is an Authenticated Collection this field will contain the 14-character long Contract Reference allocated by the Merchant for this transaction. 

OriginalMerchantReference 

Tag 

String 

64 

A merchant generated identifier of a previous transaction used in a Tokenized PAN transaction 

MerchantTrace 

Tag 

String  

64 

Unique merchant identification for the request 

MerchantUSN 

Tag 

String 

15 

The merchant USN associated with the ApplicationID 

OriginalMerchantTrace 

Tag 

String  

 

64 

A reference to the original MerchantTrace previously sent to the iVeri Gateway 

OriginalRequestID 

Tag 

Guid  

38 

38 

The RequestID that was returned as part of the original transaction 

PAN 

Tag 

N 

 

20 

Primary Account Number (eg Credit card number), may have been extracted from Track2. When this is an output parameter, then a section of it is dotted out, and safe to display or print 

PANMode 

Tag 

String 

128 

The mechanism by which the PAN was determined from the card. The value is a comma separated list of the following: 

 

Name 

 

Direction 

Description 

Keyed  

Input/Output 

Card number was keyed 

 

Tokenized 

Output 

PANFormat 'TransactionIndex', 'OriginalMerchantReference' or 'MSISDN' (non-registration) was specified in the request 

 

Swiped 

Input/Output 

Card was swiped. This means that a Track2 must be specified in the request. 

 

Dipped 

Input/Output 

Card was processed while in the card reader slot of the device. This means that a Track2 must be specified in the request. 

Tapped 

Input/Output 

Card was processed by a contactless device. This means that a24 Track2 must be specified in the request. 

ConstructedTrack2 

Output 

For when a partial Track2 is received in the request usually accompanied by a PINBlock as one of the legs of a PANFormat “MSISDN” transaction. 

CVV 

Output 

The CardSecurityCode tag had a value in the request 

PIN 

Output 

The PINBlock tag had a value in the request 

PINCapable 

Input/Output 

No online PIN or EMV data sent to the gateway, but the device is capable to process PIN. 

EMV 

Output 

 
EMV data were specified in the request. 

 

EMVFallback 

Output 

No EMV data specified in the request, but the service code of the request Track2 indicate a chip card. 

EncryptedPAN 

Output 

The value of the PAN tag in the request specified encrypted data 

EncryptedTrack2 

Output 

The value of the Track2 tag in the request specified encrypted data 

PurchaseDate 

Tag 

 

The date on which the purchase was made. Defaults to current Date 

 

MMDD 

 

MonthDay 

PurchaseTime 

Tag 

 

The time at which the purchase was made. Defaults to current Time 

HHMM 

HourMinute 

ReconReference 

Tag 

N 

Identifier that the Merchant is returned during a transaction and that also appears in the reconciliation information supplied by the Acquirer. Either assigned by the iVeri Gateway or derived from the specified MerchantReference. 

StartDate 

Tag 

A 

 

The date of the start of the validity period of the card number. The start date is not available on many cards, and will remain an optional parameter until the start date becomes more common 

 

MMYY 

MonthYear 

MMYYYY 

MonthYear 

Terminal 

Tag 

N 

Identifier optionally allocated by the merchant which is intended to group transactions together for reporting purposes in reconciliation statements. 

Track2 

Tag 

String 

 

39 

Track2 after being read by the swipe device from the magnetic stripe on the card (for card present transactions). It is inclusive of the beginning and end markers being ; and ? respectively. See section 10.3 

TransactionIndex 

Tag 

Guid 

38 

38 

Unique identifier allocated by iVeri for a series of related transactions. If PANFormat is 'TransactionIndex', TransactionIndex is used to locate a previous transaction for the PAN to be resolved. 

MobileMoneyID 

Tag 

N 

An additional transaction identifier returned for a PANFormat “MSISDN” transaction. This tag should be passed to the Gateway along with OriginalRequestID or OriginalMerchantTrace when the transaction needs to be Voided. 

MSISDN 

Tag 

String 

 

 

A mobile number required by PANFormat “MSISDN” transactions 

VisaCheckoutCallID 

Tag 

String  

48 

Visa Checkout transaction ID associated with a payment request. 

MasterPassTransactionID 

Tag 

N 

 

 

This is the MasterPass system transaction reference 

ForeignAmount 

Tag 

String  

11 

When doing a transaction in a foreign currency we need to specify the amount here in the foreign currency 

Mandatory when doing transaction in foreign currency 

 

ForeignCurrency 

Tag 

String 

When doing a transaction in a foreign currency we need to specify the foreign currency here 

Mandatory when doing transaction in foreign currency 

 

ForeignExchangeID 

Tag 

Guid 

38 

38 

Unique Identifier returned in the DynamicCurrencyConversion / MultiCurrencyPricing linked to the BaseAmount /BaseCurrency and the Amount and Currency in the current transaction request 

Mandatory when doing transaction in foreign currency 

 

PANFormat 

Tag 

String 

 

 

An enumeration specifying how to obtain the PAN details 

 

 

PAN 

Required tag: PAN. If PANFormat is not specified, this value is used if the PAN tag is set and the Track2 tag not set. 

 

Track2 

Required tag: Track2. If PANFormat is not specified, this value is used if the Track2 tag is set. 

VisaCheckoutCallID 

Required tags:  VisaCheckoutCallID 

The VisaCheckoutCallID is used to retireve the Payment Data from the Visa Checkout Process. 

 

MSISDN 

Required tag: MSISDN. If in addition, AccountType, PAN (full) and ExpiryDate are provided, the transaction also serves as a registration of the MSISDN, thereby enabling future transactions with MSISDN only. 

 

 

CardHolderPresence 

Tag 

String  

128 

Specify how the cardholder is involved when a virtual transaction is performed. This tag supersedes the ElectronicCommerceIndicator tag. The value is a comma separated list of the following: 

CardPresent 

Gets set in the output when a full Track2 was specified in the request. This value may also be set in the request when the card number was keyed on a POS device. 

 

 

 

 

 

CardNotPresent 

The physical plastic of the card was not present when the request was sent to the gateway. 

 

 

 

 

 

eCommerce 

Gets set in the output when one of the ElectronicCommerceIndicator values was specified in the request 

 

 

 

 

 

ThreeDSecure 

Encryption (SSL) used between CardHolder and Merchant. ThreeDSecure was successful 

 

 

 

 

 

ThreeDSecureAttempted 

Encryption (SSL) used between CardHolder and Merchant. ThreeDSecure was attempted unsuccessfuly 

 

 

 

 

 

SecureChannel 

Encryption (SSL) used between CardHolder and Merchant. ThreeDSecure not used 

 

 

 

 

 

ClearChannel 

No encryption used between CardHolder and Merchant 

 

 

 

 

 

MOTO 

Telephonic or mail order 

 

 

 

 

 

Recurring 

Transactions submitted by a merchant automatically 

 

 

 

 

 

 



Card Detail Parameters

 

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

Association 

tag 

string 

50 

The association to which the card number belongs e.g., VISA or Master card or American Express 

Bin 

Tag 

string 

The Bank Identification Number into which PANs are grouped. Generally, this is the first two to eight digits 

CardType 

tag 

String  

50 

A description of the type of the card used e.g., Credit Card, Maestro, Electron etc 

Issuer 

tag 

string 

50 

If the card is local this gives a description of the institution that issued this card 

 

Jurisdiction 

Tag 

String  

50  

Description of whether the card is a local or international card 



3DSecure Parameters

 

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

ElectronicCommerceIndicator 

tag 

 

More commonly known as the ECI, it describes for virtual transactions what steps were taken to secure and authenticate the transaction. Values are the following subset of CardHolderPresence values: ThreeDSecure, ThreeDSecureAttempted, SecureChannel and ClearChannel 

CardHolderAuthenticationData 

tag 

Base64 

28 

28 

For usage with Verified by Visa / MasterCard SecureCode. The CAVV or UCAF field depending on whether the card is VISA or Master card. Note: Original binary format length = 20 bytes. Mandatory when ElectronicCommerceIndicator = ThreeDSecure 

CardHolderAuthenticationID 

tag 

Base64 

28 

28 

For usage with Verified by Visa / MasterCard SecureCode. The Transaction ID. Note: Original binary format length = 20 bytes. Mandatory when ElectronicCommerceIndicator = ThreeDSecure  

ThreeDSecure_RequestID 

Tag 

Guid 

38 

 

The RequestID that was returned as part of the Enrollment Check that will be used to retrieve data for the Authentication Validation 

ThreeDSecure_ACS_URL 

Tag 

URL 

 

No Limit 

URL of the Access Control Server of the card-issuing bank where you need to send the ThreeDSecure_PAReq so that the customer can be authenticated. The field length can be very large. 

ThreeDSecure_PAReq 

Tag 

Base64 

 

No Limit 

Digitally signed payer authentication request message that contains a unique transaction ID.The field length can be very large. 

ThreeDSecure_SignedPARes 

Tag 

 Base64 

 

No Limit  

Digitally signed PARes message that contains the authentication result.The field length can be very large. 

ThreeDSecure_VEResEnrolled 

Tage 

Indicator that shows whether the cardholder is participating in 3DS. 


Result Parameters


Result Parameters

 

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

Code 

Attribute 

 

The numeric Result Code of the completed execution. See section 10.1 

Description 

Attribute 

String  

 

1024 

A description of the results of the completed execution. Only relevant where ResultStatus is 'Unsuccessful' [-1] or 'Successful with warning' [1] 

Source 

Attribute 

String  

 

138 

The source of the result 

Previous 

Attribute 

Boolean 

 

 

In most cases returns false, indicating that the other result values refer to the immediately completed execution. For advanced usage within a Reprint, to indicate whether the result returned refers to the current execution, or a previous execution. 

Status 

Attribute 

 

The status of the completed execution 

 

 

 

 

 

-1 

Unsuccessful 

0 

Successful 

1 

Successful, with warning 



UPOP SecurePlus Parameters

 

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

UPOP_TransactionTime 

tag 

String  

 

 

The time when the Merchant sends the transaction. 

Date and time formatted as an ISO 8601 combined date and time string using the extended format. 

 

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

 

              - YYYY = year 

              - MM = month 

              - DD = day 

              - hh = hour 

              - mm = minutes 

              - ss = seconds 

 

UPOP_RelatedTransactionType 

tag 

String 

Related Transaction Type. One of: 

 

              - Purchase 

              - Pre-authorization 

 

              The corresponding UnionPay protocol values are: 

 

              - 01: Purchase 

              - 02: Pre-authorization 

 

UPOP_RequestID 

Tag 

Guid 

38 

 

The RequestID that was returned as part of the Request Creation that will be used to retrieve data for the Authentication Validation 

UPOP_FrontUrl 

Tag 

URL 

 

256 

UPOP send the transaction result notification to the URL via cardholder’s browser 

UPOP_BackUrl 

Tag 

URL 

 

256 

UPOP send the transaction result notification to the URL via system 

UPOP_ACPReq 

Tag 

Base64 

 

No Limit 

The Authentication Request message to be posted to the UPOP authentication server 

UPOP_Endpoint 

Tag 

URL 

 

 

The UPOP authentication server endpoint where the Authentication Request message must be posted via cardholder’s browser 

UPOP_ACPRes 

Tag 

Base64 

 

No Limit 

The Authentication Response message received from the UPOP authentication server 



Masterpass Parameters

 

Parameter

Node Type

Data Type

Min Length

Max Length

Description

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 



ForeignExchange Parameters

 

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

Currency 

Subtag  

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

Amount 

subTag 

11 

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

ForeignExchange 

Tag 

AN 

 

 

Contains a collection of ForeignExchangeItems 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 

 






CyberSource Parameters

 

Parameter 

Node Type 

Data Type 

Required/Optional  

Max Length 

Description 

DeliveryMethod 

subTag 

255 

Physical or Virtual 

DeviceFingerprintID 

SubTag 

AN 

88 

Session ID for the fingerprint. 

BillTo_FirstName 

SubTag 

AN 

60 

First name of cardholder 

BillTo_LastName 

SubTag 

AN 

60 

Last name of cardholder 

BillTo_Street 

subTag 

AN 

60 

Street address of cardholder 

BillTo_City 

subTag 

AN 

60 

Billing city for cardholder 

BillTo_State 

subTag 

AN 

State or province of the cardholder. Required for U.S. and Canada. 

Use the two-character state, province, or territory codes. 

 

BillTo_Country 

subTag 

AN 

Billing country for cardholder. Use the two-character country codes. 

BillTo_PostalCode 

subTag 

AN 

10 

 Postal code of the billing address. Required only if the BillTo_Country field is US or CA 

BillTo_Email 

subTag 

AN 

100 

Email address of the cardholder 

BillTo_IPAddress 

subTag 

AN 

15 

 IP address of the cardholder as reported by your Web server via socket information. 

Note: If any of the fields marked in Red is unavalable all the fields in Red will be replaced with defaults specified by CyberSource 



POS Parameters

 

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

DeviceFirmware 

Tag 

String  

 

64 

The firmware (software) currently loaded on the device. This may be set as an integer 

DeviceFirmwareVersion 

Tag 

String  

 

64 

The version of the firmware (software) currently loaded on the device. 

DevicePINKey 

Tag 

Hex 

32 

32 

Master/Session encryption specific: The device PIN Key encrypted under the device master key i.e. DMK(DPK) 

MACDevicePINKey 

Tag 

Hex 

Master/Session encryption specific: The MAC of the device PIN Key i.e. MAC(DPK) 

AccountType 

Tag 

32 

The type of account that this transaction relates to (known to the cardholder 

 

Cheque  

 

Not specified  

Savings 

Credit  

AvailableBalance 

Tag 

 

12 

The available amount in the cardholders account given in the smallest unit of currency of the cardholder (not necessarily the currency of the merchant) 

DisplayAvailableBalance 

Tag 

String 

 

25 

The AvailableBalance returned in a currency aware printable format 

CashAmount 

Tag 

 

12 

The Cash (back) portion of the Amount. Subject to the constraint: 0 <= CashAmount <= Amount 

CurrentBalance 

Tag 

 

12 

The current balance in the cardholders account given in the smallest unit of currency of the cardholder (not necessarily the currency of the merchant) 

DisplayCurrentBalance 

Tag 

String  

 

25 

The CurrentBalance returned in a currency aware printable format 

DeviceMake 

Tag 

String  

 

64 

The manufacturer of the device (terminal). e.g. Dione / Sagem 

DeviceSerialNumber 

Tag 

 String  

 

64 

The serial number of the device (terminal) 

DeviceCycle 

Tag 

String  

20 

 

the current batch id of the device (terminal) 

PINBlock 

Tag 

Hex 

16 

16 

The cardholders PIN encrypted using the current device pin key 

KeySerialNumber 

Tag 

Hex 

20 

20 

DUKPT encryption specific: Mandatory input parameter needed in decryption of a DUKPT PINBlock. 

Track2KeySerialNumber 

Tag 

Hex 

20 

20 

DUKPT Track2 encryption specific: Mandatory input parameter needed in decryption of a DUKPT Track2. 

PANKeySerialNumber 

Tag 

Hex 

20 

20 

UKPT PAN encryption specific: Mandatory input parameter needed in decryption of a DUKPT PAN. 



EMV Parameters

 

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

EMV_AuthorisationRequestCryptogram 

Tag 

Hex 

 

16 

EMV tag 9F26 

EMV_ApplicationIdentifier 

Tag 

Hex 

 

32 

EMV tag 9F26 

EMV_ApplicationInterchangeProfile 

Tag 

Hex 

 

EMV tag 82 

EMV_CardSequenceNumber 

Tag 

Hex 

 

EMV tag 5F34 

EMV_ApplicationTransactionCounter 

Tag 

Hex 

 

EMV tag 9F36 

EMV_ApplicationVersion 

Tag 

Hex 

 

EMV tag 9F08 

EMV_CardHolderVerificationMethodResult 

Tag 

Hex 

 

EMV tag 9F34 

EMV_CryptogramInformationData 

Tag 

Hex 

 

EMV tag 9F27 

EMV_IssuerApplicationData 

Tag 

Hex 

 

64 

EMV tag 9F10 

EMV_TerminalCapabilities 

Tag 

Hex 

 

6 or 8 

EMV tag 9F33 

EMV_TerminalType 

Tag 

 

EMV tag 9F35 

EMV_TransactionType 

Tag 

 

EMV tag 9C 

EMV_TerminalVerificationResult 

Tag 

Hex 

 

10 

EMV tag 95 

EMV_UnpredictableNumber 

Tag 

Hex 

 

EMV tag 9F37 

EMV_TransactionStatusInformation 

Tag 

Hex 

 

EMV tag 9B 

EMV_IssuerAuthenticationData 

Tag 

Hex 

 

16 or 32 

EMV tag 91 

EMV_IssuerScriptTemplate1 

Tag 

Hex 

 

999 

EMV tag 71 

EMV_IssuerScriptTemplate2 

Tag 

Hex 

 

999 

EMV tag 72 

EMV_ResponseCode 

Tag 

AN 

 

EMV tag 8A 

 

 

 

 

 

 



Airline Data

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

PassengerName 

subTag 

AN 

60 

Passenger's first name. 

PrimaryTicketNumber 

subTag 

AN 

60 

 

FirstDepartureLocationCode 

subTag 

AN 

32 

 

FirstArrivalLocationCode 

subTag 

AN 

32 

 

OfficeIATANumber 

subTag 

AN 

32 

 

OrderNumber 

 

 

 

 

 

PlaceOfIssue 

 

 

 

 

 

DepartureDate 

 

 

 

 

 

Note: The fields in Blue will only be used when doing CyberSource Advanced Fraud Screening. 

CompleteRoute 

 

 

 

 

 

DepartureTime 

 

 

 

 

 

JourneyType 

 

 

 

 

 




Procurement Parameters

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

CustomerReferenceIdentifier 

Tag 

AN 

 

17 

Description allocated by the merchant to be printed on the Cardholders statement 

CustomerVATRegistrationNumber 

Tag 

AN 

 

13 

The VAT registration number of the Customer if available 

DestinationCountry 

Tag 

The ISO code for the country of residence of the Merchant. e.g., ZA, US, GB 

DestinationZIPCode 

Tag 

AN 

10 

The Customers Destination ZIP code 

NationalTax 

Tag  

12 

The VAT amount of the transaction in the currency's smallest denomination. Depending on the NationalTaxIndicator this may be included or in addition to the Amount field 

NationalTaxIndicator 

Tag 

Indicates whether VAT is applicable to this transaction. 

 

0 

NationalTax is NOT included 

1 

NationalTax is included 

OrderDate 

Tag 

The date that the order was placed. This is not necessarily the same as the PuchaseDate. Defaults to current Date 

PurchaseIdentifier 

Tag 

AN 

25 

Optional description allocated by the Merchant to be displayed on the Merchants statement.  Defaults to MerchantReference. 

ShipFromZIPCode 

Tag 

AN 

10 

The ZIP code of the Merchant (Shipping source ZIP code) 

ShippingAmount 

Tag 

12 

The amount charged to the customer for shipping charges in the currency's smallest denomination. 

ShippingTaxRate 

Tag 

 

The VAT rate that applies to the ShippingAmount. It is a percentage and not the actual value. The value is the rate multiplied with 10000. 

TransactionDiscount 

Tag 

12 

Discount value for the transaction, it is the result of individual line-item percentage discounts applied to line items. In the currency’s smallest denomination 

UniqueVATInvoiceReferenceNumber 

Tag 

AN 

15 

The invoice number allocated by the merchant and appears on the merchant’s invoice given to the customer. This is an optional field is independent of the Merchant Reference. 





Procurement LineItems Parameters

 

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

Discount 

subTag 

0  

12 

The total discount for the line item in the currency's smallest denomination. 

ItemCommodityCode 

subTag 

The ISO commodity code for the line-item unit 

ItemDescriptor 

subTag 

26 

A description for the line-item unit. 

ProductCode 

subTag 

AN 

12 

The merchant's code for the line-item unit. 

Quantity 

subTag 

The total number of line-item units. 

TaxRate 

subTag 

The VAT rate applicable to the line item. The value is the rate multiplied with 10000. 

Total 

subTag 

12 

The total amount for the line item in the currency's smallest denomination. The value equals Quantity x UnitCost - Discount. 

UnitCost 

subTag 

12 

The cost of a line-item unit in the currency's smallest denomination. 

UnitOfMeasure 

subTag 

AN 

12 

The measurement unit description. 

PassengerFirstName 

subTag 

AN 

60 

Passenger's first name. 

PassengerLastName 

subTag 

AN 

60 

Passenger's last name 

PassengerID 

subTag 

AN 

32 

ID of the passenger to whom the ticket was issued. For example, you can use this field for 

the frequent flyer number 

 

PassengerStatus 

subTag 

AN 

32 

our company's passenger classification, such as with a frequent flyer program. In this case, 

you might use values such as standard, gold, or platinum. 

 

PassengerType 

subTag 

AN 

32 

Passenger classification associated with the price of the ticket. You can use one of the 

following values: 

•  ADT: Adult 

•  CNN: Child 

•  INF: Infant 

•  YTH: Youth 

• STU: Student 

•  SCR: Senior Citizen 

• MIL: Military 

 

Note: The fields in Blue will only be used when doing CyberSource Advanced Fraud Screening. 



AuthenticatedCollectionData Parameters

 

Parameter 

Node Type 

Data Type 

Required/Optinal   

Max Length 

Description 

AccountNumber 

subTag 

AN 

R  

19 

The account number that the payor is agreeing to allow the payee debit. 

DebtorIdentification 

SubTag 

AN 

35 

Some data to identify the payor e.g., ID Number 

DebtorIdentification 

subTag 

AN 

12 

The maximum amount that the payor is agreeing to in the smallest unit of the currency specified (eg in cents) 

 

 

 

 

 

 



Fleet Parameters

 

Parameter 

Node Type 

Data Type 

Min Length 

Max Length 

Description 

CustomerReferenceIdentifier 

Tag 

AN 

 

Contains two subfields and is in the format: “Type” + “Odometer Reading”. 

 

Type 

Private (P) or Business (B). Max Length = 1. Data Type = A 

Odometer reading 

Odometer reading. Max Length = 7. Data Type = N 

Fleet  LineItem  Parameters 

Quantity 

Subtag 

he total number of line item units 

QuantityDecimalPlaces 

subtag 

The number of implied decimals in the Quantity 

UnitCost 

subtag 

10 

The cost of a line item unit in the currency's smallest denomination 

ProductCode 

subTag 

AN 

64 

The iVeri Product Code for the Fleet LineItem. The latest set of iVeri Fleet Product Codes can be obtained via the Inventory download command (Only use the ProductCodes with Type='Fleet'). The set at time of writing is provided here. 

 

FLEET OIL 

Oil 

FLEET SERVICE 

Service 

FLEET TYRES 

Tyres 

FLEET ACCIDENTS 

Accidents 

FLEET ACCESSORIES 

Accessories 

FLEET BRAKES 

Brakes 

 

FLEET EXHAUSTS 

Exhausts 

FLEET SHOCK ABSORBERS 

Shock absorbers 

FLEET BATTERIES 

Batteries 

FLEET GLASS 

Glass 

FLEET TRUCK STOP 

Truck Stop 

FLEET FORECOURT SHOP 

Forecourt Shop 

FLEET HOTEL EXPENSES 

Hotel Expenses 

FLEET TOLL GATE 

Toll Gate 

FLEET MISCELLANEOUS 

Miscellaneous 

FLEET PREMIUM 

Premium Fuel 

FLEET REGULAR 

Regular Fuel 

FLEET SASOL 

Sasol Fuel 

FLEET DIESEL 

Diesel Fuel 

FLEET UNLEADED SUPER 

Unleaded Super Fuel 

FLEET UNLEADED PREMIUM 

Unleaded Premium Fuel 

FLEET AVIATION 

Aviation Fuel