Value Master

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

The document describes how the integration between PDM and Value Master is done. The process involves also PDM.control as a service provider.

1.1. PDM

Handling of value master requests has been made via real time request framework developed earlier (Real time multi request). There are two requests to get card balance and to use amount of money.

1.2. Monetary units

All monetary values received or send to Value Master can be of two types. Standard currencies (E.g. EUR or CZK) or points. Currently only standard currencies are returned. Points throw exceptions and not passed to PDM as a valid response.

Unfortunately, Brain Behind do not know how how to handle points. They return integer as a string value and it is not known how to decode it. They do not know if points have decimal places and how may. Maybe the number of decimal places even vary. Chief evangelist assured me, that only real currencies will be used for Villach. In every case I will reserve currency XPT (PoinT) for future use. Yes I know that XPT is platinum currency but I do not expect that somebody can pay by platinum on our machine.

2. Integration 1

2.1. Card balance

To find out balance of the card it is necessary to provide the card number (KKN) and PDM identification (PSA, GAC). It seems, that the amount of money on the card account somehow depends on, by which PDM they will be used. Unfortunately, even chief evangelist from Brain Behind was not able to explain me why it is so or provide an example how it is used in real projects.

2.1.1. Request

Card balance can be retested by REQ22 together with KNN, PSA, GAC and DPA to indicate PDM scale.

Example 1. Card balance request

PSA12;GAC11;MRQ[{REQ:22,KNN:"A66C6D51"}];DPA2;

2.1.2. Successful response

PDM.control responds with list of accounts available on this cards. According to the promises of the chief evangelist, there will be always just one account element in the list. Unfortunately he did not know why they return array when there is always just one element. To also cover the case, that chief evangelist was wrong, PDM.control also returns list. For Villach just use first element. For other projects we will see.

Example 2. Return value is following JSON:

{pin:false,acc:[{cfg:[2,3],bet:10000,wkz:"EUR"},{...}]}

Element cfg tells what can be done with account. Possible values are listed in the table below.

Table 1. Accounts purposes
Code	Meaning
1	Add Purchase (Collect Bonus)
2	Payment from account (Redeem voucher)
3	Add additional value to voucher (Buy voucher)

Element bet is amount of money on the card multiplied by 10 ^DPA.
Element wkz: currency of the account.
Element pin indicate whether PIN is required for payment operations.

Example 3. Answer for 100€ may be

 ... PSA12;GAC8;MRQ[{DPA:2,BAL:{pin:false,acc:[{cfg:[2,3],bet:10000,wkz:"EUR"}]},REQ:22}];..

See also chapter Error codes for error handling.

Be aware of fact that in case of invalid (non existing) card number, reports Brain Behind no error. The card is presented as valid with value 0.

2.2. Payment / re-charging

2.2.1. Request

To successfully register payment it is necessary to provide flowing arguments:

PSA – PDM number.
GAC – area code.
KNN – card number.
BET – amount to use. Positive value decreases account value (buy), negative increases (recharge). New account value is therefore V_new = V_old-BET^-DPA.
DPA – decimal shift.
PIN – card pin (if required)
PTS – use points instead of amount of money. PTS0 (default) = currency, PTS1 points.

Please note two very strange things:

Currency cannot be specified and verified by Brain Behind API. Even if it is provided from PDM is will be ignored. Therefore is up to the configuration provider that PDM and Brain Behind are configured to the same currency.
It cannot be specified which account form the provided by function in chapter Request. It seems that this function works in some default well known account.

Example 4. Paying 3.2€ without PIN.

PSA3;GAC11;BET320;WKZEUR;DPA2;MRQ[{REQ:23,KNN:"A66C6D51"}];

Example 5. Paying 3.2€ with PIN

PSA3;GAC11;BET320;WKZEUR;DPA2;MRQ[{REQ:23,KNN:"A66C6D51",PIN:"123"}];

Example 6. Recharging 7€ without PIN

PSA3;GAC11;BET-700;WKZEUR;DPA2;MRQ[{REQ:23,KNN:"A66C6D51"}];

2.2.2. Response

Flowing information are part of responses

display - Message to be shown on terminal display
print - Message to be printed on receipt
id - Unique transaction ID. It is expected to be used for payment tracing.

Therefore sample response may be:

Example 7. Discharging (credit decrease)

...;PSA3;GAC11;MRQ[{PAY:{id:"651a9565-0f45-4f68-b782-50120eb3bb6f",display:"Vielen Dank! EUR -7,12 bezahlt. Guthaben: EUR 104",print:"Vielen Dank! EUR -7,12 bezahlt. Guthaben: EUR 104"},REQ:23}];...

Example 8. Charging (credit increase)

...;PSA3;GAC11;MRQ[{PAY:{id:"09329d4e-00a0-4365-8e76-b1aa92ef95f3",display:"Vielen Dank! EUR 10 aufgebucht. Guthaben: EUR 115",print:"Vielen Dank! EUR 10 aufgebucht. Guthaben: EUR 115"},REQ:23}];...'

2.3. Error codes

Error is indicated by ERC (ERror Code) and ERM (ERror Message). If field ECR is present with non 0 value, error has happened. Field ECD is optional. It may provide textual description if available.

Example 9. Wrong authentication:

  ...;PSA00003;GAC11;MRQ[{ERM:"Wrong Authentication",ERC:3,REQ:23}];...

Following error codes are now supported.

Table 2. 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.

3. Configuration

Brain behind requires also to put some configuration to PDM.control. Each Area can have different configuration. Go to PDM.control and open appropriate Area. Switch to Services Brain Behind. Fill out the form according to instruction from Brain Behind.

3.1. Terminal identification

It is somehow necessary to register terminal (PDMs) names, which will be used together with Brain Behind. This implementations expects that the terminal name is format pdmNumber@areaNumber. E.g. 1@7 or 48515@57. Do not pre-pend leading zeroes (like 00078@000001).

3.2. Time zone

As I was informed by Brain Behind, each project in their system is created in some particular time zone. In this time zone are provided all the time stamps via their API without further information which time zone it is. Unfortunately it not possible to read this time zone programmatically. Therefore user has to configure, in which time zone the project in Brain Behind was created.

3.3. Web service encryption

Please note that now only AES encryption method is supported. Specification for the others was not provided by Brain Behind. Please ask Brain Behind to set encryption as AES and do not change it.

Brain behind requires to choose encryption method of web service to one of following values:

Triple DES
AES
Rijndael

on their web interface.

As it was told by Alfred Dworschak <alfred.dworschak@brainbehind.com> the setting in web UI has no effect and clicking on button Save changes will do nothing. The encryption is set once by creating of the project and cannot be changed (although UI confirms that changes were saved and UI shows new values). Unfortunately there is even no possibility to read encryption settings programmatically via API. Therefore user has to set manually which encryption is set by Brain Behind.

4. Integration 2 (2022-04-25)

There is new UI part called 'Integration 2' in UI. User needs to provide a new password because it is not clear if one of the existing passwords from integration 1 correlates with this one. Also it is not know in 'Service ID' and 'Integrator ID' is constant or customer dependant. Therefor there are entries for them in UI. If it will be find out how configuration by Brain Behind works, some or all of those new fields may be removed.

Brain behind also requests a terminal id. It is generated from PDM number and area in form pdm@area. Please register PDMs by Brain Behind in this from.

4.1. QR code

Validate QR code by Brain Behind.

To validate QR code provide its number in parameter KNN inside request 31.

Example 10. Validate QR

PSA3;GAC11;MRQ[{REQ:31,KNN:"808807516872365"}];

Response is contained in standard form for multi-request. Next examples contains only JSON part

Response

{
  "qrc":{
    "statusCode":0,
    "statusText":"OK",
    "display":"Text to display",
    "print":"Text to print",
    "program":"My program"
  }
}

Values display, print, program may be null as they are not always provided by Brain Behind. In such a case is will be skipped in the answer.

Minimal response may therefore look like this.

{"qrc":{"statusCode":0,"statusText":"OK"}}

Error are reported in mnemonics ERC and ERM. See Appendix A for error codes description.

5. Appendix A

Status codes are copied from Value Master documentation v 7.10.

Table 3. Status codes
StatusCode	Category	StatusText
0	Generic	OK
1	Generic	Undefined Error
100	ID	Error
101	ID	Unknown identifier
102	ID	IntegratorID invalid
103	ID	IntegratorID missing
104	ID	CompanyID invalid
200	Authentication	Error
201	Authentication	Failed
202	Authentication	Insufficient permissions
203	Authentication	Soap header null or empty
204	Authentication	Integrator password not found in soap header
300	HttpContext	Description or system id could could not be set
301	HttpContext	ContentType in header is null or empty
302	HttpContext	Content type must be json
303	HttpContext	Authentication header null or empty
304	HttpContext	Integrator password missing in HTTP header
305	HttpContext	JWT missing in HTTP header (Authentication: Bearer)
306	HttpContext	Invalid JWT
400	Parameters	Error
401	Parameters	Use case value not supported
402	Parameters	Terminal group type X not supported
403	Parameters	Invalid terminal group
404	Parameters	Request object can not be null
405	Parameters	Invalid technology indicator
406	Parameters	Invalid transaction type
407	Parameters	Transaction type ignored
500	Validation	Error
501	Validation	JWT error
502	Validation	Secret key null or empty
503	Validation	PIN invalid
504	Validation	PIN must be alphanumerical
505	Validation	Balance on card has expired
600	SQL	Error
601	SQL	Transaction failed
602	SQL	Transaction with that id already processed or missing
700	Data	Error
701	Data	Insufficient funds
702	Data	No balance found for card
703	Data	No bonus for transaction
800	Configuration	Error
801	Configuration	Terminal group not chargeable
802	Configuration	No terminals active with that id
803	Configuration	Too many active terminals with that id
804	Configuration	Could not find program
805	Configuration	Invalid terminal id X
806	Configuration	Invalid terminal group X
807	Configuration	Invalid card id X
808	Configuration	System id X not configured as additional key
809	Configuration	Insufficient permissions
810	Configuration	Processor not implemented
811	Configuration	No terminal group with systemId X and terminalId Y
812	Configuration	Terminal X not in terminal group Y
813	Configuration	Terminal is not in consumer group
814	Configuration	Terminal is not in producer group
815	Configuration	Terminal is not allowed to collect bonus
816	Configuration	System not configured for transaction confirmation
817	Configuration	No permissions configured for integratorId X, systemId Y and companyId Z
900	External	Error
901	External	Error calling six web service
1000	Process	Error
1001	Process	Request is already being processed