Migrating from a previous CCV POS integration

Migrating to the Viva Wallet 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 Wallet’s POS terminals.

List of methods and signatures

Table of contents:

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

ParameterImportanceUsage
Int32 TimeoutRequiredSpecifies the maximum number of milliseconds (after sending the echo message) to wait for the ICMP echo reply message.

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

Parameter Importance Usage
String WorkstationID Required POS unique ID. Example: "POS1"
CardServiceRequestType
RequestType
(Enumeration)
Required Transaction type:
CardPayment: Start a Purchase transaction
CashAdvance: Start a Cash Advance transaction (only
attended terminals if allowed by ACQ)
CardReservation: Start a Reservation transaction (only attended terminals)
PaymentRefund: Start a Refund transaction (only attended terminals)
PaymentReversal: Start a Cancellation transaction (only attended terminals)
CardValidation: Start the Card Validation functionality to check if a specific card can be used to perform a transaction (not used)
TicketReprint: Reprint a receipt
AbortRequest: Abort a transaction
RepeatLastMessage: Retrieve last message in case of
communication failure
LanguageCode LanguageCode
(Enumeration)
Required POS language (en: English, fr: French, de: German,
nl: Dutch)
Int32 ShiftNumber Required Not used
Int32 ClerkID Required Not used
PrinterStatus PrinterStatus
(Enumeration)
Required Printer status:
• Available
• PaperLow
• PaperEnpty
• PrintLocal (see 4.6. Local Printing...)
• Unavailable
JournalPrinterStatus
JournalPrinterStatus
(Enumeration)
Required Journal printer status:
• Available
• PaperLow
• PaperEnpty
• PrintLocal (see 4.6. Local Printing...)
• Unavailable
EJournalStatus
EJournalStatus
(Enumeration)
Required E-Journal printer status:
• Available
• Unavailable
• MemoryLow
TextLine PrinterTicketHeader1 Optional* Receipt header line 1. E.g. Company name
Use:
public TextLine(
String Text,
TextLineWidth Width,
TextLineHeight Height)

TextLineWidth values: Single and Double
TextLineHeight values: Single and Double
You can enter max 40 characters and 20 if TextLineWidth =
Double
Example:
TextLine PTH1 = new TextLine("CCV-Jeronimo",
TextLineWidth.Double,TextLineHeight.Single)
TextLine PrinterTicketHeader2 Optional* Receipt header line 2. E.g. Company address
Use and example: See PrinterTicketHeader1
TextLine PrinterTicketHeader3 Optional* Receipt header line 3. E.g. Company zip and city
Use and example: See PrinterTicketHeader1
TextLine PrinterTicketHeader4 Optional* Receipt header line 4. E.g. Company phone nbr
Use and example: See PrinterTicketHeader1

TextLine PrinterTicketHeader5 Optional* Receipt header line 5. E.g. Company emai or website
Use and example: See PrinterTicketHeader1
TextLine PrinterTicketFooter1 Optional* Receipt footer line 1
Use and example: See PrinterTicketHeader1
TextLine PrinterTicketFooter2 Optional* Receipt footer line 2
Use and example: See PrinterTicketHeader1
TextLine PrinterTicketFooter3 Optional* Receipt footer line 3
Use and example: See PrinterTicketHeader1
TextLine PrinterTicketFooter4 Optional* Receipt footer line 4
Use and example: See PrinterTicketHeader1
TextLine PrinterTicketFooter5 Optional* Receipt footer line 5
Use and example: See PrinterTicketHeader1
Currency Currency
(Enumeration)
Required Amount currancy: CHF, CHW and EUR
Example: Currency.CHF
Decimal TotalAmount Required Transaction amount.
Example: 4 or Decimal.Parse("4.00"));

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

Value Description
“Success” Complete Success
“Failure” Complete Failure
“PrintLastTicket” Complete Failure. Payment rejected by terminal
because receipt of last transaction has not been
printed
“DeviceUnavailable” Complete Failure. No further request will be
successful because a device is temporary unavailable
(e.g. busy with terminal initialisation session or other
request)
“Aborted” Complete failure. The transaction was aborted by
cashier or cardholder
“TimedOut” Complete Failure. No response from remote host,
cardholder timeout or cashier input timeout
“FormatError” Complete Failure. The request cannot be handled or
mistakenly (unknown) formatted
“ParsingError” Complete Failure. The request XML is not well formed

“ValidationError”
Complete Failure. The request XML is not validated
against the definition scheme
“MissingRequiredData” Complete Failure. The request message is missing
required data
“ConnectionError” Complete Failure. No conection with terminal
“FlowTimedOut” Complete Failure. Timeout set in FlowManager
instance.
“Error” Unknown error

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

Parameter Usage
String WorkstationID POS unique ID. Example: "POS1"
LanguageCode LanguageCode
(Enumeration)
POS language (en: English, fr: French, de: German,
nl: Dutch)
PrinterStatus PrinterStatus
(Enumeration)
Printer status:,
• Available
• Unavailable

Return

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

Value Desciption
"Success" Complete Success
"Failure" Complete Failure
"DeviceUnavailable" Complete Failure. Device is temporary unavailable (e.g.
busy with terminal initialisation session or other request)
"TimedOut" Complete Failure. No response from remote host,
cardholder timeout or cashier input timeout
"FormatError" Complete Failure. The request cannot be handled or
mistakenly (unknown) formatted
"ParsingError" Complete Failure. The request XML is not well formed
"ValidationError" Complete Failure. The request XML is not validated against
the definition scheme
"MissingMandatoryData" Complete Failure. The request message is missing
mandatory data
"ConnectionError" Complete Failure. No conection with terminal
"Error" Unknown error
"TimeOut" Complete Failure. Timeout set in FlowManager instance

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

ParameterUsage
String WorkstationIDPOS unique ID. Example: "POS1"
LanguageCode LanguageCode (Enumeration)POS language (en : English, fr : French, de : German, nl : Dutch)
PrinterStatus PrinterStatus (Enumeration)Printer status:
• Available
• Unavailable

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:

Value Description
"Success" Complete Success
"Failure" Complete Failure
“DeviceUnavailable” Complete Failure. No further request will be successful
because a device is temporary unavailable (e.g. busy
with terminal initialisation session or other request)
“TimedOut” Complete Failure. No response from remote host, cardholder timeout or cashier input timeout
“FormatError” Complete Failure. The request cannot be handled or mistakenly (unknown) formatting
“ParsingError” Complete Failure. The request XML is not well formed
“ValidationError” Complete Failure. The request XML is not validated
against the definition scheme
“MissingMandatoryData” Complete Failure. The request message is missing
mandatory data
“ConnectionError” Complete Failure. No conection with terminal
“Error” Unknown error
"FlowTimedOut" Complete Failure. Timeout set in FlowManager instance

Event to implement

CashierDisplay
Printer