XML Receipts

Ocius Sentinel can supply raw receipt data in XML form rather than as formatted text. The directory path where Ocius writes these files should be setup in Ocius and points to the working directory of EFTLink, example C:\eftlink. There are a considerable number of data fields available in this way (see the latest Ocius Sentinel Integration Guide for a full list). Here is an example of an XML signature receipt received by the core from Sentinel:

<VoucherDetails>
  <TrainingMode>false</TrainingMode>
  <ReceiptType>Signature</ReceiptType>
  <Header>B &amp; Q</Header>
  <PTID>PW001654</PTID>
  <TID>04380001</TID>
  <MID>21249872</MID>
  <MkTransactionID>1552313</MkTransactionID>
  <TxnDateTime>2010-12-06 20:40:37.845 CET</TxnDateTime>
  <CardScheme>Visa</CardScheme>
  <PAN>*********2222</PAN>
  <ExpiryDate>12/12</ExpiryDate>
  <TxnType>Sale</TxnType>
  <CaptureMethod>SWIPED</CaptureMethod>
  <CustomerPresent>true</CustomerPresent>
  <ECommerce>false</ECommerce>
  <ContAuth>false</ContAuth>
  <AccountOnFile>false</AccountOnFile>
  <PinEntered>false</PinEntered>
  <CreditDebitMessage>Please debit my account</CreditDebitMessage>
  <CurrencySymbol>£</CurrencySymbol>
  <CurrencyAbbreviation>GBP</CurrencyAbbreviation>
  <Amount>1.00</Amount>
  <Total>1.00</Total>
  <CVM>Please Sign Below</CVM>
  <KeepText1>Please Keep This Receipt</KeepText1>
  <KeepText2>For your Records</KeepText2>
  <EFTSN>0508</EFTSN>
  <AuthCode>789DE</AuthCode>
  <Reference>101206 61 1 1</Reference>
  <Footer>B &amp; Q</Footer>
  <GratuityBoxRequired>false</GratuityBoxRequired>
  <ExtendedReceipt>false</ExtendedReceipt>
  <DisableCurrencySymbol>false</DisableCurrencySymbol>
  <AuthOnly>false</AuthOnly>
  <CardSchemePrintText></CardSchemePrintText>
  <PrintAttempts>1</PrintAttempts>
  <ContactlessMSD>false</ContactlessMSD>
  <TokenRegistrationResult>NotSet</TokenRegistrationResult>
  <TokenRegistrationOnly>false</TokenRegistrationOnly>
</VoucherDetails>

In XML mode the core must be configured to convert the XML data into formatted text receipts. Formatting is achieved using template files in which free text and XML fields can be positioned and left, right or center justified as required. Any number of templates can be created, and you would typically expect to have seven or more, one for each of the merchant, signature, customer, merchant void, customer void, merchant declined and customer declined receipts, and further templates for any extended functionality (for example gift cards).

Below is example of a template file:

Example 10-1 customer_template.txt

<WIDTH=36>
<CENTRE>Customer Test Template
------------------------------------
Card Sale<RIGHT><Total>
<PAN>
------------------------------------
Card   : <CardScheme>
Number : <PAN><RIGHT><CaptureMethod>
AID        : <AID>
App Date   : <AppEff>
Cryptogram : <CID>/<AC>
Auth Code  : <AuthCode>
Merchant ID: <MID>
Terminal ID: <TID>
------------------------------------
<CreditDebitMessage>
<CENTRE><CVM>

In the template, XML element names are specified in angled brackets like this <CVM> and each will be substituted with the actual value supplied by Sentinel. There are four special directives used for formatting which are:

  • <WIDTH=nn> This specifies the maximum width of the receipt in columns.

  • <CENTRE> This will center any text which appears after it on the same line.

  • <RIGHT> This will right-justify any text which appears after it on the same line.

  • <SUPPRESS> The receipt will not be printed.

Note:

All the above directives must be uppercase to be recognized.

In order to decide which template to use for a receipt the core will read a file called ocius_receipt.properties in which templates can be selected by looking for one or more values in the XML data. This file contains entries in the form

template-filename=<XML-element-1>required-value<XML-element-2>required-value

If all of the XML elements listed on the line have the specified value, then that template file will be used. Below is an example file:

Example 10-2 ocius_receipt.properties

template_customer_keyed_swiped.txt=<ReceiptType>Customer<CaptureMethod>SWIPED
template_merchant_keyed_swiped.txt=<ReceiptType>Merchant<CaptureMethod>SWIPED
template_signature.txt=<ReceiptType>Signature

When looking for a match templates are checked in the order that they appear in ocius_receipt.properties. If no matching template is found, then the core will return the entire XML data in place of a formatted receipt. If a template appears which does not specify any XML fields to match on (nothing after the equal sign) then that template will always be treated as a match.

It is also possible to match partial values using one or more of the flags [PREFIX], [SUFFIX] or [CONTAINS] followed by the partial text to match. For example:

template_customer_contactless.txt= <ReceiptType>Customer<CaptureMethod>[SUFFIX]CONTACTLESS

The above will match when ReceiptType has the fixed value Customer and CaptureMethod is any text followed by CONTACTLESS.