Generic POS Channel API Developers Guide

Matches:

Introduction
Introduction
Network Topology
Network Topology
Latency, Jitter and Lost Packets
How to measure the network performance
How to measure the network performance
Transaction Life Cycle
Transaction Life Cycle
REST Endpoints
REST Endpoints
Parameter description
Parameter description
Example Message Format
Example Message Format
Initial Transaction
Initial Transaction
Authorisation
Authorisation
JSON Request
JSON Request
JSON Response
JSON Response
Payment
Payment
JSON Request
JSON Request
JSON Response
JSON Response
Followup
Followup
Settlement of a previously successful Authorisation
Settlement of a previously successful Authorisation
JSON Request
JSON Request
JSON Response
JSON Response
Refund of a previously successful Sale Transaction
JSON Request
JSON Request
JSON Response
JSON Response
Reversal of a previously successful Authorisation
Reversal of a previously successful Authorisation
JSON Request
JSON Request
JSON Response
JSON Response
Sale
Sale
JSON Request
JSON Request
JSON Response
JSON Response
Void
Void
JSON Request
JSON Request
JSON Response
JSON Response
Cancel
Cancel
JSON Request
JSON Request
JSON Response
JSON Response
GetData
GetData
JSON Response
JSON Response
GetHMAC
GetHMAC
JSON Request
JSON Request
JSON Response
JSON Response
GetSystemInfo
GetSystemInfo
JSON Request
JSON Request
JSON Response
JSON Response
Appendix A
Appendix A
Ingenico RA1 based devices
Ingenico RA1 based devices
Appendix B – QA Environment for Development and Certification
Appendix B – QA Environment for Development and Certification
Appendix C – Test Plan
Appendix C – Test Plan
Appendix D – Receipt Requirements
Appendix D – Receipt Requirements
Appendix F – Reconciliation
Appendix F – Reconciliation
Appendix G – Postman
Appendix G – Postman

Introduction
Introduction
Network Topology
Network Topology
Latency, Jitter and Lost Packets
How to measure the network performance
How to measure the network performance
Transaction Life Cycle
Transaction Life Cycle
REST Endpoints
REST Endpoints
Parameter description
Parameter description
Example Message Format
Example Message Format
Initial Transaction
Initial Transaction
Authorisation
Authorisation
JSON Request
JSON Request
JSON Response
JSON Response
Payment
Payment
JSON Request
JSON Request
JSON Response
JSON Response
Followup
Followup
Settlement of a previously successful Authorisation
Settlement of a previously successful Authorisation
JSON Request
JSON Request
JSON Response
JSON Response
Refund of a previously successful Sale Transaction
JSON Request
JSON Request
JSON Response
JSON Response
Reversal of a previously successful Authorisation
Reversal of a previously successful Authorisation
JSON Request
JSON Request
JSON Response
JSON Response
Sale
Sale
JSON Request
JSON Request
JSON Response
JSON Response
Void
Void
JSON Request
JSON Request
JSON Response
JSON Response
Cancel
Cancel
JSON Request
JSON Request
JSON Response
JSON Response
GetData
GetData
JSON Response
JSON Response
GetHMAC
GetHMAC
JSON Request
JSON Request
JSON Response
JSON Response
GetSystemInfo
GetSystemInfo
JSON Request
JSON Request
JSON Response
JSON Response
Appendix A
Appendix A
Ingenico RA1 based devices
Ingenico RA1 based devices
Appendix B – QA Environment for Development and Certification
Appendix B – QA Environment for Development and Certification
Appendix C – Test Plan
Appendix C – Test Plan
Appendix D – Receipt Requirements
Appendix D – Receipt Requirements
Appendix F – Reconciliation
Appendix F – Reconciliation
Appendix G – Postman
Appendix G – Postman

Introduction

Network Topology

The generic solution is premised on the following network topologies and depends on whether or not the Indigo Server and/or the POS Server, if it exists, are located inside or outside of the merchant’s location.
At the point that a payment by the customer must be made the POS Till or POS Server will, using the protocol described in this document, contact the Indigo Server which will control the appropriate device to prompt for payment from the cardholder. Once the required card details have been collected on the device the Indigo server will process the transaction to the iVeri Gateway before returning a response to the POS Till or POS Server which will then be able to close the invoice created and indicate to the cashier at the POS Till that the invoice has been paid.

Illustration 1 shows where all the POS Tills are able to connect directly to the Indigo Server locally and the POS Till manages the creation of an invoice which needs to be paid by a customer. In this scenario there is no POS Server and the POS Tills effectively act independently of each other.

Illustration 2 shows where all the POS Tills are able to connect directly to the remote Indigo Server and the POS Till manages the creation of an invoice which needs to be paid by a customer. In this scenario there is no POS Server and the POS Tills effectively act independently of each other.

Illustration 3 shows where the POS Tills connect directly to the POS Server which, in turn, connects to the local Indigo Server. In this case the POS Server acts on behalf of the POS Tills, creating the invoice which needs to be paid by a customer and connecting to the Indigo Server on behalf of the POS Till which is performing the transaction. In this scenario the POS Server co-ordinates the creation of invoices between the POS Tills.

Illustration 4 shows where the POS Tills connect directly to the POS Server which, in turn, connects to the remote Indigo Server. In this case the POS Server server acts on behalf of the POS Tills, creating the invoice which needs to be paid by a customer and connecting to the Indigo Server on behalf of the POS Till which is performing the transaction. In this scenario the POS Server co-ordinates the creation of invoices between the POS Tills.

Latency, Jitter and Lost Packets

Latency, Jitter and Lost Packets

With the above four scenarios in mind the solution relies on the quality of the connections from the POS Till, POS Server and the Devices to the Indigo Server as well as from the Indigo Server to the iVeri Gateway. If any of these connections suffers from high latency or dropped packets the solution as a whole will not perform as required so it is imperative that the networks on which the solution is deployed have adequate bandwidth as well as that they have low latency and zero packet losses. This means that if the networks are shared with other equipment it is important to understand what that equipment is doing and when it is doing it so that it doesn’t impinge on the operational requirements of the Indigo Solution.

The interaction between the Device and the Indigo server amounts to approximately 6K bytes which is spread over about 15 seconds which includes the activation of the device, inserting the card, choosing the account type, entering the PIN, performing the transaction and then completing the transaction to the device. As a rough guide this means that one needs 0.4KB/s of bandwidth per transaction that is being processed. The bandwidth requirements are therefore modest but what is critical is the latency, jitter and dropped packets between the Device and the Indigo Server.

How to measure the network performance

The following commands should be executed on the Indigo server and the destination should be the connected Devices. If there is any variation from a network point of view between the location of the various devices connecting to an Indigo Server, then they should be tested separately.
Windows
PS C:\Users\roland> ping -n 1000 -l 512 192.168.128.14

Pinging 192.168.128.14 with 512 bytes of data:
Reply from 192.168.128.14: bytes=512 time=1ms TTL=63
Reply from 192.168.128.14: bytes=512 time<1ms TTL=63
Reply from 192.168.128.14: bytes=512 time<1ms TTL=63
Reply from 192.168.128.14: bytes=512 time<1ms TTL=63
.
.
.
Reply from 192.168.128.14: bytes=512 time<1ms TTL=63
Reply from 192.168.128.14: bytes=512 time<1ms TTL=63
Reply from 192.168.128.14: bytes=512 time<1ms TTL=63

Ping statistics for 192.168.128.14:
Packets: Sent = 1000, Received = 1000, Lost = 0 (0% loss),
Approximate round trip times in milli-seconds:
Minimum = 0ms, Maximum = 438ms, Average = 2ms
PS C:\Users\roland>

Linux
roland@roland-mbp1604:~$ ping -s 512 -v -c 1000 192.168.128.14
PING 192.168.128.14 (192.168.128.14) 512(540) bytes of data.
520 bytes from 192.168.128.14: icmp_seq=1 ttl=64 time=0.556 ms
520 bytes from 192.168.128.14: icmp_seq=2 ttl=64 time=0.407 ms
520 bytes from 192.168.128.14: icmp_seq=3 ttl=64 time=0.458 ms
.
.
.
520 bytes from 192.168.128.14: icmp_seq=998 ttl=64 time=0.395 ms
520 bytes from 192.168.128.14: icmp_seq=999 ttl=64 time=0.391 ms
520 bytes from 192.168.128.14: icmp_seq=1000 ttl=64 time=0.398 ms

--- 192.168.128.14 ping statistics ---
1000 packets transmitted, 1000 received, 0% packet loss, time 998997ms
rtt min/avg/max/mdev = 0.291/0.401/0.669/0.050 ms
roland@roland-mbp1604:~$

Assessment
There are two criteria that need to be evaluated from the results obtained.
Packet Loss – The percentage of lost packets between the devices and the Indigo server.
Maximum Latency – The Maxium Latency is the upper limit of 3 standard deviations (i.e. it will include 99.7% of all response times) from the average and can be calculated as
MaximumLatency=AverageLatency+(3"*" StandardDeviation)
The Average Latency is labeled as “avg” and the Standard Deviation is labeled as “mdev” in the ping results above.
For the Indigo Server to work reliably with the devices measured, the Packet Losses must be 0% and the measured Maximum Latency must not exceed 100ms. The lower the measured value of Maximum Latency, the more responsive and reliable the device will subjectively appear to be. Conversely the higher it is the worse the performance and the poorer the user experience.
Note that the sensitive data being sent from the Device through the Indigo server and to the iVeri Gateway is encrypted already and no benefit would be derived from running this data over additional VPN encryption. In fact, transporting the data over a VPN may increase latency by as much as 30% over and above the latency that would exist if a VPN was not used.

Transaction Life Cycle

The following diagrams describe how related stages can be executed during the life cycle of a transaction. There are three diagrams to illustrate the three possible starting points that a transaction life cycle can start from and, once it has started, what follow-up transactions can be performed on them. The data which links transactions together is the MerchantReference which is generated by the POS Till and/or MerchantTrace which is generated by the Indigo Server and returned in appropriate response messages to the POS Till.

There is a subtle distinction between a Refund (command = Credit) and Payment (command = Credit); a Refund is the term used when returning money previously taken from a cardholders account by a Sale (command = Debit). A Payment is not linked to any previous transaction and is simply giving money to a cardholder.

The void is used when there is a system problem e.g. no response received to make absolutely sure that systems do not get out of sync where the POS Till or POS Server thinks that a transaction failed but the Issuers host thinks that a transaction was successful. As such, the void must be executed during the same business day as the transaction which is being voided i.e. it must be sent fairly close to the transaction it relates to. Another instance in which a void command would be used by the POS Till or POS Server would be if something went wrong in the POS systems after a successful financial transaction was completed. In this case, the POS Till or Server needs to roll the entire transaction back so that the net effect is as if nothing ever happened. If no response was returned by the channel, then a Void can be done with the Original transaction's MerchantReference otherwise the OriginalMerchantTrace will be used to void the transaction. A Void command can be used irrespective of whether a card has been presented or not. If no card has been present then the Void functions a lot like a Cancel but if a card has been presented then it will ensure that whatever the state of the transaction, it will be reversed.

The flow just shows what can be done, not what must be done. In most transactions and at most merchants the only transaction really used is the Sale (command = Debit). It is only at a later stage if there happens to be some kind of problem with the goods not being delivered or the amount being incorrect that a Refund or a Payment (command = Credit) may be used to correct the situation.

The basic difference between a void, Refund and Payment is the following:
• Void - The transaction against which the void was processed will not show up on the cardholder’s statement.
• Refund - The transaction against which the refund was processed will show up on the cardholder’s statement as will the refund so the cardholder will have two transactions of opposite sign showing up on their statement.
• Payment – Since this is not linked like a Refund to a previous transaction the cardholder would only see money being deposited into their account.

Tap-In/Tap-Out transaction processing can be performed by executing the GetHMAC command on both the tap-in and the tap-out and using the returned HMAC, which is the same for both calls, to determine the duration that needs to be charged for. The result of this is the amount to be charged which is passed, along with the HMAC and all the other parameters into the “Debit” command which works out whether the cardholder needs to authenticate the transaction by means of a PIN based on the card requirements as well as the value or whether the transaction can be processed without having to prompt for a second presentation of the card and the relevant authentication.
If a device has been activated to prompt for a transaction but the customer chooses to use another payment medium, then the transaction can be cancelled. Note that this can only be used if a card is not presented at all, if a card is presented then a Void should be used in preference to a Cancel command. Note that calling the “Cancel” command after a card has been dipped, swiped, or tapped will NOT “Void” the transaction. The “Cancel” command is ONLY to be used to regain control in the event that a card transaction is not being performed. In the event that a card transaction is “in process” the “Cancel” command will return a HTTP Status code 405 “Method Not Allowed” and the calling application should thereafter execute a “Void” command to ensure that the card transaction is rolled back. If “Cancel” is successful, then an HTTP Status code of 200 would be returned and if the “Cancel” is malformed or missing essential information then an HTTP Status code of 400 “Bad Request” will be returned. To add, transaction processing should not be init

The GetSystemInfo command can be used to expose information about the status of the estate and the connection to the gateway. Because of this it returns two sets of information. One relates to the devices that are connected to the Indigo server and the other relates to the connection from the Indigo server to the configured iVeri Gateway. Note that the DeviceInfo response is an array with a length of one if a single device’s status is requested but will generally be of variable length according to the number of devices connected. In the case that all devices are requested and there are not any devices connected at all this could be an array of zero length. Note also that GatewayInfo is also an array; usually there will only be one item in this array, but it is possible that there are multiple items. This call initiates a message to each connected device so if there are multiple devices that are disconnected this call could take some time to return because each request to a disconnected device would take some time. This also means that use of this call must not be too frequent i.e. not less than a minute between calls to GetSystemInfo to prevent monitoring interfering with the actual operation of Indigo.

REST Endpoints

• Only one REST endpoint exists on the Indigo server and it will be at http://ipaddress/rest/transaction/transact or https://ipaddress/rest/transaction/transact where ipaddress is the local or external ip address or dns of the Indigo server as appropriate. Note that only TLS1.2 or above should be used.
• Only POST method is supported, and the data submitted must be in JSON format.
• The response from the Indigo server will also be in JSON format
• In the request header set request.Accept = "application/json";
• in the request header set request.ContentType = "application/json";

The design of this interface is to use synchronous REST calls to perform either an “Authorisation”, “Debit” or “Credit” which leads to a potential problem in the event that a card is not presented and something else, e.g. cash, is tendered instead. There are three mechanisms than an integrator may use to avoid or address this:
• Avoid the problem altogether by only activating the POS device if the customer intends to pay with a card.
• Set the timeout on the REST call to the Indigo server to a value that gives the cardholder enough time to insert/tap their card and for the actual transaction to happen. Typically, a value of more than 60 seconds on the REST timeout is recommended. If a customer does not present a card this will eventually timeout and return control to the Integrator.
• Set the timeout on the REST call to the Indigo server to a value that gives the cardholder enough time to insert/tap their card and for the actual transaction to happen. Typically, a value of more than 60 seconds on the REST timeout is recommended. If a customer does not present a card the Integrator can regain control by executing a “Cancel” command which will cause the POS device specified to return immediately instead of waiting for the timeout to expire, assuming that there are no “Authorisation”, “Debit” or “Credit” commands in pro

Parameter description

Command	Authorisation		Debit		Credit		AutohorisationReversal		Void		GetData		Cancel		GetHMAC		GetSystemInfo
Parameter	In	Out	In	Out	In	Out	In	Out	In	Out	In	Out	In	Out	In	Out	In	Out	Description
AcquirerCode		O		O		O		O		O									The Acquirer ISO code returned for this transaction. Note that the success or failure of this transaction MUST be determined by the Result Code and NOT by the AcquirerCode nor the AcquirerDescription. This is only made available as extra information and may not exist in all response.
AcquirerDescription		O		O		O		O		O									The Acquirer ISO description returned for this transaction. Note that the success or failure of this transaction MUST be determined by the Result Code and NOT by the AcquirerCode nor the AcquirerDescription. This is only made available as extra information and may not exist in all response.
AcquirerReference		O		O		O													The unique reference number allocated by the Acquirer to this transaction. A composite element whose format is dependent on the particular acquirer to which this transaction was routed. The contents of this can, in some cases, be used to group transactions together to arrive at the total amount of money that should be deposited into the merchants bank account per settlement period and card type. See Appendix F - Reconciliation
Amount	M	E	M	E	M	E													The total value of the transaction in the smallest unit of the currency specified. E.g. $10.01 meaning ten dollars and one cent would be submitted as 1001. Note that this value includes any cashback portion that may be set so if the sale is for $10.00 and the cardholder wants cashback of $5.00 then the value set in this field would be $15.00 which without the decimal would be 1500.
ApplicationIdentifier		O		O		O													EMV Tag 9F06 (AID)
ApplicationLabel		O		O		O													EMV Tag 50
AuthorisationCode		O		O		O													The Authorisation Code issued by the Issuer to the Merchant and may be viewed by the merchant as a guarantee of funds for a limited period of time.
BudgetPeriod	O	E	O	E															The number of months over which the carholder wishes to pay off the total amount to the issuing bank. This should be one of the following values [1\|3\|6\|12\|18\|24\|36]. If a value is submitted which the issuer does not support, it is likely that the Issuer will default the request to no budget period.
CardAcceptorID		O		O		O													The cardacceptorid assigned to this merchant at the acquirer. Commonly referred to as the merchantid
CardholderName		O		O		O													The name of the Cardholder obtained from Track1 if available.
CardholderVerificationMethod		O		O		O													EMV Tag 9F34 (CVM)
CashAmount			O	E															The portion of the total value that is to be dispensed to the cardholder as cash. This is often referred to as a cashback transaction. This is also in the smallest unit of the currency specified.
Code		M		M		M		M		M		M				M			The numeric Result Code of the completed execution. Note that Code is contained within the Result node i.e. it is one level below the other data items described in this list. The “Cancel” command is unique in that the only indication of success is to query the HTTP Status which will return a 200 if the “Cancel” command was successful.
Command	M	E	M	E	M	E	M	E	M	E	M	E	M		M	E	M	E	Authorisation, Debit, Credit, AuthorisationReversal, Void, GetData, Cancel, GetHMAC, GetSystemInfo
ConnectedSince																		M	The date and time at which a connection from the device was established or, in the case of gateway, the date and time of the last change of status. This can be used to determine how long the gateway has been up or down relative to the current time. In the case of a device it can be used to determine how long the current connection has been up.
CryptogramInformationData		O		O		O													EMV Tag 9F27 (CID)
Currency	O		O		O		O												The currency that a transaction must be processed in. This must be indicated with the Alpha currency code e.g USD or ZAR to indicate US Dollar or South African Rand. This will be validated against the set of allowed currencies for a merchant. Once a currency has been set, all related transactions MUST use the same currency. If this is not set then the default currency for the mechant will be used for the transaction.
Data												O							The value as returned by the device. This parameter will be returned in response to a GetData command request.
Description		M		M		M		M		M		M				M			A description of the results of the completed execution. Only relevant where Code is not a 0 which indicates a approved transaction. Note that Description is contained within the Result node i.e. it is one level below the other data items described in this list.
DeviceSerialNumber	M	E	M	E	M	E	M	E	M	E	M	E	M		M	E	O		The serial number of the device (terminal) that is printed on the reverse of the device. It is assumed that the mapping of the POS Till at which the customer interaction is taking place and the nearest device that will be used to perform the transaction is kept and maintained on the POS Till or Server. This is an optional parameter to GetSystemInfo and, if set to “”, will return information on all connected devices. If set to an actual DeviceSerialNumber it will only return information for the specific device as well as the gateway information.
DisplayAmount		O		O		O													A correctly formatted version of the Amount as far a currency symbol and number of decimal places.
DisplayCashAmount		O		O		O													A correctly formatted version of the CashAmount as far a currency symbol and number of decimal places.
GatewayDNS																		M	The currently configured gateway DNS or IP address on the Indigo server.
HMAC			O													O			The HMAC of the PAN of the card presented for payment.
LastTransactionEnd																		M	The date and time at the end of the last transaction processed on a specific connection from a device. Aside from being useful to calculate the elapsed time since a transaction was last processed on a specific device this is useful for working out how long transactions are taking.
LastTransactionStart																		M	The date and time at the start of the last transaction processed on a specific connection from a device. This, used in conjunction with the LastTransactionEnd, can be used to work out how long the user experience is taking. Note that this includes all the time from the time a cardholder is prompted to start a transaction to the time that it is finally completed including time taken to enter the PIN, choose an account, choose a budget period etc.
Latency																		M	In the case of a device, this is the time in milliseconds that it takes to obtain the date and time from the device. This latency is updated at the start of each transaction and is not to be confused with a network ping latency. In the case of gateway this is the time in milliseconds for the “Ping” command to obtain a response from the configured gateway. Again, this isn’t to be confused with a network ping latency.
MerchantName		O		O		O													The name fo the merchant that should appear on the cardholder’s statement.
MerchantReference	M	E	M	E	M	E	O	E	O	E									A merchant generated identifier that is unique within a specified time period that identifies a transaction. The same MerchantReference can be used throughout the lifecycle of a transaction e.g. the same value used for Authorisation, then the Debit relating to the Authorisation and then the Credit relating to the Debit is accepted.
MerchantTrace		O		M		M													Unique merchant identification for the request generated by and returned by the Indigo Server.
OriginalMerchantTrace			O	E			O	E	O	E									The MerchantTrace returned in a previously executed transaction that the merchant wants to do a follow-up on. For a follow-up transaction the use or OriginalMerchantTrace is mandated however, for a “Void”, Indigo uses two methods to lookup a previous, related transaction. It first tries to use OriginalMerchantTrace and if that is unsuccessful or OriginalMerchantTrace is missing, then it will attempt to lookup the data based on MerchantReference. At least one of these two data elements MUST be present in the “Void” message in order for Indigo to find the related transaction.
PAN		M		M		M													Primary Account Number (eg Credit card number), may have been extracted from Track2. When this is an output parameter it will have been sanitized and is safe to display, store and print.
PANSequenceNumber		O		O		O													EMV Tag 5F34 (PSN)
Product		M		M		M													The name of the channel responding to this request within Indigo.
Prompts											M								The index of the Prompt to display on the device. This parameter is required when the command is GetData. The list of valid values is contained in Appendix A. This is a JSON array of prompts in the format ["05","4D"] indicating display prompt “05” on line 1 and “4D” on line 2.
SignatureRequired		O		O		O													Determines if a signature panel must be printed on the merchant receipt for this transaction. The value returned in this field will be either “True” or “False”
SocketAddress																		M	The IP address and port from which the device established the connection.
Status																		M	A textual description of the state of the device/gateway at the time of the call to GetSystemInfo. In the DeviceInfo section this will be the status of a device. In the case of the GatewayInfo section this indicates whether communications to the gateway is up or down.
Terminal	O	E	O	E	O	E													Used to group transactions together for reporting purposes independently of the physical device (DeviceSerialNumber) at which a transaction was actually processed.
TerminalVerificationResult		O		O		O													EMV Tag 95 (TVR)
TransactionCertificate		O		O		O													EMV Tag 98 (TC)
TransactionDateTime		O		O		O													The date and time as determined by the acquirer for this transaction in “YYYY-MM-DD HH:MM: SS” formatted local time.
TransactionIndex		O		O		O													Unique identifier generated on the iVeri Gateway and allocated for a series (Authorisation, Debit and Credit) of related legs of a transaction. This can be used as the UTI (Unique Transaction Indicator) required to be printed on receipts.
Transactions																		M	The number of transactions that have been processed on the device in question since the device last connected to the Indigo server.
TransactionStatusInformation		O		O		O													EMV Tag 9B (TSI)
TransactionTypeDescription		O		O		O													A cardholder/merchant friendly version of Command + CashAmount that describes the transaction being performed e.g. Sale, Refund, Authorisaction, Sale with Cashback etc.
Version		M		M		M												M	The version of the Indigo software responding to this request in the case of a Transaction being processed. In the case of GetSystemInfo this is the Make, Model and version of the software running on the device.

Example Message Format

Initial Transaction

Authorisation

JSON Request

{
"Command": "Authorisation",
"DeviceSerialNumber": "81546628",
"MerchantReference": "Roland20190212.1",
"Currency”: “ZAR”,
"Amount": 1001,
"BudgetPeriod" : 0,
"CashAmount": 0,
"Terminal" : "Roland"
}

JSON Response

{
    "TransactionStatusInformation": "F800",
    "MerchantReference": "Roland20190212.1",
    "DisplayCashAmount": "R 0.00",
    "CardAcceptorID": "1732668",
    "AuthorisationCode": "228849",
    "Product": "Indigo",
    "TransactionDateTime": "2019-02-12 08:00:48",
    "DeviceSerialNumber": "81546628",
    "PANSequenceNumber": "00",
    "Result": {
        "Description": "Approved",
        "Code": "0"
    },
    "CardholderName": "22112016/P.               ",
    "CardHolderVerificationMethod": "410302",
    "SignatureRequired": "false",
    "TransactionTypeDescription": "Authorisation",
    "MerchantName": "ArchRetail",
    "TerminalVerificationResult": "0880008000",
    "Version": "0482.01",
    "TransactionIndex": "{B4767088-68BC-40FD-A4A3-695B0822BF18}",
    "AuthorisationRequestCryptogram": "5E3C53B0D0160098",
    "TransactionCertificate": "{8a80fe66-4032-4cd9-b9f6-763762417e46}",
    "ApplicationLabel": "VISA      ",
    "Amount": 1001,
    "ApplicationIdentifier": "A0000000031010",
    "MerchantTrace": "292732.287654448218",
    "Terminal": "Roland",
    "CryptogramInformationData": "40",
    "DisplayAmount": "R 10.01",
    "Command": "Authorisation",
    "AcquirerReference": "01431:09014049",
    "BudgetPeriod": 0,
    "PAN": "4923........1826",
    "CashAmount": 0
}

{
“Command” : “GetData”,
“DeviceSerialNumber” : “81546628”,
“Data” : “690825518708425”
}

GetHMAC

JSON Request

{
"Command": "GetHMAC",
"DeviceSerialNumber": "81535719"
}

JSON Response

GetSystemInfo

JSON Request

{
“Command” : “GetSystemInfo”,
“DeviceSerialNumber” : “”,
}

JSON Response

{
"GatewayInfo": [
{
"Status": "Up",
"StatusSince": "2019-02-12 03:22:45",
"GatewayDNS": "https://portal.iveri.net%22%2C/
"Name": "Gateway Provider",
"Latency": 124
},
{
"Status": "Up",
"StatusSince": "2019-02-12 03:22:47",
"GatewayDNS": "https://portal.iveri.net%22%2C/
"Name": "NBPostilion NBSouthAfrica Gateway Provider",
"Latency": 93
}
],
"DeviceInfo": [
{
"Status": "Disconnected",
"Transactions": 11,
"LastTransactionEnd": "2019-02-11 14:38:51",
"LastTransactionStart": "2019-02-11 14:38:30",
"Version": "IPP350 - RA12105",
"ConnectedSince": "2019-02-11 13:13:50",
"DeviceSerialNumber": "81528455",
"SocketAddress": "192.168.128.85:1030",
"Latency": 312
},
{
"Status": "Idle",
"Transactions": 0,
"LastTransactionEnd": "",
"LastTransactionStart": "",
"Version": "IPP350 - RA11603",
"ConnectedSince": "2019-02-12 00:00:33",
"DeviceSerialNumber": "81546628",
"SocketAddress": "192.168.128.77:3742",
"Latency": 0
},
{
"Status": "Idle",
"Transactions": 0,
"LastTransactionEnd": "",
"LastTransactionStart": "",
"Version": "IPP350 - RA11605",
"ConnectedSince": "2019-02-12 00:00:38",
"DeviceSerialNumber": "81540356",
"SocketAddress": "24.141.44.64:4327",
"Latency": 0
},
{
"Status": "Idle",
"Transactions": 0,
"LastTransactionEnd": "",
"LastTransactionStart": "",
"Version": "IPP350 - RA11605",
"ConnectedSince": "2019-02-12 00:00:41",
"DeviceSerialNumber": "81537057",
"SocketAddress": "41.76.207.121:1787",
"Latency": 0
},
{
"Status": "Idle",
"Transactions": 0,
"LastTransactionEnd": "",
"LastTransactionStart": "",
"Version": "IPP350 - RA12105",
"ConnectedSince": "2019-02-12 00:00:43",
"DeviceSerialNumber": "81528407",
"SocketAddress": "154.70.210.218:4145",
"Latency": 0
},
{
"Status": "Idle",
"Transactions": 0,
"LastTransactionEnd": "",
"LastTransactionStart": "",
"Version": "IPP350 - RA12105",
"ConnectedSince": "2019-02-12 00:00:46",
"DeviceSerialNumber": "81528351",
"SocketAddress": "105.187.120.113:3472",
"Latency": 0
},
{
"Status": "Idle",
"Transactions": 0,
"LastTransactionEnd": "",
"LastTransactionStart": "",
"Version": "IUN2X0 - RA11605",
"ConnectedSince": "2019-02-12 01:58:58",
"DeviceSerialNumber": "20605360",
"SocketAddress": "93.63.159.172:37658",
"Latency": 0
}
]
}

Appendix A

The prompts are specific to devices so depending on which devices are attached to the Indigo server will determine which prompts are used. These prompts are, in general, loaded onto the device at initialisation so if this has not been done then prompts will not be supported. There is a hardcoded default prompt so that if the Index used from the list below does not happen to be loaded on the device or does not exist on the device then this prompt will be used as a generic request for data to be entered.

Ingenico RA1 based devices

Index	Prompt Description
01	Amount
02	Please enter new total
03	Total
04	amount again
05	Please enter
06	Add
07	Input
09	Balance
10	Tip
11	Gratuity
12	Service
13	Donation
20	Waiter ID
21	Waiter logon
22	Table number
23	Bill number
24	Location reference
25	Tab Number
26	Operator ID
37	Split by
38	number of parties
39	to pay
3A	Auth code
3B	Cashback
3C	Due
3D	Maximum
3E	Minimum
3F	Multiples of
40	Format
41	Date
42	Incorrect
43	ID incorrect
44	Number incorrect
45	Bill not found
46	Cash
47	Card
48	Cheque
49	Voucher
4A	Payment
4B	Refund
4C	Voucher number
4D	Identity code
4E	Kilometers
4F	Car number
50	Product code
51	Number of items
52	Room number
53	Plu number
Default	Input

Appendix B – QA Environment for Development and Certification

During the development and certification phases of an integration project the Indigo server will be located within iVeri's QA environment and a Merchant Profile for the Integrator performing the integration must be created on iVeri's QA Gateway as well as on the iVeri QA Indigo Server and the resulting credentials distributed to the Integrator. This must be performed by iVeri Support who can be contacted at assist@iveri.com. Please make sure in all communication with Support that they must deal with QA Indigo and the QA Gateway.
Network wise, the Integrator must ensure that the POS/Till system which will be communicating to the Indigo server using the Generic POS Channel protocol has outbound internet access to the iVeri QA Indigo Server. In a similar fashion, the Integrator must also ensure that outbound access to the iVeri QA Indigo server is also available to the device, being either Miura or Ingenico, that is going to be used.
The actual DNS names, IP addresses and ports that are required are slightly different depending on whether Miura or Ingenico devices are going to be deployed. The Miura devices use MPI application and protocol whereas the Ingenico devices use the RA1 application and protocol.

Appendix C – Test Plan

The purpose of the following section is to validate the implementation of the Generic POS Channel protocol for the transaction sets chosen by the Integrator. An Integrator may choose to only implement a subset of all the Test Cases (1, 2, 3, 4 and 5) below but, having chosen a Test Case, all sub Test Cases and the transaction types applicable to these Test Case must be performed. By way of example, if an Integrator only wants to perform Debits then only Test Case 3 comprising 3.0, 3.1, 3.2, 3.3 and 3.4 need to be tested and logs for these submitted. In this case logs for 3.0a, 3.1a, 3.1b, 3.2a, 3.3a, 3.3b, and 3.4a would need to be submitted.
Integrators should keep logs of all requests sent to the Indigo Server as well as the responses received and the data and time of submission and receipt of these messages. These logs must be submitted to iVeri Support assist@iveri.com who will create a project within iVeri's Redmine System, validate and attach the logs submitted. Any logs not submitted indicate that the Integrator does not intend to use the transaction types omitted and these will be removed from the Merchants Profile on the iVeri Gateway leaving the Transaction Types for which logs have been received.

Appendix D – Receipt Requirements

At the conclusion of each transaction a customer receipt for the cardholder to keep as a record of the transaction needs to be printed. In addition, a merchant receipt for the merchant to keep as a record of the transaction needs to be printed as well. Not all fields are returned for every transaction depending on the type of transaction, the result and other circumstances so, in the event that a field is not returned in the Response then it is not required that it be printed on the receipts.

Data Element	Source	Customer Receipt	Merchant Receipt	Notes
AcquirerReference	Response	Y	Y	If available
Address	Merchant	Y*	Y*
ApplicationIdentifier	Response	Y*	Y*	If available
ApplicationLabel	Response	Y*	Y*	If available
AuthorisationCode	Response	Y	Y	If available
BudgetPeriod	Input	Y*	Y*
CardAcceptorID	Response	Y*	Y*	If available
CardholderName	Response	Y*	Y*	If available
CardholderVerificationMethod	Response	Y*	Y*	If available
Code	Response	Y*	Y*	Always present
CryptogramInformationData	Response	Y*	Y*	If available
Description	Response	Y*	Y*	Always present
DeviceSerialNumber	Input	Y*	Y*
DisplayAmount	Response	Y*	Y*	Always present
DisplayCashAmount	Response	Y*	Y*	If available
MerchantName	Response	Y*	Y*	Always present
MerchantReference	Input	Y*	Y*
PAN	Response	Y*	Y*	Always present
PANSequenceNumber	Response	Y*	Y*	If available
Product	Response	Y*	Y*	Always present
SignatureRequired	Response	N	Y	If available
TerminalLocation	Merchant	Y*	Y*
TerminalVerificationResult	Response	Y*	Y*	If available
TransactionCertificate	Response	Y*	Y*	If available
TransactionDateTime	Response	Y*	Y*	Always present
TransactionIndex	Response	Y*	Y*	If available
TransactionStatusInformation	Response	Y*	Y*	If available
TransactionTypeDescription	Response	Y*	Y*	Always present
VATNumber	Merchant	Y*	Y*
Version	Response	Y*	Y*	Always present

* Must appear on both Approved and Declined transaction receipts

Appendix F – Reconciliation

The Indigo Server as well as the iVeri Gateway operates in Host Settlement rather than Terminal Settlement mode which means that a transaction is settled in the cycle that the Host is in when a transaction arrives at the Host. The cycle into which a transaction’s settlement will fall is allocated at the time of the transaction and returned in the AcquirerReference number which is a composite field consisting of the Settlement Cycle Number and the Transaction Trace assigned by the Acquirer.

For the Integrator to be able to generate statements which match the bank statement the integrator needs to produce reports based on the Settlement Cycle number received from Indigo at the time of the transaction. By doing this the value of the settlement deposited into the merchants account can be shown to be the sum of successful financial transactions which have the same Settlement Cycle.

Appendix G – Postman

Developers may want to test the protocol independent of their implementation by making use of Postman.

When configuring Postman, the Headers must have an additional attribute added to set Content-Type to the value “application/json” as shown below.

The Body should be set to the JSON as defined in this document to execute the command that is being tested as shown below:

The result received in the response is displayed in the pane below the request. In this case the device 20605360 is not online so the result informs us of that.