_ .-') _         _  .-')           ('-.                            .-') _
( (  OO) )       ( \( -O )         ( OO ).-.                       (  OO) )
 \     .'_        ,------.         / . --. /         ,------.      /     '._
 ,`'--..._)       |   /`. '        | \-.  \       ('-| _.---'      |'--...__)
 |  |  \  '       |  /  | |      .-'-'  |  |      (OO|(_\          '--.  .--'
 |  |   ' |       |  |_.' |       \| |_.'  |      /  |  '--.          |  |
 |  |   / :       |  .  '.'        |  .-.  |      \_)|  .--'          |  |
 |  '--'  /       |  |\  \         |  | |  |        \|  |_)           |  |
 `-------'        `--' '--'        `--' `--'         `--'             `--'
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.

Preface

There is for a long time an issue with transporting information about payment, which does not belong to any column of payment log table. Such an information is mostly customers specific and make sense only for few customers. Nevertheless every customers need his specific information. Of course we do not want to add columns for every customer. Even now there is a lot of columns in the table and database already.

The problem has two levels. One of them is, how to transfer from PDM (PDM). The other is how to display them (UI).

Note: The text and examples demonstrate how to use this feature for one specific case, registration of sales in Croatia. nevertheless this feature can be used in lot of other use case, because it uses free form of data (JSON documents).

1. PDM

Transferring data from PDM can be split to several cases.

  1. Custom data are already known when the payment message is send (Direct store).

  2. Custom data are know at later point (Delayed store).

  3. Custom data has changed later after they has been send (Delayed store).

To transfer information between PDM and PDM.control a JSON format is used in the similar way, as we used it before, in hardware_reports.html. PDM can send free form JSON Document, this time in mnemonic CPF (Custom Payment Field).

1.1. Direct store

If the custom information is available in time of sending payment message, it can be send directly with payment message.

...;CPF{JSON data};
E.g. Sale registration in Croatian
CPF{"jir":"382eb8cb-52c1-4682-b729-1bd2c10be0ae","zki":"bfabfea0c38279e0f5e8de98cf0bd77f"};

1.2. Delayed store

If the information is not available at the time of sending payment message, it can be added / updated later. To add or update information for appropriate payment a real time request number abc is used.

Similar as in hardware_reports.html, the JSON carrying update information has key "@meta" carrying service information. The rest is free form JSON document.

1.2.1. @meta key

Meta key contains following sub-keys

Put / update

Operation specifies what to do with this data. It is stored in op key.

Possible values are:

  • put – replace existing database data by this one. Existing complete JSON data in the database will be deleted first and the the provided data will be inserted. Default value if nothing is provided. See example Put data.

  • add – add this data to previous ones stored in the database (merge). If the key already exists in the database then its properties will be overwritten by provided value. See example Add data.

Operation add can be also used if data is longer than 1kB (or some other HW limit) and needs to be split to multiple messages.

Delete data

Path which should be deleted from JSON data are specified in @meta.del key.

  • del – Specified keys will be deleted. It is expected an array of first level paths to delete. Deletion of nested levels is not supported. See example Add and delete data.

Delete operation is always executed after put or add. It means that if there simultaneous request to add and delete data the data will be deleted.

Payment identification

In order to identify payment which’s payment field will be modified it is also necessary to provide its identification. Folowing information is required.

  • Timestamp (ts)- date and time of original payment, as it was sent from PDM during payment.

  • Ticket - (tic) ticket number as it was sent during initial message.

1.2.2. Examples

Example of delayed registration with Croatian tax office. This is just an example. The implementation of real process is up to PDM designers. They can decide to use this JSON document field differently.

Assume that the connection to tax office does not work and PDM has sent payment without custom field initially. Then PDM delivers ZIK later for whatever reason.

After payment message, PDM indicates that payment is not registered, by separated request.

Put data
{
  "@meta":{
    "op":"put",
    "ts":"2020-10-12T13:36",
    "tic":3478
  },
  "reg":"no",
}

Then PDM generates ZKI and update data in PDM.control.

Add data
{
  "@meta":{
    "op":"put",
    "ts":"2020-10-12T13:36",
    "tic":3478
  },
  "zki":"b32e537f69c72fd57d3993430bf04401",
  "reg":"offline",
  "reason":"Tax office error. Registration will be finished later."
}

After a while, the registration was successful, JIR is updated. PDM wants to delete reason key. The reason of failure is not needed any more Therefore PDM specified its path in array under @meta.del key. Filed zki stays unchanged because an add operation has been used.

Add and delete data
{
  "@meta":{
    "op":"add",
    "del":["reason"],
    "ts":"2020-10-12T13:36",
    "tic":3478
  },
  "jir":"382eb8cb-52c1-4682-b729-1bd2c10be0ae",
  "reg":"online"
}

2. UI

There will be one extra column in Payment report table. It will be called ‘Custom data’ and users who need it, can display it, by the same action as the other columns.

Generally it will look like this.

Table 1. Payment table
PDM Area Custom data

1

5

{"jir":"382eb8cb-52c1-4682-b729-1bd2c10be0ae","zki":"b32e537f69c72fd57d3993430bf04401", "reg":"online"}

It may happen that there is too much data in the column and customer is interested only for part of them. Let say jir and registration status. In this case he can enter list of paths which are interesting for him in UI filter field (not ready yet). The payment table will show only specified parts of JSON.

Filter: reg,jir.

Now the report will look like this. Filed zki is fitered out.

Table 2. Payment table
PDM Area Custom data

1

5

{"jir":"382eb8cb-52c1-4682-b729-1bd2c10be0ae", "reg":"online"}