Migrating from a previous CCV integration

How to migrate to Viva from a CCV integration.

• Overview
• List of methods and signatures
  • PingTerminal
  • PingTerminal(Timeout)
  • StartCardServiceFlow
  • StartGetStatusFlow
  • StartRestartTerminalFlow
• Get Support

Overview

Migrating to the Viva POS API from a previous integration of CCV POS terminals - if you’re running a CCV card terminal, the below reference guide explains how you integrate your cash register or ordering application with one of Viva’s POS terminals.

List of methods and signatures

• PingTerminal
• PingTerminal(Timeout)
• StartCardServiceFlow
• StartGetStatusFlow
• StartRestartTerminalFlow

PingTerminal

//This method checks if the terminal is live on the network
public Boolean PingTerminal()

Description

Connection test with terminal.

Parameters

None.

Return

true if terminal answers PING, false if no answer received.

PingTerminal(Timeout)

//This method checks if the terminal is live on the network and answers within a defined timeout
public Boolean PingTerminal(Int32 Timeout)

Description

Connection test with terminal with defined timeout.

Parameters

Return

True if terminal answers PING within the defined timeout; false if no answer received.

StartCardServiceFlow

//This method starts a card service flow. Used to make a transaction
public CardServiceResponse StartCardServiceFlow( String WorkstationID,
CardServiceRequestType RequestType, LanguageCode LanguageCode,
Int32 ShiftNumber,
Int32 ClerkID,
PrinterStatus PrinterStatus, JournalPrinterStatus JournalPrinterStatus, EJournalStatus EJournalStatus,
TextLine PrinterTicketHeader1*,
TextLine PrinterTicketHeader2*,
TextLine PrinterTicketHeader3*,
TextLine PrinterTicketHeader4*,
TextLine PrinterTicketHeader5*,
TextLine PrinterTicketFooter1*,
TextLine PrinterTicketFooter2*,
TextLine PrinterTicketFooter3*,
TextLine PrinterTicketFooter4*,
TextLine PrinterTicketFooter5*,
Currency Currency,
Decimal TotalAmount)

*Optional

Description

Starts a transaction.

Parameters

*Optional but if one is present all others have to be too.

Return

CardServiceResponse: This object content complete XML and parsed XML from the terminal with following items:

• StringWorkstationID: Echoed from request message
• StringRequestID: Echoed from request message
• StringRequestType: Echoed from request message
• StringOverallResult: Mandatory. Result of the requested operation with following values:

String TerminalID: Conditional. Terminal ID of the terminal

String STAN: Conditional. Counter maintained by the terminal which is incremented by one for each transaction. Corresponds to the Trx. Seq-Cnt in Ticket and Journal and to the in e-journal.

String LanguageCode: Conditional. This attribute shows the language chosen on the terminal by the cardholder.

String Currency: Required.

String TotalAmount: Conditional. EP2 allows to add a tip amount to the original transaction amount. In this case the value of the element ‘TotalAmount’, in the ‘CardServiceResponse’ differs from the value in the request. The total transaction amount in the ‘CardServiceResponse’ is equal to the total of the original transaction amount and the extra tip amount.

String TimeStamp: Required. Date and time. Same as printed on the transaction receipt.

String ApprovalCode: Conditional. The attribute ‘ApprovalCode’ contains the code that is issued by the Acquirer to identify the transaction. Corresponds to the Auth. Code: in Ticket and Journal and to the in e-journal.

String TrxReferenceNumber: Conditional (Only EP2). Reference number provided by the acquirer. Present only for on-line transactions. Corresponds to the Trx. Ref-No: in Ticket and Journal and to the < TransactionRefNumber> in e-journal.

String MaskedCardNumber: Conditional (Only C-TAP). The masked card number is in the response as reference. The way of masking is determined by the acquirer settings and can even contain a full PAN if the acquirer settings allow so.

String AcquirerBatch: Conditional. (Only C-TAP) The ‘AcquirerBatch’ is a batch number created by the host system of Equens or CCV Pay and normally contains the Booking Period Number of the related host system. The Booking Period Number shows the business day of the banks in which the transaction is captured.

String CardCircuit: Conditional. The attribute ‘CardCircuit’ shows which card brand is used by the cardholder during the transaction. Examples are “BANK”, “VISA”, “ECMC” (for Mastercard), etcetera.

String ReceiptCopies: Conditional. The attribute ‘ReceiptCopies’ indicates the total number of receipts that should be printed. For successful PIN-based transaction this number will be “1”. For successful signature based transactions this number will be “2” (one merchant receipt and one customer receipt).

String RequestSignature: Conditional. The optional attribute ‘RequestSignature’ indicates if a signature of the cardholder is needed. When this Boolean attribute is “true” the POS itself shall create a box containing the message “VRAAG HANDTEKENING”. Although it is mandatory to show this text at least six seconds to the cashier, it is advised to keep this box available on the screen until the cashier presses/clicks it away.

When this text occurs on the screen the cashier shall ask the cardholder to sign the receipt in the signature box on the ticket and check the signature against the signature available on the card. A combination of the flags ‘RequestSignature’ and ‘RequestIdentification’ is possible. String OriginalWorkstationID: Retrieve the result of the last transaction registered by the PINPad when RepeatLastMessage function is used.

String OriginalRequestID: Retrieve the result of the last transaction registered by the PINPad when RepeatLastMessage function is used. This attribute is very important to check, to see if the last PINPad registered transaction does match the ‘RequestID’ of the transaction with unknown result.

String OriginalRequestType: Retrieve the result of the last transaction registered by the PINPad when RepeatLastMessage function is used. This attribute shows the transaction type of the last PINPad registered transaction. String OriginalOverallResult: Retrieve the result of the last transaction registered by the PINPad when RepeatLastMessage function is used. This attribute shows the result of the last PINPad registered transaction and is only valid when the ‘OriginalRequestID’ matches the ‘RequestID’ of the POS or VM.

Event to implement

CashierDisplay
Printer
EJournal
DeliveryBox (Only used in unattended mode)

StartGetStatusFlow

public ServiceResponse StartGetStatusFlow(
  String WorkstationID,
  LanguageCode LanguageCode,
  PrinterStatus PrinterStatus)

Description

This method starts a get status flow. Used to retrieve status from terminal.

Parameters

Return

ServiceResponse: This object content complete XML and parsed XML from terminal with following items: String WorkstationID: Echoed from request message

• String RequestID: Echoed from request message
• String RequestType: Echoed from request message
• String OverallResult: Mandatory. Result of the requested operation with following values:

• String Identification: Terminal ID of the terminal. This field is empty if terminal is not installed. String Hardware: Hardware type. Example: VX820
• String SerialNumber: SerialNumber. Example: 333-333-333
• String ConfigurationName: Configuration name as used on TMS. Example: VX82XCHITS String ConfigurationVersion: Configuration version as used on TMS. Example: 10.05
• String TerminalStatus: Status of terminal. Values: Idle, Loggedout ,Busy, Inoperable
• String TerminalSubStatus: Datailed status of the terminal. Values: Idle, Deactivated, Available, … String ReaderStatusIcc: Status of chip reader
• String ReaderStatusMagstripe: Status of magstripe reader
• String LocalPrinterStatus: Status os local printer if present (DUET or Wi-Fi terminals)

Event to implement

CashierDisplay
Printer

StartRestartTerminalFlow

public String StartRestartTerminalFlow (
  String WorkstationID,
  LanguageCode LanguageCode,
  PrinterStatus PrinterStatus)

Description

This method starts a restart terminal flow. Used to restart the terminal.

Parameters

Return

ServiceResponse: This object content complete XML and parsed parsed XML from terminal with following item: String OverallResult: Mandatory contains the result of the requested operation with following value:

Event to implement

CashierDisplay
Printer

Get Support

If you would like to integrate with Viva, or if you have any queries about our products and solutions, please see our Contact & Support page to see how we can help!