Disclaimer

This document is only collection of author’s notes, experiences and point of views. It is not, in any meaning, either complete description of the topic nor official RTB documentation. It may be inaccurate, incomplete, obsolete, misleading or completely wrong. It may even cause loss of data or damage system integrity. It may not comply with company codex, values, presentation style or economic interests or may reveal company secrets.

As such, it is absolutely prohibited to distribute this document outside of RTB & Co. GmbH. Such an action may result into legal acts against both the sender and the company. It is only intended, after review of technical and presentational correctness and accuracy, to be used as an information source for official documentation.

Always contact documentation department for information about current presentation style and allowed formats before creating customer’s documentation.

1. Overview

This document describes integration with OneCard interface from TouchNet company. It is used on University of Waterloo.

Diagram
Figure 1. Flow chart of payment process

Blocks marked by yellow color indicate interaction with real time request service provided by PDM.control. Every green block perform and «operation».

To perform an «operation» consists from series of API call to achieve end result.

Diagram
Figure 2. Flow chart of performing single operation.

2. Real time requests (PDM)

Handling of requests is done via real time request framework developed earlier (Real time multi request).

Next chapters describes real time requests implemented to support required operations. Documentation always describes only content of mnemonic MRQ. JSON keys must not be enclosed in quotes as long as is continuing text (without spaces). Error handling is described in separated chapter below.

There are common types required for some arguments.

2.1. Account type

It indicates a source of account number. PDM must provide it to OneCard is able to find account int the database.

Account type tells origin on account number.
enum AccountType {
    Standard = 0, // Standard account
    Iso_Aba = 1, // ISO ABA account
    Prox = 2,  // Proximity account
    Custom = 3, // Custom account
    Smart = 4, // Smart Card account
    Email = 6, // account by e-mail address for LDAP authentication [pending]
    CAS = 8, // CAS account [pending]
    LDAP = 9, // LDAP account [pending]
    RAW = 10, // raw account type (for example, Track II data read by a card reader)
    ERP_ID = 11, // SIS ID account
    Username = 12, // account by Username
    MobileID = 13, // Mobile ID account
};

2.2. Login (REQ: 43)

Creates session to OneCard software. Session is needed for all other requests. Login can be called multiple times without side effect. Logins without logouts will automatically expires after some time (~15 minutes).

2.2.1. Request

A terminal ID where login was made is required.

Type of login request
type LoginRequest = {
    REQ: 43,
    terminalId: string // Please note that leading zeroes matters. Value "000000000224" ≠ "224"
};
Sample request from PDM
PSA10027;GAC00011;DTM2023-06-16T08:42:25;VER7.5.7.52;PID15727DED86;BRQ;TID00;MRQ[{REQ:43,terminalId:"000000000224"}];

2.2.2. Response

Request call returns session ID. PDM has to remember it and send with each subsequent request.

Type of login response
type LoginResponse = {
    REQ: 43,
    sessionId: string
};
Sample response from PDM.control
PSA10027;TIL15540102;DAT200623;GAC11;TIM1554;MRQ[{sessionId:"2debef15fc5945c09190c1978a53fb3b",REQ:43}];PVR1.23.0;ROK;CRC4DA6

2.2.3. Logout (REQ: 44)

Closes and invalidates session created by Login (REQ: 43). Logout can be called multiple times without side effect. If session is already deleted an error [-2102, "Invalid or Empty Login Session. Please, re-authenticate"] is thrown.

2.2.4. Request

Type of logout request
type LogoutRequest = {
    REQ: 44,
    sessionId: string
};
Sample request from PDM
PSA10027;GAC00011;DTM2023-06-16T08:42:25;VER7.5.7.52;PID15727DED86;BRQ;TID00;MRQ[{REQ:44,sessionId:"eac8ed4acc3c4cb6bdc62588ad90f816"}];

2.2.5. Response

Type of logout response
type LogoutResponse = {
    REQ: 44,
    success: boolean
};
Sample response from PDM.control
PSA10027;TIL11070403;DAT210623;GAC11;TIM1107;MRQ[{success:true,REQ:44}];PVR1.23.1;ROK;

2.2.6. Pre-init (REQ: 45)

Generate "transaction" number for next operation to make it idempotent.

2.2.7. Request

Type of pre-init request
type PreInitRequest = {
    REQ: 45,
    sessionId: string
};
Sample request from PDM
PSA10027;GAC00011;DTM2023-06-16T08:42:25;VER7.5.7.52;PID15727DED86;BRQ;TID00;MRQ[{REQ:45,sessionId:"1008c655c650414ba07a63946a7dbbf2"}];

2.2.8. Response

Type of pre-init response
type PreInitResponse = {
    REQ: 45,
    oneCardTransId: string
};
Sample response from PDM.control
PSA10027;TIL11141603;DAT210623;GAC11;TIM1114;MRQ[{oneCardTransId:"0b4f1399d46650125a3b3a0bef688b31",REQ:45}];PVR1.23.1;ROK;

2.2.9. Pre-cancel (REQ: 46)

Cancel "transaction" created by Pre-init (REQ: 45).

2.2.10. Request

Type of pre-cancel request
type PreCancelRequest = {
    REQ: 46,
    sessionId: string,
    oneCardTransId: string
};
Sample request from PDM
PSA10027;GAC00011;DTM2023-06-16T08:42:25;VER7.5.7.52;PID15727DED86;BRQ;TID00;MRQ[{REQ:46,sessionId:"7a7cc8dacc264f30a29ba8550cc08c85",oneCardTransId:"fd498b569ecb83def4353a0bef7493a0"}];

2.2.11. Response

Type of pre-cancel response
type PreCancelResponse = {
    REQ: 46,
    success: boolean
};
Sample response from PDM.control
PSA10027;TIL11281703;DAT210623;GAC11;TIM1128;MRQ[{success:true,REQ:46}];PVR1.23.1;ROK;

2.3. Inquiry balance of an account (REQ: 47)

Inquire balance of a card. It is necessary to define how to query. List below defines possible query types

enum TranType {
  FinancialBalanceQuery = 12, // Query rest amount without any additional actions.
  SpecialFieldQuery = 16, // Not used in our case.
  MealBalanceQuery = 18,  // Not used in our case.
  FinancialBalanceQueryWithLock = 21, // Lock required amount of money for further usage.
  CancelQueryLock = 23 // Release lock acquired by type 21.
};

2.3.1. Request

  • Parameter oneCardTransId is optional. If it is not used request runs without "transaction".

  • Parameter tranType is optional. If not used, default value FinancialBalanceQuery (12) is used.

  • Parameter bet is required only for TranType.FinancialBalanceQueryWithLock (21). It is ignored in other cases.

If amount of money is specified its currency must be USD. Otherwise an error is thrown.

Type of inquiry request
type InquiryRequest = {
    REQ: 47,
    sessionId: string, // Session ID obtained by login.
    oneCardTransId?: string, // OneCard transaction ID obtained form pre-init (optional).
    accountId: string, // ID of the account read from the card.
    accountType: AccountType, // Source of account ID.
    tranType?: TranType // What to query (see above). Default is 'FinancialBalanceQuery'.
    bet?: number // Amount to book. Scaled value x*10^DPA. Only for TranType.FinancialBalanceQueryWithLock, ignored otherwise.
};
Sample request from PDM
PSA10027;GAC00011;DTM2023-06-16T08:42:25;VER7.5.7.52;PID15727DED86;BRQ;TID00;MRQ[{REQ:47,sessionId:"2467fb406fd94cf78a7244bad78506ab",oneCardTransId:"42293ec70116ce3273cd3a0befe0cde7",accountId:"100044627",accountType:"0","tranType":21,bet:1}];DPA2;WKZUSD;

2.3.2. Response

Type of inquiry response
type InquiryResponse = {
    REQ: 47,
    oneCardTransId: string,
    balanceNoCredit: number // *10^DPA
};
Sample response from PDM.control
PSA10027;TIL13314103;DAT210623;GAC11;TIM1331;MRQ[{oneCardTransId:"42293ec70116ce3273cd3a0befe0cde7",balanceNoCredit:1,REQ:47}];PVR1.23.1;ROK;

2.4. Vend money (REQ: 48)

Do payment of amount of money. If reservation was done before, maximal amount of money for payment is limited by reservation. Currency must be USD otherwise an error is thrown.

It is strongly recommended to use this request together with OneCardTransID to make the payment idempotent.

2.4.1. Request

Type of vend money request
type VendMoneyRequest = {
    REQ: 48,
    sessionId: string, // Session ID obtained by login.
    oneCardTransId?: string, // OneCard transaction ID obtained form pre-init (optional).
    accountId: string, // ID of the account read from the card.
    accountType: AccountType, // Source of account ID.
    bet: number // Amount to book. Scaled value x*10^BZA.
};
Sample request from PDM
PSA10027;GAC00011;DTM2023-06-16T08:42:25;VER7.5.7.52;PID15727DED86;BRQ;TID00;MRQ[{REQ:48,sessionId:"2467fb406fd94cf78a7244bad78506ab",oneCardTransId:"e25ca13e7ec0538115f03a0beffd1108",accountId:"100044627",accountType:"0",bet:1}];DPA2;WKZUSD;

2.4.2. Response

Type of vend money response
type VendMoneyResponse = {
    REQ: 48,
    receipt: string,
    balanceNoCredit: number, // *10^DPA
    oneCardTransId: string
};
Sample response from PDM.control
PSA10027;TIL13574303;DAT210623;GAC11;TIM1357;MRQ[{oneCardTransID:"e25ca13e7ec0538115f03a0beffd1108",balanceNoCredit:99604,receipt:"Paymode: Onecard\r\nAccount: 100044627\r\nDate: 06/21/2023\r\nTime: 06:57:43\r\nTerminal: 00044 - RTB\r\nAmount: $         0.01\r\n",REQ:48}];PVR1.23.1;ROK;

2.5. Transaction result (REQ: 49)

Provide a result of "transaction" defined by OneCardTransID.

2.5.1. Request

Type of transaction result request
type VendMoneyRequest = {
    REQ: 49,
    sessionId: string, // Session ID obtained by login.
    oneCardTransId: string, // OneCard transaction ID obtained form any request which returns it.
};
Sample request from PDM
PSA10027;GAC00011;DTM2023-06-16T08:42:25;VER7.5.7.52;PID15727DED86;BRQ;TID00;MRQ[{REQ:49,sessionId:"2467fb406fd94cf78a7244bad78506ab",oneCardTransId:"e25ca13e7ec0538115f03a0beffd1108"}]

2.5.2. Response

Based on operation which generated OneCardTransID the result may slightly differ. See field resultType to distinguish among various cases. Currently there are following cases supported

enum ResultType {
  Unknown = "Unknown", // The "transaction" was not finished yet.
  Inquiry = "Inquiry", // Balance inquiry transaction
  VendMoney = "VendMoney" // Vend money transaction
}

Response structure depends on its type. .Type of vend money response

type TransactionInquiryResponse = {
    REQ: 49,
    resultType: "Inquiry"
    completed: string,
    balanceNoCredit: number, // *10^DPA
    oneCardTransId: string
};

type TransactionVendMoneyResponse = {
    REQ: 49,
    resultType: "VendMoney"
    completed: string,
    balanceNoCredit: number, // *10^DPA
    oneCardTransId: string,
    receipt: string
};
Sample response from PDM.control of type "Inquiry"
PSA10027;TIL14563504;DAT060723;GAC11;TIM1456;MRQ[{balanceNoCredit:996.04,completed:true,resultType:"Inquiry",REQ:49}];PVR1.23.1;ROK;
Sample response from PDM.control of type "VendMoney"
PSA10027;TIL13574303;DAT210623;GAC11;TIM1357;MRQ[{oneCardTransID:"e25ca13e7ec0538115f03a0beffd1108",resultType:"VendMoney",balanceNoCredit:99604,receipt:"Paymode: Onecard\r\nAccount: 100044627\r\nDate: 06/21/2023\r\nTime: 06:57:43\r\nTerminal: 00044 - RTB\r\nAmount: $         0.01\r\n",REQ:49}];PVR1.23.1;ROK;

3. Errors

Errors are reported via mnemonics ERC and ERM as usually.

It may happened that API works correctly, but there is some error in parameters or configuration. In such a case the API report error. The error code is sent to PDM in the mnemonic ERV.

3.1. Standard error codes

Table 1. Standard Web API error codes
Error code Meaning

1

Service is disabled in PDM.control

2

Response can not be understand by our system. This is probably implementation error or changed API. Please contact help desk.

3

Web API did not understood request. See mnemonic ERM for details.

4

Web API understood the request but refused to fulfill it. See mnemonic ERM for details.