Supported Prompts

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

x	Prompt Description
1	Amount
2	Please enter new total
3	Total
4	amount again
5	Please enter
6	Add
7	Input
9	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

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.

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.

Key	Expected Result
	Transaction where a response is received and the Result:Code indicates success.
	Transaction where a response is received and the Result: Code indicates Failure.
	Transaction where a response is received but the Result:Code indicates a Timeout.
	Transaction where no response is received. e.g. No card is presented to the Device and the web service call to Indigo times out.

Initial Authorisation

Test Case	a	b	Description
1.0	Authorisation		Successful response.
1.1	Authorisation	AuthorisationReversal	A successful Authorisation is obtained but an exception in the Integrator's system requires that a reversal of that Authorisation must be performed.
1.2	Authorisation		Declined e.g. No Funds in the card. Check that the Integrators system does not consider this to be a successful transaction.
1.3	Authorisation	Void	Timeout received from Acquiring Host. The Integrator must send a Void to ensure that the transaction is rolled back by Indigo.
1.4	Authorisation		Card not presented to Device. In this case no response at all is received from Indigo.

Follow-up Debit

Test Case	a	b	c	Description
2.0	Authorisation	Debit		Successful response received to both the Authorisation and the Sale thereafter.
2.1	Authorisation	Debit	Void	Successful response received to both the Authorisation and Sale but then an exception in the Integrators system occurs requiring that the Void is executed to ensure no financial implications for the cardholder.
2.2	Authorisation	Debit		Success response to the Authorisation but the Sale returns a Failure
2.3	Authorisation	Debit	Void	Successful response to the Authorisation but a timeout occurs when processing the Sale and the Integrator must execute a void to make sure that there are no financial implications to the cardholder.

Initial Debit

Test Case	a	b	Description
3.0	Debit		Successful transaction.
3.1	Debit	Void	Successful Sale but then an exception in the Integrators system occurs and the Integrator must reversal the Debit so that there is no impact on the cardholders account
3.2	Debit		Transaction Declined e.g No funds available. This must not be marked as a successful sale by the Integrator.
3.3	Debit	Void	Timeout from Acquiring Host. The Integrator must ensure that a Void for this transaction is executed.
3.4	Debit		Card not presented to Device and the web service eventually times out and no transaction is actually even attempted.

Follow-up Credit

Test Case	a	b	c	Description
4.0	Debit	Credit		Success response from a Sale and then the Integrator gives the money back in the Refund. Note the delay that may occur between Sale and Refund.
4.1	Debit	Credit	Void	Success then Success then Rollback due to exception in Integrators systemSuccess. The Void would only apply to the Credit so the merchant would effectively still have the money obtained during the Sale.
4.2	Debit	Credit		Success then Failure of the Credit. The money must be returned to the customer some other way.
4.3	Debit	Credit	Void	Timeout from Acquiring Host. The Void would only apply to the Credit so the merchant would effectively still have the money obtained during the Sale.

Initial Credit

Test Case	a	b	Description
5.0	Credit		Success Payment of money to the cardholder
5.1	Credit	Void	Exception in the Integrators system leading to the reversal of the Payment
5.2	Credit		A payment to the cardholder has been Declined.
5.3	Credit	Void	Timeout from Acquiring Host, this needs to be resolved with the use of a Void to unwind the transaction.
5.4	Credit		Card not presented to Device and the web service times out.

In addition to the above there are some general tests that need to be performed to take care of the following situations.

Transactions being performed by two devices simultaneously to check that if there are two transactions being performed at exactly the same time that the Integrators systems as well as the Indigo server handles this successfully.
Error code 255 indicating a system error. These generally indicate an actual programming error and the details of what has happened must be logged and a notification to someone created (e.g. email) so that the exact cause can be investigated, and the programming issue resolved.
Void must be executed until either a positive response is received OR 24 attempts have been exhausted OR more than 24 hours has elapsed. It is recommended that an Integrator puts voids onto a queue and then has a separate process which sends the voids to Indigo until one of the above conditions is met.
If the Integrator wants to offer cash back as an option then the setting of the “CashAmount” parameter must be tested.
If the Integrator wants to offer budget period as an option then the setting of the “BudgetPeriod” parameter must be tested.
If the Integrator wants to obtain data input from the POS device then the GetData command must be tested.
If the Integrator makes use of the Cancel command to return control to the calling process in the event that a card is not presented to the POS device e.g. Cash is tendered, the this should be tested as well.

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

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

Result Codes

The design of the iVeri Gateway is intended to give the merchant/integrator enough information to be able to respond to the merchant and/or card holder with a sensible course of action to take without delving too deeply into what the reason behind the result code is.

The following is the list of Result Codes.

Result Code	Result Description	Invalid Data submitted, change the data, and resubmit	Resubmit without changing the data after a period. Stop if this Result Code is returned continuously.	Merchant configuration/Development problem. Stop processing this transaction and resolve the specific issue, if possible, before re-attempting the transaction.	Stop processing. Re-submitting the transaction will not change the result.	Notes
0	Approved/Successful				X
1	Timeout waiting for response		X			Either stop the transaction or wait a while before re-submitting. Do not re-submit forever, have a limit in place of how many times a transaction can be re-submitted.
2	Gateway unreachable		X			Either stop the transaction or wait a while before re-submitting. Do not re-submit forever, have a limit in place of how many times a transaction can be re-submitted.
3	Hot card				X
4	Denied				X
5	Please call	X				Merchant can phone their acquiring bank to obtain a telephonic authorisation. If this is not possible then the transaction should be Denied.
7	Invalid Authentication Data	X				Card security code and/or 3D secure data is incorrect.
8	Card Type not accepted			X		The Card cannot be accepted either because the Merchant has not signed up with the association, the card type cannot be accepted on the channel that the merchant is using, or the Acquirer does not support this card type.
9	Unable to process the transaction		X			Either stop the transaction or wait a while before re-submitting. Do not re-submit forever, have a limit in place of how many times a transaction can be re-submitted. Will also be returned if the request is cancelled.
10	Card blocked			X		The card is being blocked either by the iVeri Gateway, the Acquirer or the Issuer. This is NOT a hot card but one that has been blocked for some reason.
11	Invalid Amount			X		Amounts of zero or where the cash amount exceeds the total amount are not accepted.
12	Invalid Budget Period	X				The budget period chosen is not supported.
13	Void unsuccessful				X	Command Void
14	Invalid Card Number	X				The card number fails the Luhn Mod10 check, is too short or too long or contains invalid characters.
15	Invalid Track2	X				The track2 fails the Luhn Mod10 check, is too short or too long or contains invalid characters.
16	Invalid Expiry Date/Card Period	X				The expiry date submitted is malformed, contains invalid characters or simply incorrect.
17	Invalid Account Selection	X				Ask the cardholder to choose another account.
18	Invalid Authorisation code	X				The acquiring institution does not accept the authorisation code submitted due to length or character restrictions.
19	Incorrect PIN	X				Resubmitting a transaction whose response code is “Incorrect PIN” repeatedly will result in the cardholder’s card being locked and the cardholder will have to contact their issuing bank to unlock their card.
22	EMV not supported			X		EMV Cryptogram submitted
23	Card information not present				X	Tokenized PAN submitted but no record of the actual PAN can be found.
26	Contactless not allowed				X	The use of contactless for this transaction is not supported and the customer must try again by dipping or swiping their card.
255	General Error (Exception)			X
7	Approved in spite of Invalid Authentication Data				X	Allow the cardholder to depart with the goods.
21	Approved but Cash Denied				X	Hand over the goods but DO NOT hand over the cash.
25	Approved but Identification Required				X	Ask the cardholder for identification before allowing the cardholder to depart with the goods.

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.

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.

Additional Information