Versions

Maximal protocol version supported should be set in each command and answer.

  1. Version 2 optional tag "Tip" added to AuthPayResponse, ConfPay. Cаn be added only if version 2 in AuthPay attribute "version"

RK7 settings

For tips fill parameter TipChargeForAuthTerminal "Tip for authorization terminal"

AUHTTP driver description

  1. Each auth proc will made HTTP request to and address like https://127.0.0.1:1212/authtest/authpay.xml / https://127.0.0.1:1212/authtest/confpay.xml / e t. c.
  2. You should process this request and fill response data with neccesary data (see docs below)

AUHTTP driver configuration

XML data format description


AuthPay / ConfPay / VoidPay: request

<?xml version="1.0" encoding="utf-8"?>
<ConfPay version="1">
    <SrcID cashguid="{A776FBF7-F9B3-4E14-946E-AB717BA4884B}" servguid="{C31D76A2-09EC-419F-9EA8-7AB85D7446F8}" restguid="{FC1BBB36-4D7F-4EF9-80C2-33B78ADBDB6A}" fullcode="016470001"/>
    <Order/>
    <MyPay myAmount="288000"/>
    <auXML>
        <ActionID>1</ActionID>
        <CardCode>SomeText</CardCode>
        <AuthCode>AuthCode</AuthCode>
        <AuthInfo>AuthInfo</AuthInfo>
    </auXML>
  <!-- Optional Tip in ConfPay and VoidPay from version 2, only if Tip was returned in AuthPayResponse-->
  <Tip>
    <MyPay myAmount="10000"/>
    <auXML>
        <ActionID>56014</ActionID>
        <AuthCode>AuthCode</AuthCode>
        <AuthInfo>AuthInfo</AuthInfo>
        <CardCode>5536 91.. .... ....</CardCode>
    </auXML>
  </Tip>
</ConfPay>
XML
  • SrcID: source information (Restaurant / Server / Cash station e. t. c.)
  • Order: order content (empty in this example)
  • MyPay: amount information (will add currency later)
  • auXML: previous calls payment info (to find transaction data to void / confirm)

AuthPay / ConfPay / VoidPay: response

<?xml version="1.0" encoding="utf-8"?>
<!-- AuthPayResponse, ConfPayResponse, VoidPayResponse according to request main tag-->
<ConfPayResponse version="1">
  <OpResult>1</OpResult>
  <ActionID>56014</ActionID>
  <CardCode>SomeText</CardCode>
  <AuthCode>AuthCode</AuthCode>
  <AuthInfo>AuthInfo</AuthInfo>
  <PrinterT>
        <Unfiscal CutAfter="1">
            <TextLine Text="--------------------------------" />
            <TextLine Text="    MOKĖJIMO KORTELĖS KVITAS" />
            <TextLine Text="TERMINALO NR.:          TMM01651" />
            <TextLine Text="PREKYBININKO NR.:        0001651" />
            <TextLine Text="MAESTRO  (C)" />
            <TextLine Text="" />
            <TextLine Text="676515******0400" />
            <TextLine Text="BYLA: 000007    KVITO NR: 122381" />
            <TextLine Text="DATA: 2015.08.18   LAIKAS: 12:08" />
            <TextLine Text="RRN: 523012077523 AUT.K.: 851840" />
            <TextLine Text="AID: A0000000043060 APP: MAESTRO" />
            <TextLine Text="TC:  BD67A2DC2F76C234" />
            <TextLine Text="TVR: 0800008000      TSI:   E800" />
            <TextLine Text="           PARDAVIMAS" />
            <TextLine Text="" />
            <TextLine Text="SUMA:                   1.16 EUR" />
            <TextLine Text="" />
            <TextLine Text="  PIN KODAS ĮVESTAS TEISINGAI" />
            <TextLine Text="" />
            <TextLine Text="          PATVIRTINTA" />
            <TextLine Text="" />
            <TextLine Text="IŠSAUGOKITE ČEKĮ, KAD GALĖTUMĖTE" />
            <TextLine Text="" />
            <TextLine Text="  PATIKRINTI SĄSKAITOS IŠRAŠĄ" />
            <TextLine Text="--------------------------------" />
            <TextLine Text="" />
        </Unfiscal>
    </PrinterT>
  <DisplayT>Show me on Display</DisplayT>
  <ConfPrnT>0</ConfPrnT>
  <!-- Tip from version 2, only if 2+ in ConfPay/@version -->
  <Tip>
    <ActionID>56014</ActionID>
    <AuthCode>AuthCode</AuthCode>
    <CardCode>5536 91.. .... ....</CardCode>
    <AuthInfo>AuthInfo</AuthInfo>
    <MyPay myAmount="10000"/>
  </Tip>
</ConfPayResponse>
XML
  • Root node has one of the following values: AuthPayResponse / ConfPayResponse / VoidPayResponse.
  • OpResult: operation result (1 if okay, 0 if fail, default 1)
  • ActionID, CardCode, AuthCode, AuthInfo: payment data (will be available in subsequent calls to confpay.xml / authpay.xml in auXML block, also will be stored in R-Keeper database and available in reports)
  • PrinterT: Text to print, for format see [https://support.ucs.ru/ru/node/7045#header-19]
  • DisplayT: message to display
  • ConfPrnT: confirmation flag (message box required before receipt printing)

GetMenuList: request

<?xml version="1.0" encoding="utf-8"?>
<GetMenuList version="2"/>
XML

GetMenuList: response

<?xml version="1.0" encoding="utf-8"?>

<GetMenuListResponse version="2">
  <MENU>
    <MENUITEM caption="Menu 1" operationId="{607D07C9-42E9-4F92-B8AD-7AE051D4AB15}" parameter="12345" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}" userRight="{E3F2D792-1AC5-46D0-B53F-250FD8C3C189}"/>
    <MENUITEM caption="Menu 2 - with submenu">
      <MENUITEM caption="Menu 2: SubMenu 1" operationId="{B012B4DD-3ED9-422C-A28E-D0BF0152F931}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}"/>
      <MENUITEM caption="Menu 2: SubMenu 2">
        <MENUITEM caption="Menu 2: SubMenu 2: SubSubMenu 1" operationId="{59D8C6CA-809D-45B6-9D4E-0D7CCC21569A}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}"/>
        <MENUITEM caption="Menu 2: SubMenu 2: SubSubMenu 2" operationId="{56A61F0A-13A9-4FD2-A328-D41893576A3A}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}"/>
        <MENUITEM caption="Menu 2: SubMenu 2: SubSubMenu 3" operationId="{2D551616-229A-4EAA-A333-8F06D926F70D}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}"/>
      </MENUITEM>
      <MENUITEM caption="Menu 2: SubMenu 3">
        <MENUITEM caption="Menu 2: SubMenu 3: SubSubMenu 1">
          <MENUITEM caption="Menu 2: SubMenu 3: SubSubMenu 1: SubSubSubMenu: 1" operationId="{0E2F7D7F-8AE1-4F55-937A-4445C30AB1D0}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}"/>
          <MENUITEM caption="Menu 2: SubMenu 3: SubSubMenu 1: SubSubSubMenu: 2" operationId="{B7C5A6D9-5E43-4159-9C8D-ADBF1B26EC18}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}"/>
        </MENUITEM>
      </MENUITEM>
    </MENUITEM>
    <MENUITEM caption="Menu 3 - with dialogs">
      <MENUITEM caption="Menu 3: SubMenu 1 with  dialog DateInterval" operationId="{47704B77-5D7A-4B66-9250-DC37238095B1}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}">
        <DIALOGINFO dialogType="DateInterval" caption="Enter date interval"/>
      </MENUITEM>
      <MENUITEM caption="Menu 3: SubMenu 2 with  dialog NumberInterval" operationId="{51EC80F4-3612-4828-9330-6BDD814D7678}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}">
        <DIALOGINFO dialogType="NumberInterval" caption="Enter number interval"/>
      </MENUITEM>
      <MENUITEM caption="Menu 3: SubMenu 3 with  dialog OneDate" operationId="{773B5388-9C30-4878-B338-6D37EEAC8576}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}">
        <DIALOGINFO dialogType="OneDate" caption="Enter date"/>
      </MENUITEM>
      <MENUITEM caption="Menu 3: SubMenu 4 with  dialog OneNumber" operationId="{29A0D2FC-19CB-40F2-B2ED-02699D7CEB5F}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}">
        <DIALOGINFO dialogType="OneNumber" caption="Enter number"/>
      </MENUITEM>
    </MENUITEM>
  </MENU>
</GetMenuListResponse>
XML

ExecMenuItem: request

<?xml version="1.0" encoding="utf-8"?>
<ExecMenuItem version="2">
    <OperationId>{607D07C9-42E9-4F92-B8AD-7AE051D4AB15}</OperationId>
    <Parameter>12345</Parameter>
</ExecMenuItem>
XML

ExecMenuItem: response

<?xml version="1.0" encoding="utf-8"?>
<ExecMenuItemResponse version="2">
  <OpResult>1</OpResult>
  <PrinterT>
        <Unfiscal CutAfter="1">
            <TextLine Text="----Unfiscal doc 1 header-------"/>
            <TextLine Text="Some unfiscal 1 text line 1     "/>
            <TextLine Text="Some unfiscal 1 text line 2     "/>
            <TextLine Text=""/>
        </Unfiscal>
        <Unfiscal CutAfter="1">
            <TextLine Text="----Unfiscal doc 2 header-------"/>
            <TextLine Text="Some unfiscal 2 text line 1     "/>
            <TextLine Text="Some unfiscal 2 text line 2     "/>
            <TextLine Text="Some unfiscal 2 text line 3     "/>
            <TextLine Text="Some unfiscal 2 text line 4     "/>
            <TextLine Text="Some unfiscal 2 text line 5     "/>
            <TextLine Text=""/>
        </Unfiscal>
  </PrinterT>
  <DisplayT>Show me on Display</DisplayT>
</ExecMenuItemResponse>
XML

Interaction scenario example

1. authpay.xml: authorizations request

  • Server must use MyPay node from AuthPay document to determine the required amount.
  • In case of successful execution server should set OpResult to "1" (version 4+) and fill CardCode, AuthCode, AuthInfo, ActionID parameters.
  • Server may set ConfPrnT parameter if receipt printing confirmation message is required on cash stations
  • Server may set PrinterT parameter if additional printed text is required
  • If server is unable to execute required operation it must set OpResult to "0" and fill the DisplayT parameter (or return an HTTP error code with describing text)

2. confpay.xml: confirmation request

  • Server must use MyPay node from AuthPay document to determine the required amount.
  • Server may use auXML node data to identify transaction (this block will contain values received in authorizations call)
  • In case of successful execution server should set OpResult to "1" (version 4+) and fill CardCode, AuthCode, AuthInfo, ActionID parameters (if any of them were changed since authorization)
  • Server may use auXML node data to identify transaction (this block will contain values received in authorizations call)
  • Server may set ConfPrnT parameter if receipt printing confirmation message is required on cash stations
  • Server may set PrinterT parameter if additional printed text is required
  • If server is unable to execute required operation it must set OpResult to "0" and fill the DisplayT parameter (or return an HTTP error code with describing text)

3. voidpay.xml: void request

  • Server must use auXML node data to identify transaction (this block will contain values received in authorizations call)
  • Server must use MyPay node from AuthPay document to determine the required amount.
  • In case of successful execution server should set OpResult to "1" (version 4+) and fill CardCode, AuthCode, AuthInfo, ActionID parameters (if any of them were changed since authorization)
  • Server may set PrinterT parameter if additional printed text is required
  • If server is unable to execute required operation it must set OpResult to "0" and fill the DisplayT parameter (or return an HTTP error code with describing text)

4. doshift.xml: shifts totals request

When common shift is closed, driver will call doshift.xml with following data:

<?xml version="1.0" encoding="utf-8"?>
<DoShift version="1">
    <SrcID cashguid="{4E4C529F-88EF-4BFF-A8C4-9C3D9524BC42}" servguid="{F64F66DA-5463-46A0-BDCD-97DE92026F0E}" restguid="{FC1BBB36-4D7F-4EF9-80C2-33B78ADBDB6A}" fullcode="199990053"/>
</DoShift>
XML
Server must answer with DoShiftResponse (no action at this moment):
<?xml version="1.0"?>
<DoShiftResponse version="1"/>
  <PrinterT>
        <Unfiscal CutAfter="1">
            <TextLine Text="   START CARD TERMINAL REPORT   "/>
            <TextLine Text="             ...                "/>
            <TextLine Text="   REPORT IN PROGRESS           "/>
            <TextLine Text="             ...                "/>
            <TextLine Text="  FINISH CARD TERMINAL REPORT   "/>
        </Unfiscal>
    </PrinterT>
XML

5. getmenulist.xml: Запрос структуры меню:

Post request to: http://127.0.0.1:1220/authcall.xml/getmenulist.xml

<?xml version="1.0" encoding="utf-8"?>
<GetMenuList version="2"/>
XML

Пример ответа на него:

<?xml version="1.0" encoding="utf-8"?>
<GetMenuListResponse version="2">
  <MENU>
    <MENUITEM caption="Menu 1" operationId="{607D07C9-42E9-4F92-B8AD-7AE051D4AB15}" parameter="12345" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}" userRight="{E3F2D792-1AC5-46D0-B53F-250FD8C3C189}"/>
    <MENUITEM caption="Menu 2 - with submenu">
      <MENUITEM caption="Menu 2: SubMenu 1" operationId="{B012B4DD-3ED9-422C-A28E-D0BF0152F931}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}"/>
      <MENUITEM caption="Menu 2: SubMenu 2">
        <MENUITEM caption="Menu 2: SubMenu 2: SubSubMenu 1" operationId="{59D8C6CA-809D-45B6-9D4E-0D7CCC21569A}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}"/>
        <MENUITEM caption="Menu 2: SubMenu 2: SubSubMenu 2" operationId="{56A61F0A-13A9-4FD2-A328-D41893576A3A}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}"/>
        <MENUITEM caption="Menu 2: SubMenu 2: SubSubMenu 3" operationId="{2D551616-229A-4EAA-A333-8F06D926F70D}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}"/>
      </MENUITEM>
      <MENUITEM caption="Menu 2: SubMenu 3">
        <MENUITEM caption="Menu 2: SubMenu 3: SubSubMenu 1">
          <MENUITEM caption="Menu 2: SubMenu 3: SubSubMenu 1: SubSubSubMenu: 1" operationId="{0E2F7D7F-8AE1-4F55-937A-4445C30AB1D0}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}"/>
          <MENUITEM caption="Menu 2: SubMenu 3: SubSubMenu 1: SubSubSubMenu: 2" operationId="{B7C5A6D9-5E43-4159-9C8D-ADBF1B26EC18}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}"/>
        </MENUITEM>
      </MENUITEM>
    </MENUITEM>
    <MENUITEM caption="Menu 3 - with dialogs">
      <MENUITEM caption="Menu 3: SubMenu 1 with  dialog DateInterval" operationId="{47704B77-5D7A-4B66-9250-DC37238095B1}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}">
        <DIALOGINFO dialogType="DateInterval" caption="Enter date interval"/>
      </MENUITEM>
      <MENUITEM caption="Menu 3: SubMenu 2 with  dialog NumberInterval" operationId="{51EC80F4-3612-4828-9330-6BDD814D7678}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}">
        <DIALOGINFO dialogType="NumberInterval" caption="Enter number interval"/>
      </MENUITEM>
      <MENUITEM caption="Menu 3: SubMenu 3 with  dialog OneDate" operationId="{773B5388-9C30-4878-B338-6D37EEAC8576}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}">
        <DIALOGINFO dialogType="OneDate" caption="Enter date"/>
      </MENUITEM>
      <MENUITEM caption="Menu 3: SubMenu 4 with  dialog OneNumber" operationId="{29A0D2FC-19CB-40F2-B2ED-02699D7CEB5F}" purposeToLock="{7DA9C7F9-7DAE-462F-9FC5-113E2E3810B2}">
        <DIALOGINFO dialogType="OneNumber" caption="Enter number"/>
      </MENUITEM>
    </MENUITEM>
  </MENU>
</GetMenuListResponse>
XML

6. execmenuitem.xml: Запрос выполнения пункта меню:

Post request to: http://127.0.0.1:1220/authcall.xml/execmenuitem.xml

<?xml version="1.0" encoding="utf-8"?>
<ExecMenuItem version="2">
    <OperationId>{607D07C9-42E9-4F92-B8AD-7AE051D4AB15}</OperationId>
    <Parameter>12345</Parameter>
</ExecMenuItem>
XML

Пример ответа на него:

<?xml version="1.0" encoding="utf-8"?>
<ExecMenuItemResponse version="2">
  <OpResult>1</OpResult>
  <PrinterT>
        <Unfiscal CutAfter="1">
            <TextLine Text="----Unfiscal doc 1 header-------"/>
            <TextLine Text="Some unfiscal 1 text line 1     "/>
            <TextLine Text="Some unfiscal 1 text line 2     "/>
            <TextLine Text=""/>
        </Unfiscal>
        <Unfiscal CutAfter="1">
            <TextLine Text="----Unfiscal doc 2 header-------"/>
            <TextLine Text="Some unfiscal 2 text line 1     "/>
            <TextLine Text="Some unfiscal 2 text line 2     "/>
            <TextLine Text="Some unfiscal 2 text line 3     "/>
            <TextLine Text="Some unfiscal 2 text line 4     "/>
            <TextLine Text="Some unfiscal 2 text line 5     "/>
            <TextLine Text=""/>
        </Unfiscal>
  </PrinterT>
  <DisplayT>Show me on Display</DisplayT>
</ExecMenuItemResponse>
XML

If server is unable to execute required operation it must return an HTTP error code with describing text

Solved issues

1. There is not enough info to VOID transaction at this momen: will fix in next version.

We`ve added auXML section with CardCode, AuthCode, AuthInfo, ActionID data: this will allow you to find previous transaction info.

2. An ability to print message and show mesage on screen after an authorization process and in case of any stage operation error.

We`ve added OpResult to determine operation result and PrinterT / DisplayT nodes:

  • If OpResult is "0" and DisplayT contains some text: we`ll show a message on station
  • If PrinterT contains some text it will be printer on a printing device

3. An ability to prevent user dialog about document printing: will fix in next version.

We`ve added ConfPrnT parameter: 1 if we need confirmation before receipt printing (default is 0)