CUSCNX

From RPOWERWiki

Jump to: navigation, search

CUSCNX is an On-Line Customer Gift & Loyalty API under XyzzyTalk (pronounced "ZizzyTalk"), which in turn is a lightweight XML specification for client-server transaction processing and data exchange.

CUSCNX is used as a conduit to an actual back-end gift and loyalty application, including RPOWER itself on an RPOWER database local to the CUSCNX server.

CUSCNX exists within the wider context of the K3 Card Automatic Numbering System (KCANS). It uses and implements KCANS card, coupon, reward, and program numbering and identification standards. As such, it recognizes and supports the use of non-card-number Canonical Data Types such as phone, email, and XTYPE, plus the various wegy data representations such as UPC49 and CRMPHN.

This is a long article, on purpose. Use the Table of Contents!

Contents

Introduction

Like other XyzzyTalk applications, a CUSCNX client performs an HTTP POST of a (XyzzyTalk) XML payload to a CUSCNX server, typically on TCP port 32112, and waits for a response. The server processes the request and replies with similar HTTP payload. Almost all CUSCNX operations are expected to execute and reply in well under one second.

Typically the server is a single background RPOWER running on either a standalone computer or on the file server of a single active location.

CUSCNX is almost unique among transactional APIs (SparkBase being a notable exception) in that it provides the exact same complete response payload to every function call, with the only exception being that elements with no meaning in the context of a particular function are suppressed. Values specific to each function are isolated in a separate element.

This means the application developer can write a single response-parsing function to fill in a standard reponse record.

To support this functionality for third-party platforms, such as the original combined Mercury Loyalty and Gift, the CUSNCX server can perform multiple posts to the external server while executing a single CUSCNX transaction.

This article deals primarily with RPOWER's own Built-In Gift and Loyalty system to describe how one would go about designing one's own minimal client or server CUSCNX application. Other back ends, such as MercuryLoyalty or SparkBase, will always work with a full client implementation but the drivers may interpret things a little differently. For example, the SparkBase driver does not look at the card number (num=) but only at the account number (acct=). In other cases, a card number might actually be an email address or a phone number.

A Full-Blown Example CUSCNX Exchange

Combination Loyalty and Stored Value Guest Check

To illustrate how CUSCNX works, here is an example a full exchange from the POS.

In all of the examples card numbers are shown in plaintext. In practice, <Card> fields such as num, t2, and acct use X1 Encryption and appear as Base64 strings prefixed with with #X1#.

Query-on-Swipe

RPOWER queries any CUSCNX card swipe or other recognized entry (phone number, name, email address, or even credit card) immediately upon swipe to retrieve balances in order to find out exactly what the application can and should do with the the account.

«POST / HTTP/1.1<CR><LF>                                   »
«User-Agent: RPOWER v1108607 sn1<CR><LF>                   »
«Accept: */*<CR><LF>                                       »
«Host: rpower.dyndns.org<CR><LF>                           »
«Content-Type: text/xml<CR><LF>                            »
«Content-Length: 493<CR><LF>                               »
«<CR><LF>                                                  »
«<?xml version="1.0"?><CR><LF>                             »
«<XyzzyTalk><CR><LF>                                       »
«<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api»
«_version='12.2.11.1' api_command='QUERY' app_version='1108»
«607' date_time='2013-03-15T09:54:54-07:00' tz='MST'/><CR><»
«LF>                                                       »
«<CCX_QUERY><CR><LF>                                       »
«<Card f='S' id='RPQKCSH' t2='901012021200014' num='9010120»
«21200014' acct='901012021200014'/><CR><LF>                »
«<Loc co='RPOWER(tm) Restaurant POS #SAMP' loc='1' sta='SAM»
«PLE' sid='SAMPLE'/><CR><LF>                               »
«<Tran cduprid='1118521407892949273' dt='2013-03-15T09:54:0»
«0' clk='0'/><CR><LF>                                      »
«</CCX_QUERY><CR><LF>                                      »
«</XyzzyTalk><CR><LF>                                      »

This first example POST and reply shows the actual unformatted content enclosed in chevrons for clarity and including the ASCII #13 and #10 end-of-line characters. These are shown as "<CR><LF>" per notation in the Wikipedia article (as opposed to "CRLF" in RFC 2616). Note that HTTP headers are just text followed by two contiguous <CR><LF> pairs (or, technically, the headers are separated by a "blank line" from the "message body").

All other examples will show just XML formatted for readability but still well-formed.

Query-on-Swipe Response
«HTTP/1.1 200 OK<CR><LF>                                                        »
«Server: K3INET/1.0<CR><LF>                                                     »
«Connection: close<CR><LF>                                                      »
«Proxy-Connection: close<CR><LF>                                                »
«Cache-Control: no-cache<CR><LF>                                                »
«Content-Type: text/xml<CR><LF>                                                 »
«Content-Length: 592<CR><LF>                                                    »
«<CR><LF>                                                                       »
«<?xml version="1.0"?><CR><LF>                                                  »
«<XyzzyTalk><CR><LF>                                                            »
«<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1' »
«api_command='QUERY' app_version='1108606' date_time='2013-03-15T09:54:49-07:00'»
« tz='MST'/><CR><LF>                                                            »
«<CCX_RESPONSE><CR><LF>                                                         »
«<Tran cduprid='1118521407892949273' srefstr='0/0;AAAAAAAAAAA' dt='2013-03-15T09»
«:54:00' clk='0'/><CR><LF>                                                      »
«<Info><CR><LF>                                                                 »
«<Bal bf='CLMT,LMTD,ANON,LOYL,PPAY,MMOK,DPTS,PPTS,DBAL,PBAL,CBAL,CUSCNX' tf='AD,»
«RP,RDP,CD,A,D,NC,ED' dp='72' rp='-1' rd='$US-0.01' dcd='$US25' cd='$US25'/><CR>»
«<LF>                                                                           »
«<TTD accum_p='72'/><CR><LF>                                                    »
«</Info><CR><LF>                                                                »
«<Card f='S,PRI,EXC' acct='901012021200014'/><CR><LF>                           »
«</CCX_RESPONSE><CR><LF>                                                        »
«</XyzzyTalk><CR><LF>                                                           »

(Add Pointable Dollars for) Loyalty Purchase

<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='PURCHASE' app_version='1108607'
             date_time='2013-03-15T09:55:23-07:00' tz='MST'/>
<CCX_QUERY>

  <Card f='S' id='RPQKCSH' t2='901012021200014' num='901012021200014'
        acct='901012021200014'/>

  <Loc co='RPOWER(tm) Restaurant POS #SAMP' loc='1' sta='SAMPLE' sid='SAMPLE'/>

  <Tran crefstr='CpPqLMY1gGm;AAAAAAAAAAA;3GJ5R2R9J9;20130315,A,129;66450969'
        cduprid='1118521485765679385' dt='2013-03-15T09:55:00' clk='101' clki='RF'/>

  <Parms parm2='525' trk1='567'/>

  <Amts it='$US5.25' nc='1' xc1='1' tax='$US0.42' pdp='72' pcd='$US25'
        accum_d='$US5.25'/>

  <Ticket ref='CpPqLMY1gGm,3GJ5R2R9J9,129' dt='2013-03-15T09:55:00' dlvt='DINEIN'
          asap='1' tax='$US0.42' gttl='$US5.67' pcenter='1'/>

</CCX_QUERY>
</XyzzyTalk>
Loyalty Purchase Response
<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='PURCHASE' app_version='1108606'
             date_time='2013-03-15T09:55:22-07:00' tz='MST'/>
<CCX_RESPONSE>

  <Tran crefstr='CpPqLMY1gGm;AAAAAAAAAAA;3GJ5R2R9J9;20130315,A,129;66450969'
        cduprid='1118521485765679385' srefstr='NE3/V4;CpPqL1ZvK6O'
        dt='2013-03-15T09:55:00' clk='101' clki='RF'/>

  <Parms parm1='5'/>

  <Info>

  <Bal bf='CLMT,LMTD,ANON,LOYL,PPAY,MMOK,DPTS,PPTS,DBAL,PBAL,CBAL,CUSCNX'
       tf='AD,RP,RDP,CD,A,D,NC,ED' dp='77' rp='-1' rd='$US-0.01' dcd='$US25'
       cd='$US25'/>

  <TTD accum_p='77'/>

  </Info>

  <Card f='S,PRI,EXC' acct='901012021200014'/>

</CCX_RESPONSE>
</XyzzyTalk>

Stored Value Charge

<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='CHARGE' app_version='1108607'
             date_time='2013-03-15T09:55:32-07:00' tz='MST'/>
<CCX_QUERY>

  <Card f='S' id='RPQKCSH' t2='901012021200014' num='901012021200014'
        acct='901012021200014'/>

  <Loc co='RPOWER(tm) Restaurant POS #SAMP' loc='1' sta='SAMPLE' sid='SAMPLE'/>

  <Tran crefstr='CpPqLMY1gGm;CpPqLNWtJ9w;3GJ5R2R9J9;20130315,A,129;71833113'
        cduprid='1118521507874650393' dt='2013-03-15T09:55:00' clk='101' clki='RF'/>

  <Parms parm1='567' parm2='100' trk1='667'/>

  <Amts it='$US5.25' nc='1' xc1='1' tax='$US0.42' tip='$US1' pdp='72' pcd='$US25'
        charge_d='$US6.67'/>

</CCX_QUERY>
</XyzzyTalk>
Stored Value Charge Response
<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='CHARGE' app_version='1108606'
             date_time='2013-03-15T09:55:30-07:00' tz='MST'/>
<CCX_RESPONSE>

  <Tran crefstr='CpPqLMY1gGm;CpPqLNWtJ9w;3GJ5R2R9J9;20130315,A,129;71833113'
        cduprid='1118521507874650393' srefstr='NE3/V5;CpPqMmS5LPU'
        dt='2013-03-15T09:55:00' clk='101' clki='RF'/>

  <Parms parm1='667'/>

  <Info>

    <Bal bf='CLMT,LMTD,ANON,LOYL,PPAY,MMOK,DPTS,PPTS,DBAL,PBAL,CBAL,CUSCNX'
         tf='AD,RP,RDP,CD,A,D,NC,ED' dp='77' rp='-1' rd='$US-0.01' dcd='$US18.33'
         cd='$US18.33'/>

    <TTD accum_p='77'/>

  </Info>

  <Card f='S,PRI,EXC' acct='901012021200014'/>
</CCX_RESPONSE>

</XyzzyTalk>

Basic CUSCNX Concepts

At the bottom of CUSCNX lies a single database record containing an integer point balance and a numeric stored-value dollar amount. This record has a unique ID called an account number. In pure CUSCNX parlance the account number is merely a contiguous substring a card number (or the entire card number) and cannot be interpreted as anything more significant than that.

Program 
A program contains card numbers. A program is the outermost conceptual layer for a group of card numbers. Each program has a unique ID rendered as a XXTYPE (pronounced "double x-type").
Card Number 
A card number is a single permanent unique identifier within a single program. Once a card number has been generated for a program, that same number may never be generated again.
Account 
An account is a single entity containing balance values in a database. In theory, the concept of account exists independently of program. In practice, the account is linked to a single primary card number, with other card numbers acting as aliases.
Alias 
An alias is a short-term unique identifier within a single program that uniquely links to a card number.

While under the K3 Card Automatic Numbering System (KCANS) it is possible for a single card number to exist in different programs, a CUSCNX server will always parse a given card number to a single program and return that information on a balance inquiry.

CUSCNX API Command Reference

Account Lookup (QUERY and BALINQUIRY)

CUSCNX differentiates between an implicit (automatic query-on-swipe) and an explicit ("pure" customer-initiated) balance inquiry.

It also used to be the case that some third-party gift and loyalty systems charged money for a customer simply walking up looking up his or her balance. Even though this is probably no longer true, there might still be a reason in the future to allow an explicit query of this type to return a richer, more time-consuming response (for example, one containing a transaction history).

There might also be a difference in the handling of the "Autoactivate" (AA) CUSCNX Transaction Flag. A BALINQUIRY might not activate the account (but a QUERY always would so that a card never "needs activation").

BALINQUIRY Minimal Client Request

<XyzzyTalk>
  <XyzzyHeader api_id='CUSCNX' api_command='BALINQUIRY'/>
  <CCX_QUERY>
    <Card id='RPQKCSH' num='901012021200014'/>
  </CCX_QUERY>
</XyzzyTalk>

The inclusion of id= is optional. The program ID and description will be returned in the full reply.

BALINQUIRY Minimal Server Response
<XyzzyTalk>
  <CCX_RESPONSE>
    <Info>
      <Bal cd='$US11.17'/>
    </Info>
  </CCX_RESPONSE>
</XyzzyTalk>

where the cd='$US11.17' means the spending limit on the account is $11.17. Zero ($US0.00) means the limit is zero, not unlimited. To make the amount unlimited, use cd='US$99999.99'. Since zero-dollar amounts don't have to be output, the following is equivalent to cd=$US0.00:

<XyzzyTalk/>

which is a single, empty, self-terminating wrapper element. Technically not even that has to be output because it is blank. However, a zero-content-length response may be interpreted as a communication error by RPOWER.

Other balance values would be supplied as needed in the minimal response, of course.

BALINQUIRY Full Post

<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='BALINQUIRY' app_version='1108607'
             date_time='2013-03-18T16:10:11-07:00' tz='MST'/>
<CCX_QUERY>

  <Card f='S' id='RPQKCSH' t2='901012021200014' num='901012021200014'
        acct='901012021200014'/>

  <Loc co='RPOWER(tm) Restaurant POS #SAMP' loc='1' sta='SAMPLE' sid='SAMPLE'/>

  <Tran cduprid='1119277633643984479' dt='2013-03-18T16:10:00' clk='0'/>

</CCX_QUERY>
</XyzzyTalk>

Out of this, the following strings are (may be) important:

api_command='BALINQUIRY' or 'QUERY' 
Inquire Balance. RPOWER differentiates between a "pure" (customer-initiated) balance inquiry (BALINQUIRY) and RPOWER's own internal balance check (QUERY), since some third-party companies charge a fee for the former.
num='901012011200016' 
Card number. It is required. RPOWER Built-In Gift and Loyalty does not use t2= and acct=.
id='RPQKCSH' 
references the CRM program ID matching the id=... setting in the CardRule= line under the appropriate [SERVICE ...] section in the server's CUSCNX.ini.

If id= is not supplied, num= will be used to determine the program id.

f='S' 
S means swiped. M means manually entered.
cvc='5432' 
"Card verification value" entered by the user.

Other fields are described below under Charge Account.

BALINQUIRY Full Response (Account Found)
<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='BALINQUIRY' app_version='1108607'
             date_time='2013-03-18T16:10:04-07:00' tz='MST'/>
<CCX_RESPONSE>

  <Tran cduprid='1119277633643984479' srefstr='0/0;AAAAAAAAAAA' dt='2013-03-18T16:10:00'
        clk='0'/>

  <Info>

    <Bal bf='CLMT,LMTD,ANON,LOYL,PPAY,MMOK,DPTS,PPTS,DBAL,PBAL,CBAL,CUSCNX'
         tf='AD,RP,RDP,CD,A,D,NC,ED' dp='77' rp='-1' rd='$US-0.01' dcd='$US18.33'
         cd='$US18.33'/>

    <TTD accum_p='77'/>

  </Info>

  <Card f='S,PRI,EXC' acct='901012021200014'/>

  <Program id='RPQKCSH' name='RPOWER Quik Cash'
           fCusFlags='CLMT,LMTD,ANON,LOYL,PPAY,DPTS,PPTS,DBAL,PBAL,CBAL'
           fTranFlags='AD,RDP,RP,CD,A,ED,D,NC' iTenderKey='3' iRdmMinimum='100'
           iRdmIncrement='50' sCentsPerPoint='10' iDivideCentsPerPointBy='1'
           iPointsPerDollar='1' iSettleGroup='2'/>

</CCX_RESPONSE>
</XyzzyTalk>

The bf= and tf= <Bal> element attributes from the server tell the client everything (one hopes) it needs to know about this account's status and what kind of transactions are allowed on the account. Even though in RPOWER the restaurant's CUSCNX.ini typically has these flags, they are ignored in a multi-store environment — the server's flags rule.

BALINQUIRY Full Response (Account Not Found)
<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='BALINQUIRY' app_version='1108607'
             date_time='2013-03-18T16:10:15-07:00' tz='MST'/>
<CCX_RESPONSE>

  <Tran cduprid='1119277663585072735' srefstr='0/0;AAAAAAAAAAA' dt='2013-03-18T16:10:00'
        clk='0'/>

  <Info>

    <Cus>

      <Card f='NEW'/>

    </Cus>

    <Bal bf='CASH,LMTD,ANON,LOYL,MMOK,DPTS,PPTS,DBAL,PBAL,UNKN,NDAC,CBAL,CUSCNX'
         tf='AD,RP,RDP,CD,A,D,NC,ED' dp='-1' rp='-1' rd='$US-0.01' dcd='$US-0.01'
         cd='$US-0.01'/>

    <TTD accum_p='-1'/>

  </Info>

  <Card f='S,PRI,EXC' acct='901012021200022'/>

  <Program id='RPQKCSH' name='RPOWER Quik Cash'
           fCusFlags='CLMT,LMTD,ANON,LOYL,PPAY,DPTS,PPTS,DBAL,PBAL,CBAL'
           fTranFlags='AD,RDP,RP,CD,A,ED,D,NC' iTenderKey='3' iRdmMinimum='100'
           iRdmIncrement='50' sCentsPerPoint='10' iDivideCentsPerPointBy='1'
           iPointsPerDollar='1' iSettleGroup='2'/>

</CCX_RESPONSE>
</XyzzyTalk>
BALINQUIRY Full Response (Completely Invalid Account Number)
<XyzzyTalk>

<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='BALINQUIRY' app_version='1108607'
             date_time='2013-03-29T09:19:23-07:00' tz='MST'/>

<CCX_RESPONSE>

  <Tran cduprid='1121762690512929283' dt='2013-03-29T09:19:00' clk='0'/>

  <Info>

    <Bal bf='UNKN,INVL'/>

  </Info>

</CCX_RESPONSE>

</XyzzyTalk>

Stored-Value Charge (CHARGE)

CHARGE Minimal Client Request

<XyzzyTalk>
  <XyzzyHeader api_id='CUSCNX' api_command='CHARGE'/>
  <CCX_QUERY>
    <Card id='RPGIFT' num='901012011200016'/>
    <Loc loc='906'/>
    <Tran cref='102' dt='2008-05-20'/>
    <Parms parm1='567'/>
  </CCX_QUERY>
/XyzzyTalk>

Note that dt= in the above example has only the date, not the date and time. loc= is required. Technically, neither cref= nor dt= is required, so the entire <Tran> element could be eliminated.

CHARGE Minimal Server Response
<XyzzyTalk>
  <CCX_RESPONSE>
    <Tran sref='1188'/>
    <Parms parm1='567'/>
    <Info>
      <Bal cd='$US5.5'/>
    </Info>
  </CCX_RESPONSE>
</XyzzyTalk>

where the cd='$US5.5' means the account is now limited to $5.50 after the charge, which is the prior $11.17 minus the $5.67 charged. parm1= is the amount charged in pennies, which can just be echoed back from the parm1= in the CHARGE command. Finally, the sref= may be given as a transaction reference number from the server. If not applicable, please send back the cref= number from the CHARGE.

CHARGE Minimal Error Response
<XyzzyTalk>
<XyzzyHeader err_num='2' err_flags='svr,Log,Disp' err_desc='Declined'/>
</XyzzyTalk>

where err_num= can be any number and err_desc= can be any string to be displayed and/or printed.

CHARGE Full Post

RPOWER itself will always send a QUERY (described above) at some point before a CHARGE. The XML to the server for the CHARGE will look something like:

<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='CHARGE' app_version='1108607'
             date_time='2013-03-18T16:11:39-07:00' tz='MST'/>
<CCX_QUERY>

  <Card f='S' id='RPQKCSH' t2='901012021200014' num='901012021200014'
        acct='901012021200014'/>

  <Loc co='RPOWER(tm) Restaurant POS #SAMP' loc='1' sta='SAMPLE' sid='SAMPLE'/>

  <Tran crefstr='CpWluo0BeQu;CpWlupH1l3w;3GJ47K3G5Y;20130318,A,131;47541855'
        cduprid='1119277872451948895' dt='2013-03-18T16:11:00' clk='101' clki='RF'/>

  <Parms parm1='863' parm2='200' trk1='1063'/>

  <Amts it='$US8' nc='1' xc1='1' tax='$US0.63' tip='$US2' pdp='77' pcd='$US18.33'
        charge_d='$US10.63'/>

</CCX_QUERY>
</XyzzyTalk>

Out of this, the following strings are important:

api_command='CHARGE' 
The command to charge.
id='RPGIFT' 
references the CRM program ID matching the id=... setting in the CardRule= line under the appropriate [SERVICE ...] section in the corporate server's CUSCNX.ini.
num='901012011200016' 
Card number.
f='S' 
S means swiped. M means manually entered.
loc='906' 
The "RPOWER store number." This is normally the RPOWER license serial number of the site.
cvc='5432' 
"Card verification value" entered by the user, if present.
parm1='567' 
The base amount to be charged in pennies.
parm2='0' 
The tip amount, not shown in the example. If tips are not accepted, parm2= can be ignored. The example shows how zero or blank amounts are suppressed from the XML to avoid clutter.
cref='102' 
The RPOWER ticket (check) number. In order to void a transaction this must be sent along with the sref value sent back in the response.
crefstr='06452310102' 
The 11-digit RPOWER statement reference number that encodes the store ID and ticket date, shift, and number.
dt='2008-05-20T13:07:00' 
The transaction date (and, optionally, time).
charge_d='$US5.67' 
The total charge amount (parm1 + parm2) in dollars, but we recommend not using it since other commands use parm1= and there is no need to depart from that.

Other fields in this request of lesser importance:

t2='901012011200016' 
Track 2 from the magnetic stripe. This may contain more information than just the card number, typically after an equals (=) sign.
co='DONATO'S Italian Sports Bar & Sushi' 
"Company" name.
sta='BAR3' 
Workstation name.
sid='13' 
Workstation ID.
cseq='834' 
Client-generated sequence number. Not used by the RPOWER server.
ddupstr='K3%8&apos;!!+gt' 
Duplicate transaction prevention string.
clk='101' 
"Clerk" ID number.
clki='RF' 
Clerk's initials.
trk1='567' 
Primary "tracking" amount. Typically the grand total of the check.
it='$US5.25' 
One of a number of tracking, secondary, or courtesy amounts. This one is the "item total" on the check (not including tax, tip, and gratuity).
tax='$US0.42' 
Tax total of the check.
pcd='$US11.17' 
"Previous charge dollars" — the card's charge balance returned by the QUERY operation performed when the card was first swiped. Some gift card providers can't figure this out for themselves.
charge_d='$US5.67' 
The total amount being charged, in dollars.
CHARGE Full Response
<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='CHARGE' app_version='1108607'
             date_time='2013-03-18T16:11:39-07:00' tz='MST'/>
<CCX_RESPONSE>

  <Tran crefstr='CpWluo0BeQu;CpWlupH1l3w;3GJ47K3G5Y;20130318,A,131;47541855'
        cduprid='1119277872451948895' srefstr='NE6/V8;CpWlvKgqplo'
        dt='2013-03-18T16:11:00' clk='101' clki='RF'/>

  <Parms parm1='1063'/>

  <Info>

    <Bal bf='CLMT,LMTD,ANON,LOYL,PPAY,MMOK,DPTS,PPTS,DBAL,PBAL,CBAL,CUSCNX'
         tf='AD,RP,RDP,CD,A,D,NC,ED' dp='85' rp='-1' rd='$US-0.01' dcd='$US7.7'
         cd='$US7.7'/>

    <TTD accum_p='85'/>

  </Info>

  <Card f='S,PRI,EXC' acct='901012021200014'/>

</CCX_RESPONSE>
</XyzzyTalk>

Receive On Account (RECEIVE, RECVACT, and AUTORECEIVE)

AUTORECEIVE works after a successful AUTOREDEEM transaction by RECEIVing the exact same non-zero dollars originally from the Bal.rd= in the PURCHASE reply.

RECEIVE Minimal Client Request

<XyzzyTalk>
  <XyzzyHeader api_id='CUSCNX' api_command='ACTIVATE'/>
  <CCX_QUERY>
    <Card id='RPGIFT' num='901012011200016'/>
    <Loc loc='906'/>
    <Tran cref='103' dt='2008-05-20'/>
    <Parms parm1='1000'/>
  </CCX_QUERY>
/XyzzyTalk>

Note that dt= in the above example has only the date, not the date and time. loc= is required. Technically, neither cref= nor dt= is required, so the entire <Tran> element could be eliminated.

RECEIVE Minimal Server Response
<XyzzyTalk>
  <CCX_RESPONSE>
    <Tran sref='1188'/>
    <Parms parm1='1000'/>
    <Info>
      <Bal cd='$US15.5'/>
    </Info>
  </CCX_RESPONSE>
</XyzzyTalk>

where the cd='$US15.5' means the account is now limited to $15.50 after the receive, which is the prior $5.50 plus $10.00 received. parm1= is the amount received in pennies, which can just be echoed back from the parm1= in the RECEIVE command. Finally, the sref= may be given as a transaction reference number from the server. If not applicable, please send back the cref= number from the RECEIVE.

RECEIVE Full Post

<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='RECEIVE' app_version='1108607'
             date_time='2013-03-18T16:19:18-07:00' tz='MST'/>
<CCX_QUERY>

  <Card f='S' id='RPQKCSH' t2='901012021200022' num='901012021200022'
        acct='901012021200022'/>

  <Loc co='RPOWER(tm) Restaurant POS #SAMP' loc='1' sta='SAMPLE' sid='SAMPLE'/>

  <Tran crefstr='CpWmckFdM0O;CpWmcknM5mW;3G26U2EE5Y;20130318,A,136;48184671'
        cduprid='1119279103731336031' dt='2013-03-18T16:19:00' clk='101' clki='RF'/>

  <Parms parm1='750'/>

  <Amts nc='1' hsh='$US7.5' pdp='127' prp='100' prd='$US10' receive_d='$US7.5'/>

</CCX_QUERY>
</XyzzyTalk>
RECEIVE Full Response
<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='RECEIVE' app_version='1108607'
             date_time='2013-03-18T16:19:14-07:00' tz='MST'/>
<CCX_RESPONSE>

  <Tran crefstr='CpWmckFdM0O;CpWmcknM5mW;3G26U2EE5Y;20130318,A,136;48184671'
        cduprid='1119279103731336031' srefstr='NE6/VC;CpWmcJ89YeW'
        dt='2013-03-18T16:19:00' clk='101' clki='RF'/>

  <Parms parm1='750'/>

  <Info>

    <Bal bf='CLMT,LMTD,ANON,LOYL,PPAY,MMOK,DPTS,PPTS,DBAL,PBAL,CBAL,CUSCNX'
         tf='AD,RP,RDP,CD,A,D,NC,ED' dp='127' rp='100' rd='$US10' dcd='$US7.5'
         cd='$US7.5'/>

    <TTD accum_p='127'/>

  </Info>

  <Card f='S,PRI,EXC' acct='901012021200022'/>

</CCX_RESPONSE>

</XyzzyTalk>

Loyalty Accumulate Dollars (PURCHASE and PURCHACT)

PURCHASE (Dollars) Minimal Client Request

TODO 
Need this.
PURCHASE (Dollars) Minimal Server Response
TODO 
Need this.

PURCHASE (Dollars) Full Query

<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='PURCHACT' app_version='1108607'
             date_time='2013-03-18T16:11:00-07:00' tz='MST'/>
<CCX_QUERY>

  <Card f='S' id='RPQKCSH' t2='901012021200022' num='901012021200022'
        acct='901012021200022'/>

  <Loc co='RPOWER(tm) Restaurant POS #SAMP' loc='1' sta='SAMPLE' sid='SAMPLE'/>

  <Tran crefstr='CpWlrYYYJv4;AAAAAAAAAAA;3GJ32JXG5Y;20130318,A,130;21723999'
        cduprid='1119277766721805919' dt='2013-03-18T16:11:00' clk='101' clki='RF'/>

  <Parms parm2='800' trk1='863'/>

  <Amts it='$US8' nc='1' xc1='1' tax='$US0.63' accum_d='$US8'/>

  <Ticket ref='CpWlrYYYJv4,3GJ32JXG5Y,130' dt='2013-03-18T16:10:00' dlvt='DINEIN'
          asap='1' tax='$US0.63' gttl='$US8.63' pcenter='1'/>

</CCX_QUERY>
</XyzzyTalk>
PURCHASE (Dollars) Full Response
<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='PURCHACT' app_version='1108607'
             date_time='2013-03-18T16:10:56-07:00' tz='MST'/>
<CCX_RESPONSE>

  <Tran crefstr='CpWlrYYYJv4;AAAAAAAAAAA;3GJ32JXG5Y;20130318,A,130;21723999'
        cduprid='1119277766721805919' srefstr='NE6/V6;CpWlrFOccvA'
        dt='2013-03-18T16:11:00' clk='101' clki='RF'/>

  <Parms parm1='8'/>

  <Info>

    <Bal bf='CLMT,LMTD,ANON,LOYL,PPAY,MMOK,DPTS,PPTS,DBAL,PBAL,CBAL,CUSCNX'
         tf='AD,RP,RDP,CD,A,D,NC,ED' dp='8' rp='-1' rd='$US-0.01' dcd='$US-0.01'
         cd='$US-0.01'/>

    <TTD accum_p='8'/>

  </Info>

  <Card f='S,PRI,EXC' acct='901012021200022'/>

</CCX_RESPONSE>
</XyzzyTalk>

Loyalty Accumulate Points (PURCHASE and PURCHACT)

PURCHASE (Points) Minimal Client Request

TODO 
Need this.
PURCHASE (Points) Minimal Server Response
TODO 
Need this.

PURCHASE (Points) Full Query

<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='PURCHASE' app_version='1108607'
             date_time='2013-03-18T16:15:30-07:00' tz='MST'/>
<CCX_QUERY>

  <Card f='S' id='RPQKCSH' t2='901012021200022' num='901012021200022'
        acct='901012021200022'/>

  <Loc co='RPOWER(tm) Restaurant POS #SAMP' loc='1' sta='SAMPLE' sid='SAMPLE'/>

  <Tran crefstr='CpWmGcJOedg;AAAAAAAAAAA;3GJE7WW95Y;20130318,A,132;98620767'
        cduprid='1119278491171903839' dt='2013-03-18T16:15:00' clk='101' clki='RF'/>

  <Parms parm1='15' trk1='1050'/>

  <Amts it='$US9.66' nc='1' xc2='3' tax='$US0.84' pdp='8' accum_p='15'/>

  <Ticket ref='CpWmGcJOedg,3GJE7WW95Y,132' dt='2013-03-18T16:15:00' dlvt='DINEIN'
          asap='1' tax='$US0.84' gttl='$US10.5' pcenter='1'/>

</CCX_QUERY>
</XyzzyTalk>
PURCHASE (Points) Full Response
<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='PURCHASE' app_version='1108607'
             date_time='2013-03-18T16:15:27-07:00' tz='MST'/>
<CCX_RESPONSE>

  <Tran crefstr='CpWmGcJOedg;AAAAAAAAAAA;3GJE7WW95Y;20130318,A,132;98620767'
        cduprid='1119278491171903839' srefstr='NE6/V9;CpWmGtJtRVQ'
        dt='2013-03-18T16:15:00' clk='101' clki='RF'/>

  <Parms parm1='15'/>

  <Info>

    <Bal bf='CLMT,LMTD,ANON,LOYL,PPAY,MMOK,DPTS,PPTS,DBAL,PBAL,CBAL,CUSCNX'
         tf='AD,RP,RDP,CD,A,D,NC,ED' dp='23' rp='-1' rd='$US-0.01' dcd='$US-0.01'
         cd='$US-0.01'/>

    <TTD accum_p='23'/>

  </Info>

  <Card f='S,PRI,EXC' acct='901012021200022'/>

</CCX_RESPONSE>
</XyzzyTalk>

Loyalty Redeem Dollars (REDEEM and AUTOREDEEM)

AUTOREDEEM is the same as REDEEM, but always for dollars, not points. It works upon a reply to any PURCHASE transaction by immediately and automatically REDEEMing any non-zero Bal.rd= redemption dollars contained therein, thereby using up those dollars and getting the account back down to zero.

REDEEM (Dollars) Minimal Client Request

TODO 
Need this.
REDEEM (Dollars) Minimal Server Response
TODO 
Need this.

REDEEM (Dollars) Full Query

TODO 
Do we redeem dollars? Sure!
REDEEM (Dollars) Full Response
TODO 
Do we redeem dollars? Sure!

Loyalty Redeem Points (REDEEM)

REDEEM (Points) Minimal Client Request

TODO 
Need this.
REDEEM (Points) Minimal Server Response
TODO 
Need this.

REDEEM (Points) Full Query

<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='REDEEM' app_version='1108607'
             date_time='2013-03-18T16:23:51-07:00' tz='MST'/>
<CCX_QUERY>

  <Card f='S' id='RPQKCSH' t2='901012021200022' num='901012021200022'
        acct='901012021200022'/>

  <Loc co='RPOWER(tm) Restaurant POS #SAMP' loc='1' sta='SAMPLE' sid='SAMPLE'/>

  <Tran crefstr='CpWm2J6BbFk;AAAAAAAAAAA;3G3J34535Y;20130318,A,138;27169631'
        cduprid='1119279836732889951' dt='2013-03-18T16:23:00' clk='101' clki='RF'/>

  <Parms parm1='15' trk1='6250'/>

  <Amts it='$US62.5' nc='1' xc1='10' dsc='$US-10' tax='$US4.15' pdp='180' prp='150'
    prd='$US15' redeem_p='15'/>

  <Ticket ref='CpWm2J6BbFk,3G3J34535Y,138' dt='2013-03-18T16:23:00' dlvt='DINEIN'
          asap='1' tax='$US4.15' gttl='$US56.65' pcenter='1'/>

</CCX_QUERY>
</XyzzyTalk>
REDEEM (Points) Full Response
<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='REDEEM' app_version='1108607'
             date_time='2013-03-18T16:23:47-07:00' tz='MST'/>
<CCX_RESPONSE>

  <Tran crefstr='CpWm2J6BbFk;AAAAAAAAAAA;3G3J34535Y;20130318,A,138;27169631'
        cduprid='1119279836732889951' srefstr='NE6/VF;CpWm2CuAvS6'
        dt='2013-03-18T16:23:00' clk='101' clki='RF'/>

  <Parms parm1='15'/>

  <Info>

    <Bal bf='CLMT,LMTD,ANON,LOYL,PPAY,MMOK,DPTS,PPTS,DBAL,PBAL,CBAL,CUSCNX'
         tf='AD,RP,RDP,CD,A,D,NC,ED' dp='165' rp='150' rd='$US15' dcd='$US-0.01'
         cd='$US-0.01'/>

    <TTD accum_p='180'/>

  </Info>

  <Card f='S,PRI,EXC' acct='901012021200022'/>

</CCX_RESPONSE>
</XyzzyTalk>

Void Transaction (VOID)

VOID Minimal Client Request

<XyzzyTalk>
  <XyzzyHeader api_id='CUSCNX' api_command='VOID'/>
  <CCX_QUERY>
    <Tran cref='102' sref='1188'/>
  </CCX_QUERY>
</XyzzyTalk>
VOID Minimal Server Response
<XyzzyTalk>
  <CCX_RESPONSE>
   <Parms parm1='567'/>
   <Info>
     <Bal cd='$US11.17'/>
   </Info>
  </CCX_RESPONSE>
</XyzzyTalk>

parm1= and cd= are important. parm1= may simply be echoed back. cd= is the new spending limit after the void.

One could conceivably implement VOID using the same mechanism as CHARGE, only internally switching the sign on parm1= before posting. It is important however, to switch it back on the response (positive in, positive out).

VOID Full Post

<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='VOID' app_version='1108607'
             date_time='2013-03-18T16:27:57-07:00' tz='MST'/>
<CCX_QUERY>

  <Card f='S' id='RPQKCSH' t2='901012021200022' num='901012021200022'
        acct='901012021200022'/>

  <Loc co='RPOWER(tm) Restaurant POS #SAMP' loc='1' sta='SAMPLE' sid='SAMPLE'/>

  <Tran crefstr='CpWnLY3qHVs;AAAAAAAAAAA;3G3927G75Y;20130318,A,139;88274527'
        cduprid='1119280496585203551' srefstr='NE6/VH;CpWnLIrzaTY'
        dt='2013-03-18T16:27:00' clk='101' clki='RF'/>

  <Parms parm1='7'/>

  <Amts pdp='164' prp='150' prd='$US15'/>

</CCX_QUERY>
</XyzzyTalk>

Out of this, the following strings are important:

api_command='VOID' 
The command to void.
num='901012011200016' 
Card number.
f='S' 
S means swiped. M means manually entered.
cvc='5432' 
"Card verification value" entered by the user.
parm1='567' 
The base amount to be voided in pennies.
parm2='0' 
The tip amount. See Charge Account for more information.
cref='102' 
The RPOWER ticket (check) number. The RPOWER server needs this and sref=.
sref='1188' 
Information sent by the server in the CHARGE response. The RPOWER server needs this and cref=.
VOID Full Response
<XyzzyTalk>
<XyzzyHeader xyzzy_version='6.10.29.4' api_id='CUSCNX' api_version='12.2.11.1'
             api_command='VOID' app_version='1108607'
             date_time='2013-03-18T16:27:52-07:00' tz='MST'/>
<CCX_RESPONSE>

  <Tran crefstr='CpWnLY3qHVs;AAAAAAAAAAA;3G3927G75Y;20130318,A,139;88274527'
        cduprid='1119280496585203551' srefstr='NE6/VH;CpWnLIrzaTY'
        dt='2013-03-18T16:27:00' clk='101' clki='RF'/>

  <Parms parm1='7'/>

  <Info>

    <Bal bf='CLMT,LMTD,ANON,LOYL,PPAY,MMOK,DPTS,PPTS,DBAL,PBAL,CBAL,CUSCNX'
         tf='AD,RP,RDP,CD,A,D,NC,ED' dp='171' rp='150' rd='$US15' dcd='$US-0.01'
         cd='$US-0.01'/>

    <TTD accum_p='186'/>

  </Info>

  <Card f='S' acct='901012021200022'/>

</CCX_RESPONSE>
</XyzzyTalk>

Batch Settlement (SETTLE)

SETTLE Minimal Client Request

There is no need for minimal clients to send this transaction. It is just a formality.

SETTLE Minimal Server Response

Please just send parm1= from the post back as follows:

<XyzzyTalk>
  <CCX_RESPONSE>
    <Parms parm1='567'/>
  </CCX_RESPONSE>
</XyzzyTalk>

SETTLE Full Post

At the end of day, RPOWER sends a totals record to the server and expects some sort of response as a courtesy. The XML looks something like:

TODO 
need this post

Out of this, the following strings are important:

api_command='SETTLE' 
The Settlement command.
parm1='567' 
The total of all activity for the day.
SETTLE Full Response
TODO 
Need this post.

POSTTICKET

xxx Minimal Client Request

TODO 
Need this.
xxx Minimal Server Response
TODO 
Need this.

Full Query

TODO 
Need this.
Full Response
TODO 
Need this.

Meal Plan Use Dollars (USEPLAN and PLANACT)

USEPLAN Minimal Client Request

TODO 
Need this.
USEPLAN Minimal Server Response
TODO 
Need this.

USEPLAN Full Query

TODO 
Need this.
USEPLAN Full Response
TODO 
Need this.

Deactivate Card (DEACTIVATE)

DEACTIVATE Minimal Client Request

TODO 
Need this.
DEACTIVATE Minimal Server Response
TODO 
Need this.

DEACTIVATE Full Query

TODO 
Need this.
DEACTIVATE Full Response
TODO 
Need this.

Transfer Card (NEWCARD)

NEWCARD Minimal Client Request

TODO 
Need this.
NEWCARD Minimal Server Response
TODO 
Need this.

NEWCARD Full Query

TODO 
Need this.
NEWCARD Full Response
TODO 
Need this.

CUSCNX API Records, Flags, and Enums

First of all, CUSCNX uses the Xyzzy Built-In API Records, Flags, and Enums.

General Query Structure

<?xml version="1.0"?>
<XyzzyTalk>
<XyzzyHeader .../>
  <CCX_QUERY>
    <Card ... />
    <Loc ... />
    <Tran ... />
    <Parms ... />
    <Amts ... />
    <Ticket ... />
  </CCX_QUERY>
</XyzzyTalk>

General Response Structure

<?xml version="1.0"?>
<XyzzyTalk>
<XyzzyHeader ... />
  <CCX_RESPONSE>
    <Tran ... />
    <Parms ... />
    <Info>
      <Bal ... />
      <TTD ... />
    </Info>
    <Card ... />
   </CCX_RESPONSE>
</XyzzyTalk>

Element Overview

<?xml version="1.0"?> 
Added as a formality. Otherwise ignored.
<XyzzyTalk> 
Outer pure wrapper element with no attributes.
<XyzzyHeader ... /> 
API function call information.
<CCX_QUERY> 
Outer wrapper for a client query to a server — no attributes.
<CCX_RESPONSE> 
Outer wrapper for a server response to a clinet — no attributes.
<Parms ... /> 
Parameters and required tracking amounts unique to each API function call.
<Card ... /> 
Card and/or customer and/or account identification data.
<Loc ... /> 
Store and workstation (register) identification data.
<Tran ... /> 
Transaction identification data, including ticket or guest check identification, plus server (or operator or clerk) identification.
<Amts ... /> 
Additional generic amounts and optional tracking values associated the the transaction.
<Ticket ... /> 
A much more detailed description of a sale from the POS than just generic tracking data contained in <Tran> and <Amts>. <Ticket> can contain other detailed elements such as <ShipTo>, an array of <Item> records and an array of <Payment> records.

Response Elements

<Info> 
Container for either account balance and other information for a single selected account or an array of "customer selection" (<XFR_CUS>) records for reselection.
<Bal> 
"Balance" flags and amounts.
<Program> 
Filled on on balance inquiry only. Importantly, contains program ID and name strings in case the client does not know them in advance. Also contains full server CUSCNX.ini setup strings which are technically not required by a client.
<TTD> 
Total To Date "accumulation" amounts.
<Cus> 
If Info.nselcus is non-zero, <Info> contains an array of these records (instead of <Bal> and <TTD>) to be presented for selection by the user. The client then queries the selected Info.Cus.Card.num as if were the original card number. Notably, the server can return a single <Cus> record (with nselcus='1') to force a requery of the selected record by the POS without user interaction.

Xyzzy Built-In API Records, Flags, and Enums

These are the Xyzzy Built-In API Records, Flags, and Enums used by CUSCNX:

CUSCNX Parameters Record (CCX_TXPARMS) <Parms>

Integer transaction parameters. Money is given in "cents."

parm1 (int32)  
API function parameter #1.
parm2 (int32)  
API function parameter #2.
parm3 (int32)  
API function parameter #3.
parm4 (int32)  
API function parameter #4.
trk1 (int32)  
Tracking total #1
trk2 (int32)  
Tracking total #2
trk3 (int32)  
Tracking total #3
trk4 (int32)  
Tracking total #4
trk5 (int32)  
Tracking total #5
trk6 (int32)  
Tracking total #6
trk7 (int32)  
Tracking total #7
trk8 (int32)  
Tracking total #8
trk9 (int32)  
Tracking total #9
<Card2> (XFR_CARD) 
"New" (transfer-to, e.g.) card.

CUSCNX Customer Information (CCX_CUSINFO) <Info>

nselcus (int32)  
array for multiple selection; -1 means not found.
<Cus> (XFR_CUS)  
<Bal> (CCX_BALANCE) 
<MTD> (CCX_ACCUM)  
<YTD> (CCX_ACCUM)  
<TTD> (CCX_ACCUM)  

CUSCNX Balance Flags 1 (fCCX_CUSBAL) bf=

Primary Balance Flags
CASH 
Cash-only — no charging allowed (same as credit limit zero).
CLMT 
A "member" spending limit is present. This is typical for gift and prepaid accounts.
ALMT 
An "account" spending limit is present. This is typical for "billing" (house) accounts. For loyalty programs, the point balance is stored on the account (group of members), not the individual member as is normally done.
HOLD 
The member or account is on credit hold.
AHLD 
The account is on hold.
OHLD 
A "customer setup" manager can override a credit hold.
LMTD 
Spending is limited (to available credit). This is typical of any prepaid account but not house accounts.
LMTA 
Spending limit comes from from the account, not the member; also true if AHLD is set.
OLMT 
A "customer setup" manager can override a spending limit.
ANON 
Anonymous — not a "regular" named customer.
LOYL 
Loyalty account in addition to any one the glags below.
BILL 
"House" (bill-behind) account. Generally this means that members may charge but the accounts to which they belong pay the bills (receive money). The accounts may have credit limits but members typically only have daily spending limits, if anything.
PPAY 
"Prepaid" account. Generally this means that the members receive money (not accounts), which determines how much money they have to charge.
GIFT 
"Gift." Same as PPAY but may print on receipts differently.
ALOW 
"Allowance." Similar to PPAY but may may print on receipts differently.
PLAN 
On a "meal plan" in addition to any of the flags below.
More Balance Flags
MMEM 
Account has more than one member ("multi-member"). Regular house (BILL) account members are not shown the account balance due on receipts unless they are the only member.
MMOK 
An internal flag indicating that the account has been checked to see if it is multi-member.
DPTS 
Display loyalty points on the screen.
PPTS 
Print loyalty points on receipts.
CPTS 
Display loyalty points on a customer (pole) display.
DBAL 
Display charge balance dollars on the screen.
PBAL 
Print charge balance dollars on receipts.
CBAL 
Display charge balance dollars on a customer (pole) display.
UNKN 
Charge balances and limits are unknown. This could be due, for example, to a communication error with a third-party host.
OFFL 
The transaction in question is proceeding in an offline mode according to the last good information obtained.
NDAC 
The card or account in question is inactive, and therefore needs activation.
DEAC 
The card or account has been deactivated and is not valid for any transactions.
NPOP 
Do not pop up DispMsg (display message) pop-up notes.
INVL 
The card is invalid (unrecognizable), and therefore will also be UNKN. It is not valid for any transactions.
EXTERN 
The provider is external to the POS — also referred to as "batch mode." All transactions are approved. No account records are created, no balances stored, no history kept. At the end of the day the transactions will be exported somewhere and forgotten.
CUSCNX 
An internal flag, always set, indicating that this account is from the CUSCNX interface (what this article is about) and not something else.

CUSCNX Balance Flags 2 (fCCX_CUSBAL2) bf2=

  • GNRC  : Customer has generic name (not the same as "anonymous").
  • PLNA  : Meal plan comes from from account, not member.
  • NRCPT  : No receipt print (default true for loyalty).
  • RCPT  : Force receipt print (default false for gift card).
  • PARRD  : (internal) RD= was calculated from par price and quantity.
  • RETRWD : Transaction returns rewards, so if there aren't any, the rewards from the original QUERY need to be removed.
  • CANRW  : Customer account is rewards-based.
  • HASRW  : Customer has one or more rewards.
  • RESEL  : (internal) Customer is not real! Client handler had the operator select it from a list of <CCX_RESPONSE.Info.Cus> and wants a requery of the selected Cus.Card.num=.
  • MNYPTS : Display points using money decimals (e.g., 12345 points = "123.45").
  • UPC49  : Customer is a (free-standing) "coupon," not a real customer.

CUSCNX Transaction Flags (fCCX_CUSTRAN) tf=

These flags indicate what types of transactions are allowed on the POS.

  • AD : Accumulate loyalty dollars. Dollars are converted to points based on PointsPerDollar settings.
  • AP : Accumulate loyalty points. Points are added according to hard-set values associated with menu items.
  • ALIFCD : Accumulate loyalty points (on this check) only when using this same (prepaid!) card to pay (any amount) on this (same) check. The customer is being rewarded for using his or her prepaid stored value account and would not receive any points if paying cash.
  • RAED : Automatically redeem loyalty points by performing an ED (Receive Dollars) transaction according to CentsPerPoint (and DivideCentsPerPointBy) settings. ED itself does not have to be set. That depends on whether one wants to allow the customer to prepay balances on the card as opposed to accruing loyalty rewards only.
  • RDP : Redeem loyalty discounts from the account's loyalty point balance according to the dollar amount of the discount. This is the most common way to redeem loyalty points. Discounts dollars are converted to points to be deducted according to CentsPerPoint and DivideCentsPerPointBy settings. DivideCentsPerPointBy is a denominator used for all CentsPerPoint values so you can assign fractional values to various point levels.
  • RP : Redeem loyalty points directly via items or discounts.
  • RD : Redeem loyalty discounts from the account's stored value (prepaid) account dollars balance. This may be used in conjunction with the RAED transaction that will presumbably have already fired and put money on the account.
  • RDPA : Redeem unlimited loyalty dollars via discounts. This is meant for a different kind of third-party loyalty provider who doesn't actually accrue point balances but instead only tracks the discounts being used that came from a source other than (or indirectly from) the POS.
  • CDP : Charge loyalty dollars via the account's point balance. This transaction is not used by RPOWER.
  • CD : Charge stored value account dollars. This is the how prepaid and house accounts pay for things. The card is associated with a Payment Method via its TenderKey number.
  • ED : Receive stored value dollars. This is how prepaid and house accounts receive money.
  • A : Activate. Indicates that the server should set the NDAC balance flag if the account does not exist in the system, instructing the client to use an RECVACT command instead of RECEIVE, PURCHACT instead of PURCHASE, and PLANACT instead of USEPLAN. The RPOWER built-in server can always take the "activate" methods regardless of activation state, so if the client is designed always to activate non-active accounts in the first place, it can just send RECVACT, PURCHACT, and PLANACT transactions all the time.
  • AA : In addition to A, instructs the server to activate an account automatically upon a QUERY (done on a card swipe).
  • EAO : (E-A-Oh, not -zero) Receive stored value dollars allowed only upon card activation. Once a card has ever had a balance, it cannot be added to until it is deactivated (deleted).
  • EAZ : Receive stored value dollars upon activation (only) for zero dollars. Instructs the POS to not charge anything for the activation of this card, regardless of amount received. New cards allowing this transaction need to be kept under lock and key.
  • D : Deactivate. Indicates that the card may be "deactivated."
  • NC : "New Card." Indicates that the card may be transferred to another card, in particular if the magnetic stripe can't be read. This lets RPOWER allow key-entry of the card number without manager restrictions as long as the new card is swiped.
  • EOT : Receive overtender automatically. Instructs the POS to allow overtendering credit cards if not enough money is available to pay a check, and allow overtenderd amounts (cash or credit) to be applied back to the card as appropriate.
  • EDP : Receive loyalty dollars. This transaction is not used by RPOWER.
  • MPU : This accounts supports "meal plan" transactions.
  • EODLTKT : Post POSTTICKET transactions on closed loyalty checks belonging to this program.
  • EODATKT : Post POSTTICKET transactions on all closed checks regardless of loyalty state or provider.
  • LTKM : Include ticket items (CCX_TKITEM <Item> records) with loyalty POSTTICKET information.
  • LTKP : Include ticket payments (CCX_TKPAY <Payment> records) with loyalty POSTTICKET information.

CUSCNX Balances Record (CCX_BALANCE) <Bal>

bf (fCCX_CUSBAL)  
bf2 (fCCX_CUSBAL2) 
tf (fCCX_CUSTRAN) 
Loyalty and Reward Data
dp (int32)  
Display (redemption) point value.
pp (int32)  
Previous (redemption) point value.
rp (int32)  
Redemption points avail via RP.
rd (money)  
Redemption dollars avail (limit) via RD (if exists). Set by server, but client adds up reward values!
nr (int32)  
Number of rewards in *<Reward> array.
<Reward>[nr] (CCX_REWARD)  
Charge plan data
dcd (money)  
Charge dollars print and display (0=use cd=.)
cd (money)  
Charge dollars avail (limit) via CD.
dscp (number)  
Eligible discount percentage (1..100). Can use with RDPA as notification or limit.
Meal plan data
mpt (char)  
D,W, or M=dollar-based, d, w, or m=ticket-based.
mp1 (number)  
Meal plan number/time/period 1 amount available.
mp2 (number)  
Meal plan #2 available.
mp3 (number)  
Meal plan #3 available.
mpmt1 (char)  
'1'..'9' or space (meal time).
mpmt2 (char)  
>= '1' means defined
mpmt3 (char)  
mpnd1 (int32)  
Quantity of items to drop.
mpnd2 (int32)  
mpnd3 (int32)  

CUSCNX Accumulator Record (CCX_ACCUM) <TTD><Amts>

Sales tracking totals
i1 (money) 
Item total #1 (optional)
i2 (money) 
i3 (money) 
i4 (money) 
it (money) 
Item total (required)
nc (int32) 
Customer count
xc1 (int32) 
Extra count 1
xc2 (int32) 
Extra count 2
xc3 (int32) 
Extra count 3
dsc (money) 
Discount total (usually negative)
hsh (money) 
HASH total
hshd (money) 
HASH discount total (usually negative)
grt (money) 
Calculated gratuity
tax (money) 
Tax total (we don't separate taxes)
tip (money) 
"Voluntary" gratuity
pdp (int32) 
Previous display points on account
pcd (money) 
Previous charge dollars cd
prp (int32) 
Previous redemption points avail via RP
prd (money) 
Previous redemption dollars avail (limit) via RD (if exists)
Transaction accumulator reference totals
n_accum_d (int32) 
Count of "pointable" adds
accum_d (money) 
"Pointable" dollar total for adding points
n_accum_p (int32) 
Count of point adds
accum_p (int32) 
Points added
n_redeem_d (int32) 
Count of dollar redemptions
redeem_d (money) 
Dollars redeemed
n_redeem_p (int32) 
Count of point redemptions
redeem_p (int32) 
Points redeemed
n_charge_d (int32) 
Count of charge transactions
charge_d (money) 
Dollars charged
n_receive_d (int32) 
Count of receive transactions
receive_d (money) 
Dollars received
n_deactivate_d (int32) 
Count of deactivate transactions
deactivate_d (money) 
Dollars transferred via deactivation
n_newcard (int32) 
Count of new-card transactions

CUSCNX Customer Record (XFR_CUS) <Cus>

uid (str15)  
Our own "universal" ID
xid (str15)  
External reference ID
n (pname)  
<Addr> (XFR_ADDR)  
<Ctct> (XFR_CONTACT) 
<Pop> (XFR_NOTE)  
Pop-up note
<Dir> (XFR_NOTE)  
Directions note
<Note> (XFR_NOTE)  
General note
<Card> (XFR_CARD)  
Primary ID card
<CrCard> (XFR_CARD)  
Primary credit card "on account"
bd (date)  
Birth date
ad (date)  
Anniversary date
sd (date)  
"Etart" date
ed (date)  
"End" date
ud1 (date)  
"User" date #1
ud2 (date)  
"User" date #2

CUSCNX POS Item Detail Record (CCX_TKITEM) <Item>

plu (str11)  
upc (str15)  
n (str63)  
pn (str63)  
wbn (str63)  
qty (number) 
p (money)  
ttl (money)  
ref (str63)  
Application reference
seat (uint32) 
Guest number
seats (uint64) 
Guest number bit flags 0..63

CUSCNX POS Ticket Payment Record (CCX_TKPAY) <Payment>

ref (str63) 
Web application reference
pmid (str23)
pm (str23)
note (str63)
amt (money)
tip (money)

CUSCNX POS Ticket Delivery Type (fCCX_DLVTYPE) dlvt=

Duplicated from POSCNX fPCX_DLVTYPE.

  • DELIVERY
  • TAKEOUT
  • CATERING
  • DINEIN

CUSCNX POS Ticket Record (CCX_TICKET) <Ticket>

ref (str63)  
dt (datetimel)  
Explicit local time.
dlvt (fCCX_DLVTYPE) 
need_dt (datetimel)  
Explicit local time. If not provided then programmed on web site.
note (str255)  
<ShipTo> (XFR_CUS)  
<Item>[n] (CCX_TKITEM)  
Array of items.
<Payment>[n] (CCX_TKPAY)  
Array of payments.
tax (money)  
Used if plu='tax' item not used.
tip (money)  
Used if plu='tip' item not used.
gttl (money)  
Optional grand balancing total.
pcenter (int32)  
Internal — profit center number.

CUSCNX Reward Flags (fCCX_REWARD) rf=

  • DVD : "Discount Via Dollars" type reward. Only type supported.
  • TIT : "Targeted Item" reward. Not used.
  • DRP : "Discount Item Drop" reward. Not used.
  • RDQ : Redeem quantity, not dollars.
  • RFA : One-at-a-time rewards.
  • L1 : This particular reward limit 1.
  • L1RWD : All rewards limit 1.
  • L1DSC : Reward discount limit 1.
  • NDLOYL : Requires a bf=LOYL customer for redemption.
  • NDRWD : Or requires a bf2=CANRW reward-based customer for redemption.
  • NDPPAY : Or requires a (any of) bf=BILL,PPAY,GIFT,ALOW customer for redemption.

CUSCNX Reward Record (CCX_REWARD) <Reward>

A CUSCNX reward record ties a loyalty system reward identified by ccode and rcxdata to an RPOWER discount menu item with a PLU of dplu. If dscp and/or damt are specified, they override the percentage and the dollar limit or amont of the discount. If iplu is specified, it overrides the discount itemizer of the discount. iplu can also target a single menu item or items with similar PLU's, in which case the discount can also be dropped as a modifier on that item. Finally, the damt of a discount can be looked up at the actual location using pplu (modified by ppno and pqty). pplu can be an actual menu item having a representative price or it can be a separate item specifically set up for this purpose.

type (int32)  
Not used.
rf (fCCX_REWARD) 
CUSCNX Reward Flags.
crc32sm (int32)  
Internal reward identifier.
dscp (number)  
Eligible discount percentage (1..100)
rwhat (str11)  
"Coupon", "Reward", "Discount", etc.
dplu (str11)  
Redemption discount PLU item dropped using rqty.
dqty (int32)  
1?
damt (money)  
Default and limit.
iplu (str23)  
"Item" or "Itemzier" "PLU." One of the following. The discount itemizer specified by this override the discount itemizer of the redemption discount.
  • Targeted item PLU. The actual PLU or UPC code of a menu item that is being discounted by the reward. When comparing numbers, an asterisk (*) in either number matches any character in the other number. If an item has both a PLU and a UPC, the PLU is used.
  • Discount itemizer name.
  • Discount itemizer MID (master ID, in DIZ.dbf).
  • Hexadecimal number representing the discount itemizer bit field.
qplu (str11)  
Redemption qualifying "family" PLU. Currently does nothing.
qqty (int32)  
Redemption qualifying quantity. Currently does nothing.
pplu (str11)  
"Par" or "price" PLU (or MID or UPC code) of an item to look up for client calculation of damt.
ppno (int32)  
The price level of pplu item to look up.
pqty (int32)  
The looked-up price is multiplied by this amount; it is not stored.
ccode (str11)  
Coupon code looked up and passed back for redemption.
rselstr (str95)  
Redemption selection string with replacable parameters, e.g., %dqty% and %dplu_name%.
rcxdata (str63)  
Redemption cxdata to passed with reward redemption Tran.cxdata.
expupto (date)  
This really means valid up to such that nowsecs < expsecs.

CUSCNX Command Query Record (CCX_QUERY) <CCX_QUERY>

<Card> (XFR_CARD)  
<Loc> (XFR_LOCATION) 
<Tran> (XFR_TRANHEAD) 
<Parms> (CCX_TXPARMS)  
<Amts> (CCX_ACCUM)  
<Info> (CCX_CUSINFO)  
Prior query balances.
<Ticket> (CCX_TICKET)  
<Reward> (CCX_REWARD)  

CUSCNX Command Reponse Record (CCX_RESPONSE) <CCX_RESPONSE>

<Tran> (XFR_TRANHEAD) 
Echo back from client.
<Parms> (CCX_TXPARMS)  
<Amts> (CCX_ACCUM)  
<Info> (CCX_CUSINFO)  
<Card> (XFR_CARD)  
acct= is used. f= should be but is not.
<DispMsg> (XFR_NOTE)  
Pop-up only — not stored!
<RcptMsg> (XFR_NOTE)  
Sales receipt message.
<Voucher> (XFR_NOTE)  
Sales receipt "voucher" or "coupon"
Views
Personal tools