Web Content Display

OPX Analytics

Open Payment Application Exchange (OPX) Analytics is a powerful application for measuring and analyzing payment-related KPIs of your business.

By fully integrating your payment processes with the OPG you will have access to a complete business intelligence data profile right at your fingertips -- across all of your providers and broken down into more than 40 KPIs and 9 filtering dimensions. A clean API allows you to control the output from simple to complex, just as your business requires.

Discover the structure of the KPIs and the API here.

Web Content Display

KPIs

A KPI is a key performance indicator that measures important aspects of a business. OPX Analytics provides more than 40 KPIs about your customer checkout, divided into the Transactions Section and the Conversion Section, straight out of the box (login required). In contrast to the Report API, OPX Analytics does not reflect individual transaction data to track specific events, but was designed for statistical analysis on a higher level.

A KPI is identified by a 3-character code (e.g., GSL for Gross Sales) and typically measures in one or more of these units:

a currency (e.g., EUR), typically transaction volume
a count (#), typically number of transactions
a percentage (%), typically conversion or bounce rate

Technically, a KPI sums up the number and volume of status transitions of payment transactions and similar events into a certain status within a given period of time.

For example, the KPI Chargebacks CHB could have a count value of 12 and an amount of EUR 359.88. This would mean that there were 12 payment transactions that changed their status to charged_back, thereby reversing payment amounts of EUR 359.88 within the given time period.

Note: a number of status transitions in a given time period in the past will not change in the future. For example, if on one day you had 100 transactions going into the state charged, being counted in the Successful Charges KPI SCG, and 10 of them will be refunded a week later (going into the status paid_out), still there will have been 100 Successful Charges on that day. So the number will never change, no matter when you query it in the future. This is because OPX Analytics is focused on state transitions, and not like the Report API on the transactions themselves, which could change their status over time.

A KPI can also be composed of sub-KPIs. For example Gross Cashflow GCF is Successful Charges SCG minus Reversals RVS. Components of Reversals RVS again are Chargebacks CHB, Payouts PYO, etc. We say that the sub-KPIs of composed KPIs are their components (aka children).

In OPX Analytics KPIs are grouped into Sections (and there they have the same General Dimensions for filtering in common). Out of the box there are two:

Transactions section example KPIs:

KPI Name	Code	Description
Gross Sales	`GSL`	Received payments and receivable payments that still have to be made by your customers, for which you have a legal claim.
Net Sales	`NSL`	Gross Sales `GSL` minus all Reversals `RVS` and not received payments.
Gross Cashflow	`GCF`	All completed Successful Charges `SCG` minus Reversals `RVS`.
Chargebacks	`CHB`	Amount of chargebacks triggered by the customers.
Credits	`CRD`	Amount of credit transactions transferring funds from the merchant to customers.
Refunds	`RFD`	The number and volume of all (partial and full) refunds of successful previous payments.
Payouts	`PYO`	Voluntary, merchant-initiated money transfer (back) to the customers; i.e., Credits `CRD` + Refunds `RFD`.
Reversals	`RVS`	All money transfers back to the customer, volunatrily or otherwise; i.e., Payouts `PYO` + Chargebacks `CHB` - Recovered Chargebacks `RCB`.

Here is the full list of Transaction KPIs. Please note that you have to be signed in to access the page.

Conversion section example KPIs:

KPI Name	Code	Description
Payment Successes	`PSC`	Amount of payment sessions that resulted in a successful payment on the first, or a subsequent attempt.
Total Finalized Payment Sessions	`TFS`	Total amount of payment sessions that were initialized and finalized (can not change their status anymore), regardless of whether there was a successful payment, only denied payment attempt(s), or it expired, because no action was taken.
Gross Conversion	`GCO`	The number of Payment Successes `PCS` divided by the number of Total Finalized Payment Sessions `TFS`, given in percent.

Here is the full list of Conversion KPIs. Please note that you have to be signed in to access the page.

Web Content Display

Transactions KPIs

Transaction KPIs are based on counting the status transitions of CHARGE and PAYOUT transactions within a given time frame. This way you get absolute numbers about Successful Charges SCG, Unsuccessful Charge Attempts UCG, Chargebacks CHB, etc..

Aggregations and changes of some of those values are also calculated to provide helpful extra information in the form of composed KPIs; for example, the Gross Cashflow GCF, which is all Successful Charges SCG minus all Reversals RVS.

The following diagram illustrates the overall structure of Transaction KPIs. Typically, status transitions of payment transactions occur from left to right.

Opened Charges

Opened Charges OCG (on the left) represents payments that were not yet executed in terms of cashflow, but for which the merchant has a legal claim. Therefore, they contribute to the sales figures in an accounting sense. There are many reasons why a payment may still be "open", they are reflected in four of the children of the OCG KPIs, which are not shown in the diagrams:

Open Demanded Charges ODD: Unreceived payment that depends on final confirmation of the customer outside of the checkout process; e.g., pre-payment.
Opened deferred Charges ODF: Preauthorized payments, that will be closed (captured) by the merchant; e.g., on delivery.
Opened redirect Charges ORD: Payments using a redirect method (e.g., PayPal) that have already been initialized but are still waiting for final confirmation from the customer on the site of that method.
Opened retry scheduled Charges ORY: All payments that were scheduled for a later retry; e.g., recurring charges that triggered ADM.

Consequently, these differentiations can also be made in the status categories wherein the contained transactions can evolve into; namely, Successfully Closed Charges SOC or Unsuccessful Previously Opened Charges UOC. Their codes can be found in the list below.

Note: The sum of Successfully Closed Charges SOC and Unsuccessful Previously Opened Charges UOC is not typically equal to the total Opened Charges OCG. Any transaction counted in OCG will eventually land in either the SOC or UOC category; however, all KPIs only count the number of respective events in the given time period. Therefore, a counted successfully closed Charge does not neccessarily correspond to a counted opened Charge in the same time period. They can be completely independent.

Tree View

The entire KPI structure can also be represented as two trees, rooted in the Net Sales NSL and Gross Cashflow GCF KPIs respectively, and show their composition throughout further child levels. This is essentially how the KPIs are represented in the API. Both trees have the Reversals RVS KPI in common at one point, shown below.

The Net Sales NSL tree:

The Gross Cashflow GCF tree:

Lastly, the detailed structure of Reversals RVS, including details about Payouts PYO, that appear in both of the high-level trees:

Alphabetical List of all Transaction KPIs

KPI Name	Code	KPI Components	Description
Charge Cancellations	`CCL`		Charges that were cancelled before they were executed by the provider.
Chargebacks	`CHB`		Amount of chargebacks triggered by the customers.
Credits	`CRD`		Amount of credit transactions explicitly transferring funds from the merchant to customers.
GrossCashflow	`GCF`	Successful total Charges (`SCG`) - Reversals (`RVS`)	All successful Charges (incoming money) minus all reversals (outgoing money).
Gross Sales	`GSL`	Successful Immediate Charges (`SIC`) + Opened Charges (`OCG`)	All sales that were made legally, but not neccessarily caused cashflow yet (e.g., due to Deferred Charges that still need Closing).
Net Sales	`NSL`	Gross Sales (`GSL`) - Reversals (`RVS`) - Unsuccessful previously opened Charges (`UOC`)	Similar to Gross Sales (`GSL`), but deducting all cases where customers reverted their previously successful payments later or an opened (e.g., deferred) Charge which was unsuccessful when closed.
Opened Charges	`OCG`	Opened deferred Charges (`ODF`) + Open demanded Charges (`ODD`) + Opened retry scheduled Charges (`ORY`) + Opened redirect Charges (`ORD`)	All payments where the customer showed a clear intent to pay, and could therefore be counted as a successful sale, but the funds still need to be transferred by final confirmation from the customer or the merchant. Pending Charges are not counted here, because they only depend on the response of the payment provider.
Open demanded Charges	`ODD`		Unreceived payment that depends on final confirmation from the customer outside of the checkout process; e.g., pre-payment.
Opened deferred Charges	`ODF`		Preauthorized payments, that have not yet been closed (captured) by the merchant.
Opened redirect Charges	`ORD`		Payments using a redirect method (e.g., PayPal) that have already been initialized but are still waiting for final confirmation from the customer on the site of the external method.
Opened retry scheduled Charges	`ORY`		All payments that were scheduled for a later retry; e.g., recurring charges that triggered ADM.
Payouts	`PYO`	Refunds (`RFD`) + Credits (`CRD`) + Charge Cancelations (`CCL`)	The amount of funds that were actively paid to customers by the merchant due to various reasons.
Recovered Chargebacks	`RCB`		Chargebacks that can be recovered by the merchant.
Refunds	`RFD`		The number and volume of all (partial and complete) refunds of successful previous payments.
Reversals	`RVS`	Payouts (`PYO`) + Chargebacks (`CHB`) - Recovered Chargebacks (`RCB`)	The total number of cases where funds were transferred back to customers for various reasons (with or without merchant involvement), respecting potential recoveries of chargebacks.
Reversals Frontend	`RVF` (artificial)		All Reversals (`RVS`) that refer to frontend charges (active customer checkout), as opposed to backend (recurring) charges. Necessary for calculation of Net Conversion.
Successful Charges	`SCG`	Successfully closed (previously open) Charges (`SOC`) + Successful Immediate Charges (`SIC`)	Amount of all successful Charges (immediate, deferred, or successfully closed due to other reasons) with transfer of funds.
Successfully received demanded payment	`SDD`		Amount of payments that were received due to a "demanded" customer flow, meaning the customer actively transferred the funds to the merchant using an external channel (e.g., pre-payment via bank transfer)
Successfully closed deferred Charges	`SDF`		Amount of deferred Charges that were successfully closed; i.e., the funds captured.
Successful immediate charges	`SIC`		All (non-deferred or otherwise previously opened) Charges that were successful.
Successfully closed (previously opened) Charges	`SOC`	Successfully closed deferred Charges (`SDF`) + Successfully received demanded payment (`SDD`) + Successfully retried Charges (`SRY`) + SRD	Amount of all kinds of previously open charges (`OCG`) that resulted in a successful transfer of funds.
Successfully closed redirect Charges	`SRD`		Payments using a redirect method (e.g., PayPal) that have been successfully finalized by customers.
Successfully retried Charges	`SRY`		All payments that were successful in a scheduled later retry; e.g., recurring charges that triggered ADM.
Unsuccessful Charges	`UCG`		All (non-deferred or otherwise opened) charge attempts that were denied due to various reasons.
Unsuccessful demanded payment	`UDD`		All unsuccessful, because timed-out payment demands; e.g., never received pre-payment via bank transfer.
Unsuccessful deferred Charges	`UDF`		All deferred charges where the closing was unsuccessful.
Unsuccessful previously opened Charges	`UOC`	Unsuccessful deferred Charges (`UDF`) + Unsuccessful demanded payment (`UDD`) + Unsuccessfully retried Charges (`URY`) + Unsuccessful redirect Charges (URD)	Amount of all previously open charges (`OCG`) that resulted in a denial.
Unsuccessful redirect Charges	`URD`		Payments using a redirect method (e.g., PayPal) that were cancelled or never completed by customers.
Unsuccessfully retried Charges	`URY`		All payments that were subject to and already went through all scheduled later retries; e.g., recurring charges that triggered ADM, with none of them being successful.

Transactions KPIs

Please sign in to view further details of this article. Login

Web Content Display

Conversion KPIs

A complete and correct integration of OPG allows tracking of customer conversion on the payment page. This is possible due to optile's unique checkout architecture with LIST and CHARGE Requests that also allows the dynamic payment page. Conversion tracking basically puts the total number of generated payment sessions in relation to the number of successful CHARGEs or PAYOUTs.

The diagram below shows the structure of conversion KPIs:

For example, Gross Conversion GCO is the number of Payment Successes PSC divided by the number of Total Finalized Payment Sessions TFS. So a value of 20% would indicate that from 100 payment sessions 20 resulted in a successful payment.

Interaction Conversion ICO is similar but also takes into account the payment attempts that were denied; i.e., it measures how many times the user attempted to make a payment.

Net Conversion NCO deducts all Reversals Frontend RVF; i.e., all Refunds and Chargebacks that refer to a frontend checkout charge (as opposed to a backend Recurring Charge).

Payment Session Outcome

During a payment session (i.e., using one LIST object) there can be multiple payment attempts (e.g., CHARGE Requests) with various outcomes. Therefore the conversion KPIs are measured by only examining the payment sessions that were finalized during the Selected Time Period. Finalized means that their outcome can no longer change, due to one of these reasons:

There was a successful payment within a session (counted in Payment Successes PSC). A session only allows one successful payment.
- It could either be successful on the first attempt (Succeeded Payment Sessions SPS), or
- It was successful after an initial denial at a later attempt (Recovered Declined Sessions RDS).
There were so many denied payment attempts, that no further attempts are possible (this happens only rarely, and counts towards Denied Payment Sessions DPS).
The session expired without a successful payment.
- If the user did not try to pay, meaning there was no payment attempt at all, this counts towards the Aborted Payment Sessions APS.
- If the customer gave up after one (or more) denied attempts that is counted towards the Denied Payment Sessions DPS.
The LIST did not contain any payment methods (typically because there were no providers or methods configured for the requested country or currency). That would be reflected in the Invalid Payment Sessions IPS.

Because only finalized payment sessions are counted, the result of a conversion KPI query will always return the same result (for a time period in the past), also if repeated in the future.

Alphabetical List of all Conversion KPIs

KPI Name	Code	KPI Components	Description
Aborted Payment Sessions	`APS`	Base KPI	Sessions expired without payment attempt. Includes redirection to external pages such as PayPal and explicit customer cancellations at the external site.
Denied Payment Sessions	`DPS`	Base KPI	Payment sessions that contain at least one denied payment attempt, and no successful payment thereafter.
Gross Conversion	`GCO`	Payment Successes (`PSC`) / Total Finalized Payment Sessions (`TFS`)	Ratio between successful and all finalized payment sessions.
Interaction Conversion	`ICO`	Payment Attempts (`PAT`) / Total Finalized Payment Sessions (`TFS`)	Ratio between sessions with actual payment attempts (customer "interaction", which may be a successful or declined payment) and all finalized payment sessions.
Invalid Payment Sessions	`IPS`	Base KPI	Payment sessions that could not be properly initialized, leaving no payment possibilities for the customer. This can indicate a lack of configured payment providers or methods, or a bad LIST Request; e.g., wrong country or currency.
Net Conversion	`NCO`	Non-reversed Frontend Successes (`NRS`) / Total Finalized Payment Sessions (`TFS`)	Similar to Gross Conversion (`GCO`), but deducting the cases where customers reverted a previously successful payment at a later point in time; e.g., due to refunds.
Non-reversed Frontend Successes	`NRS`	Payment Successes (`PSC`) - Reversals Frontend (`RVF`)	The amount of all payment sessions that resulted in a successful charge minus all reversals that refer to a frontend payment. Note that there is no logic to examine if the Reversals actually belong to the included successful payments. Only the number of events that occured in the given time period are counted.
Payment Attempts	`PAT`	Payment Successes (`PSC`) + Denied Payment Sessions (`DPS`)	All payment sessions where a customer submitted a payment request (interacted), likely with the intention to pay, successful or not.
Payment Successes	`PSC`	Succeeded Payment Sessions (`SPS`) + Recovered Declined Sessions (`RDS`) + Recovered Abandoned Sessions (`RAS`)	All payment sessions that in the end resulted in a successful charge.
Payment Unsuccessful	`PUC`	Declined Payment Sessions (`DPS`) + Invalid Payment Sessions (`IPS`) + Aborted Payment Sessions (`APS`)	All payment sessions that were initialized but did not result in a successful payment.
Recovered Abandoned Sessions	`RAS`	Base KPI	Payment sessions that resulted in a successful charge, and seem to be linked to a previously abandoned payment session (e.g., due to a customer not proceeding with the checkout and then returning next day). Detection not yet implemented.
Recovered Declined Sessions	`RDS`	Base KPI	Payment sessions that resulted in a successful charge after there was at least one denied payment attempt.
Reversals Frontend	`RVF`	Base KPI	The number of Reversals (Refunds or Chargebacks) that refer to a previous frontend charge (as opposed to a backend recurring charge). This is the only KPI in this section that does not refer to the outcome of a payment session, but transactions directly, because Refunds and Chargebacks are not part of a frontend checkout.
Session Bounce Rate	`SBR`	Payment Unsuccessful (`PUC`) / Payment Successes (`PSC`)	Ratio between payment sessions that did not result in a successful payment and all initialized (and finalized) payment sessions.
Succeeded Payment Sessions	`SPS`	Base KPI	Amount of payment sessions that resulted in a successful payment on the first attempt.
Total Finalized Payment Sessions	`TFS`	Payment Unsuccessful (`PUC`) + Payment Successes (`PSC`)	All payment sessions that have a final outcome which can no longer change; e.g., due to a successful charge, or session expiration without payment.

Conversion KPIs

Please sign in to view further details of this article. Login

Web Content Display

Filtering

A KPI value is the sum of transactions of a certain type within a specific period of time; e.g., the number or volume of Chargebacks. In addition to their type and the time when they occurred, OPG transactions also have a number of additional properties which can be used for filtering. For example, all payment transactions have a currency. If one or more currencies are applied as a filter, only those transactions which were processed in one of those currencies will be counted. As a result the KPI value can change and deliver more specific data in terms of Business Intelligence (BI).

The properties that can be used for filtering; e.g., currency, are called dimensions. The possible values that can occur in one dimension are the children of that dimension. They basically represent data points along the dimension axis.

Data Cube and Slicing

Since there is often more than one dimension available, a cube is often used to visualize the filtering process. For example, the cube (presented below) could represent all payment transactions of a merchant over the past four years with all six of its payment methods in all seven of its countries:

Applying a filter to count only those transactions which happened in France (FR), conceptually, means to take a slice out of the cube, as illustrated below in red:

By applying more than one filter, the result set (and therefore the KPI value) will be reduced further. In the following example, only payment transactions made in France (FR), with VISA in 2016 are considered:

This 3D example is chosen, because it can be easily and clearly illustrated. In reality there will be more than 3 dimensions.

General Dimensions

There are different KPIs, which aggregate different types of transactions that use different filtering dimensions. KPIs that belong to a certain "section" usually have a common set of dimensions. These are called General Dimensions, and they are the same for all KPIs in a section; e.g., the Transactions Section. The General Dimensions will, therefore be returned on a section level in the corresponding API calls.

There are the four General Dimensions that currently apply to all Sections of OPX Analytics KPIs:

It should be noted that the API response of available dimensions should be respected. Also, the code of each dimension and the code of all its available children will be returned. With those values, the actual filtering in a subsequent query can be applied, e.g., with currency=EUR.

Below are the codes for the dimensions and their children, which you can use to help you implement a "static" client to read out a fixed set of KPIs.

Dimension Label	Dimension Code	Child Codes	Child Code Examples
Region	`region`	ISO 3166-1 alpha-2 country codes	`DE`, `FR`, `US`
Currency	`currency`	ISO 4217 currency codes	`EUR`, `GBP`, `USD`
Payment Provider	`provider`	OPG provider codes	`WIRECARD`, `PAYPAL`
Payment Methods	`network`	OPG network codes	`VISA`, `SEPADD`

The time dimension is not included here. Since it does not have a discrete value space with separate and directly identifiable children, but time is naturally an axis with continuous values. The time dimension is handled a little differently in the API. There is extensive documentation available under Time Handling.

Specific Dimensions

In addition to the General Dimensions, some KPIs provide additional filtering possibilities.These are referred to as Specific Dimensions. The specific dimensions are returned in the API individually per KPI. The table belwo describes the current possibilities of the Specific Dimensions currently in place. Note: The specific dimensions can only be applied to some KPIs, as indicated in the corresponding API responses.

Dimension Name	Dimension Code	Child Codes	Meaning	Definition
Trigger	`trigger`	`N`	Frontend, using a new Network	The charge has been triggered from the frontend with customer interaction, using a new payment method (network). The end-customer can either be registered and using a new payment method (e.g., registered VISA Card and choosing to pay with PAYPAL) or a non-registered user using any network.
		`A`	Frontend, using a registered Account	The Charge has been triggered from the frontend with customer interaction using a registered account.
		`R`	Backend, using a recurring Account	The Charge has been triggered from the backend, without customer interaction, using a registered recurring account.
Deferral Flow	`deferral`	`D`	Deferred	The payment was done in deferred mode.
		`N`	Not deferred	The payment was not done in deferred mode.
Refers to Charge from...	`reference`	`F`	Frontend	Note: This dimension applies only to Payouts (Refunds, Credits) and Chargebacks. Means the transaction refers to a previous frontend payment (as opposed to a recurring charge from the backend).
		`B`	Backend	The transaction refers to a recurring charge (as opposed to a frontend payment with customer interaction).
		`N`	None	Transaction does not refer to any previous transaction (would be the case for most credits, and conceptually of course all normal payments)
Unsuccessful Reasons	`reason`	`F`	Failed	Corresponds to the `failed` Status Code.
		`D`	Declined	Corresponds to the `declined` Status Code.
		`R`	Rejected	Corresponds to the `rejected` Status Code.
		`A`	Aborted by Customer	Corresponds to the `aborted` Status Code.
		`C`	Canceled by Merchant	Corresponds to the `canceled` Status Code.

Web Content Display

Time Handling

optile's OPX Analytics provides a simple and powerful tool for you to creat meaningful charts and to present your required response data, with your specified time periods.

Selected Period

A KPI value always refers to a time period, the Selected Period. It is given in the query request by specifying these values:

Period end: A timestamp with the attribute name periodEnd. It is actually the first moment outside of the time period; i.e., it is no longer part of the Selected Period. If no period end is specified, OPX will assume it is now (more implications on this below).
Period length: This is defined by two attributes:
- sliceUnit: The unit of the time slice; e.g., hour, day, week, month.
- sliceUnitCount: The number of units that make up the actual time slice.

Typically, your Selected Period will be a time slice with a length of one day, or one week, etc. However, you can also specify 12 hours, or two weeks, for example.

If no periodEnd is given, OPX assumes that the client wants data about the immediate past, e.g., the last 24 hours or the last week, as specified by the period length. This is referred to as a Rolling Period. No rounding takes place, so requesting one day back at 10:51 from today will return the KPI value aggregation between 10:51 yesterday (inclusive) and 10:51 today (exclusive). Also the natural equivalencies always apply; i.e.,: 24 hours = 1 day, 1 week = 7 days, 1 quarter = 3 months, 1 year = 12 months.

If an explicit periodEnd in the past is specified, we call it a Calendar Period. In the typical case there will be sliceUnitCount = 1. OPX then assumes the client wants to see a natural calendar unit; e.g., one day from midnight to midnight. Therefore, it will round the requested periodEnd to the natural end of the sliceUnit in the calendar to form the Selected Period (midnight in that example).

If, however, sliceUnitCount is greater than 1 (e.g., for 12 hours) there will be no rounding. So 12 hours back from 16:23 will aggregate the KPI value from 4:23 on.

If the periodEnd is in the future the query will return the value as accumulated until now, possibly 0.

Time Period: Drill-Up and Drill-Down

For data analysis, it is often useful to compare a KPI value from the Selected Period with values from different time periods. OPX offers drill-up or drill-down functionalities in relation to the selected period. For instance, assume that the selected period is one day. The OPX can provide KPI values for the entire week that contains this day, a drill-up operation, or provide KPI values of 24 hours that are contained within this day (i.e., drill-down). You can think of this as zooming-in or zooming-out from a digital image. Depending on the resolution of the data you are interested in, the OPX will either give you a finer or coarser view of the data.

Drill-Up Period

This period is used to set the selected period into context of preceding and subsequent time slices. Those time slices will all have the same length and together make up the Drill-Up Period. The selected period is one of those slices within the Drill-Up Period.

Returning data about the Drill-Up Period can be requested in the call for KPI details. The extent is always calculated by OPX, not defined by the client. OPX will take the given selected period and move up by one or two calendar units. For example, OPX will show a selected day in context of the other days of the week, in order to display a clear and concise graph. See details below.

The extent of the calculated Drill-Up Period will be returned by giving a periodEnd again and the sliceCount, which represents the number of time slices within the Drill-Up Period. Do not confuse this with the sliceUnitCount, which is a factor in specifying the length of each of those slices.

In addition to the KPI value of each time slice in the Drill-Up Period, the detail query will also return the maximum value maxValue, minimum value minValue, and average value avgValue of time slices in this Drill-Up Period. This will allow the user to immediately understand how the performance of the selected period compares to other periods.

Visualization of Drill-Up Period

Looking at a selected period, a user should not only be able to navigate to the time period before or after the selected period, but also make a larger jump by shifting the Drill-Up Period to the next or previous period. However, since the client cannot explicitly specify the Drill-Up Period, the response helps by returning the attributes previousSelectedPeriod and nextSelectedPeriod. They represent the selected period that could be used in a subsequent request in order to shift the whole Drill-Up Period back or forth.

Determining the Drill-Up Period from the Selected Period

The Drill-Up Period will always try to represent the selected period in a larger and more meaningful context, keeping the number of data points (time slices) balanced between too little information and an information overload. As a result the client needs very little logic, it should "just" visualize the data to that extent as it is returned.

For Rolling Periods (ending now), OPX will calculate the KPI value by aggragating the data from the given period in the past (constituting the selected period); e.g., the last 24 hours (without any rounding). The corresponsing Drill-Up Period will consist of this selected period plus seven more time slices of equal length in the past.

For Calendar Periods representing typical units (e.g., a day) with sliceUnitCount = 1 OPX will present the selected period in the context of a calendar unit one or two levels higher (e.g., the selected day between the other days of a natural week), again trying to find a balance between too little and too many data points.

Specifically it will use this mapping:

Selected Period Length	Example periodEnd	Resulting Selected Period	Drill-Up Period Unit	Example Drill-Up Period
1 Hour	10:00	09:00 - 10:00 (exclusive)	Day	24 slices between 00:00 this day and 00:00 next day (exclusive)
1 Day	24/06/2015 00:00	Tuesday, 23/06/2015	Week	7 slices between Monday, 22/06/2015 0:00, and Monday, 29/06/2015 00:00 (exclusive)
1 Week	22/06/2015 00:00	Monday 15/06/2015 to Sunday 21/06/2015 (inclusive)	All weeks that are fully in this quarter ((but not those that reach into another quarter, unless it is the selected week. The selected week is in a quarter if 4 or more days (out of 7) are in that quarter)).	12 slices between Monday 06/04/2015 and Monday 29/06/2015 (exclusive)
1 Month	01/07/2015 00:00	June 2015	Year	12 slices between 01/01/2015 and 01/01/2016 (exclusive)
1 Quarter	01/07/2015 00:00	2nd quarter of 2015	4 quarters before and after	9 slices between 01/04/2014 and 01/07/2016 (exclusive)
1 Year	01/01/2016	The year 2015	4 years before and after	9 slices between 2011 and 2019 (inclusive)

If the derived Drill-Up Period should include one or more time slices that would lie entirely in the future, they will naturally be returned as 0 values. The Drill-Up Period will stick to the calendar system, so to say.

In case the selected period is not a typical calendar unit; i.e., sliceUnitCount is bigger than 1, there will be no rounding for the selected period. Therefore, it could lie on the time line; e.g., 12 hours from 04:23 to 16:23. The Drill-Up Period will respect that and instead of aligning with natural calendar units return 4 time slices before and after the Selected Period, resulting in a total of 9 slices.

If in the case that the derived Drill-Up Period should include one or more time slices that lie entirely in the future, they will not be returned, but instead the same number of time slices in the past will be added.

Example: If you aggregate 3-hourly with a selected period of 12:00h to 15:00h and do a request at 18:30, the response will drop the last 2 time slices and add two from the past instead like this:

Request time: 18:30

Time Slice	18-21	21-24	00-03	03-06	06-09	09-12	12-15	15-18	18-21	21-24	00-03
Value	240	120	40	10	40	160	170	320	60 (unfinished)	-	-
Comment	added	added					Selected Period			dropped	dropped

Drill-Down Period

This period is used to represent the selected period as a sum of smaller time slices. These time slices will all have the same length and together make is what we call a Drill-Down Period.

Returning data about the Drill-Down Period can be requested in the call for KPI details. Its extent is always calculated by OPX, not defined by the client. OPX will take the given selected period and break it down into smaller time units. For example it will show a selected day in context of the individual hours that make up that day.

The extent of the calculated Drill-Down Period will be returned by giving a periodEnd again, and the sliceCount which represents the number of time slices within the Drill-Down Period. The sliceUnitCount is a factor in specifying the length of each of those slices.

In addition to the KPI value of each time slice in the Drill-Down Period, the detail query will also return the maximum value maxValue, minimum value minValue, and average value avgValue of time slices in this Drill-Down Period.

Visualization of Drill-Down Period

In the graph above, the selected period is a single day: Thursday, July 2. The Drill-Down Period for it consists of 24 hours, each represented with its own KPI value. A user can navigate back and forth within these 24 hours, as well as make a larger shift of the Drill-Down Period to the previous or next one. Since the client cannot explicitly specify the Drill-Up Period, the response helps by returning the attributes previousSelectedPeriod and nextSelectedPeriod. These attributes denote the previous and the Drill-Down Periods that could be selected from the current Drill-Down Period.

Deriving Drill-Down Period from Selected Period

The Drill-Down Period is designed to break down the selected period into smaller user-intuitive time units. The mapping that is used for it is given below.

Mapping for Calendar Units:

Selected Period Length	Example periodEnd	Resulting Selected Period	Drill-Down Period	Example Drill-Down Period
1 Day	24/06/2015 00:00	Tuesday, 23/06/2015	24 hours	24 slices between 00:00 this day and 00:00 next day (exclusive)
1 Week	22/06/2015 00:00	Monday 15/06/2015 to Sunday 21/06/2015 (inclusive)	7 days	7 slices between Monday, 22/06/2015 0:00, and Monday, 29/06/2015 00:00 (exclusive)
1 Month	01/07/2015 00:00	June 2015	30 days	30 slices between Monday 01/06/2015 and Wednesday 01/07/2015 (exclusive)
1 Quarter	30/09/2015 00:00	3rd quarter of 2015	All weeks that have 4 or more days within this quarter	14 slices between 01/07/2015 and 01/10/2016 (exclusive)
1 Year	01/01/2016	The year 2015	12 months	12 slices between 01/01/2015 and 01/01/2016 (exclusive)

Mapping for Rolling Time Units (assuming current date and time is 08/08/2016, 22:00):

Selected Period Length	Example periodEnd	Resulting Selected Period	Drill-Down Period	Example Drill-Down Period
24 hours	now	07/08/2016,00:00 to 08/08/2016, 00:00 (exclusive)	last 24 hours	24 slices between 07/08/2016, 00:00 and 08/08/2016, 00:00 (exclusive)
7 days	now	01/08/2016 to 08/08/2016 (exclusive)	last 7 days	7 slices between 01/08/2016, 0:00, and 08/08/2016, 00:00 (exclusive)
30 days	now	08/07/2016 to 08/08/2016 (exclusive)	last 30 days	30 slices between 08/07/2016 and 08/07/2015 (exclusive)
90 days	now	08/05/2016 to 08/08/2016 (exclusive)	last 90 days	90 slices between 08/05/2016 and 08/08/2016 (exclusive)

If the derived Drill-Down Period should include one or more time slices that would lie entirely in the future, they will naturally be returned as 0 values.

Web Content Display

API Endpoints: Navigation

The OPX Analytics API was designed to be highly flexible with regards to extensible and customizable KPIs. The API provides all navigation options and available KPIs with their values. This part of the documentation shows you, which data is avilable to build clients with user interfaces for navigation.

More on the underlying concepts can be found under Filtering.

Authentication

In order to access the OPX Analytics API your system needs to retrieve a temporary access token from our authentication interface. To do so, it needs to submit the login credentials of a user with corresponding permissions (currently the Business role)

API Call: POST /auth

Example Request

{
    "subject" :{
        "userName" : "e@mail.address" ,
        "password" : "MySuperSecretPassword"
},
    "authenticationRequest" : true
}

Example Responses:

Successful Authentication:

{
    "result" :
        "authenticated" : true,
        "token" : "qb85vdh521cb7795inqb3d13k2g709rlaepfkuo49a",
        "authUserId" : "56558ef0e4b009d5202988ae",
        "authorized" : false
  },
    ... // some more information here
}

Unsuccessful Authentication:

{
  "result": {
        "authenticated": false
   }
}

The token from the successful response can be used for consecutive calls against the OPX Analytics API. It works similar to the OPG authentication; however, since calls are made in the name of a user and not as a merchant, as in OPG, there will be no merchant code. Therefore the "user name" part of the HTTP Basic Auth will start with a slash "/", followed by the token. The "password" part will remain empty.

HTTP Basic Auth example:

Username: /qb85vdh521cb7795inqb3d13k2g709rlaepfkuo49a
Password: (empty)

In order to access the current user as a resource, your system will also need the authUserId from the successful response. In contrast to the token it's a permanent value that will not change.

Available Merchants, Divisions, and Sections

Once you are authenticated, you will want to analyze the KPIs of the different merchants and divisions that you have access to. To access these different KPI sections (groupings of KPIs) for the divisions, you will need to use the follwoing API call.

API Call: GET /users/{user_code}/merchants.

Example Response

[
   {
      "code": "1234",
      "label": "TestMerchant0",
      "defaultAggregationCurrencyCode": "EUR",
      "divisions": [
         {
            "code": "77799d0801e5785a677c031b",
            "label": "Division0"
         },
         {
            "code": "55889d0801e5785a677c032c",
            "label": "Division1"
         }
      ],
      "sections": [
               {
                  "code": "SALES",
                  "label": "Sales",
                  "iconUrlWOnB": "https://www.somewhere.there/get/this/icon0.png"
               },
               {
                  "code": "CONVERSIONS",
                  "label": "Conversion",
                  "iconUrlWOnB": "https://www.somewhere.there/get/this/icon1.png"
               },
               {
                  "code": "CUSTOMERS",
                  "label": "Customers",
                  "iconUrlWOnB": "https://www.somewhere.there/get/this/icon2.png"
               }
            ]
   },
   {
     "code": "12345",
     "label": "TestMerchant1",
     "defaultAggregationCurrencyCode": "GBP",
     "divisions": [
        {
          "code": "ypmok0801e5785a677c031b",
          "label": "Division0"
        },
        {
          "code": "asdf434523afdfg3642",
          "label": "Division1"
        }
     ],
   "sections": [
               {
                  "code": "SALES",
                  "label": "Sales",
                  "iconUrlWOnB": "https://www.somewhere.there/get/this/icon0.png"
               },
               {
                  "code": "CONVERSIONS",
                  "label": "Conversion",
                  "iconUrlWOnB": "https://www.somewhere.there/get/this/icon1.png"
               },
               {
                  "code": "TRANSACTIONS",
                  "label": "Transactions",
                  "iconUrlWOnB": "https://www.somewhere.there/get/this/icon2.png"
               }
            ]
   }
 ]

The response structure is a list of merchants that are accessible for the authenticated user. Each merchant contains a list of accessible divisions and each division has its own list of KPI sections, i.e, groupings of the available KPIs. Since KPIs are customizalbe, each division could have different customised KPI sections. Therefore, the KPIs are listed individually for each section.

Also sections contain an attribute called iconUrlWOnB, which holds a URL pointing to an icon that could be used to represent the section visually in the client. They are designed to be white on a black background. Other versions are available upon request.

Merchants, Divisions, and Sections all have a code, which can be used to identify them in further calls and access more information.

Available Sections of a Division

If you browse the context of a specific division, the available KPI sections can be retrieved individually for that division.

API Call: GET /merchants/{merchant_code}/sections

The section objects and attributes are the same, as previously described, with respect to the API call retrieving merchants, divisions, and sections.

Example Response

   {
      "code":"SALES",
      "label":"Sales",
      "iconUrlWOnB":"https://www.somewhere.there/get/this/icon0.png"
   },
   {
      "code":"CONVERSIONS",
      "label":"Conversion",
      "iconUrlWOnB":"https://www.somewhere.there/get/this/icon1.png"
   },
   {
      "code":"CUSTOMERS",
      "label":"Customers",
      "iconUrlWOnB":"https://www.somewhere.there/get/this/icon2.png"
   }
]

Available KPIs of a Section

Your system can retrieve the full structure of the available KPIs and the general filtering options (General Dimensions) of the Sections, your different users created.

KPIs are not just a flat list. If a KPI (e.g., Gross Cashflow GCF) is composed of other KPIs (e.g., GCF = Successful Charges SCG - Reversals RVS), the different KPIs are treated as children in a tree structure. In this example, SCG and RVS are children of GCF. The way the composition works is reflected in the attribute operation. In the example SCG's operation is + and RVS's operation is -, meaning that the parent KPI GCF is calculated by "adding" SCG (adding to 0 that means, no other values are involved), and substracting RVS. The operation attribute is mainly intended to enable visualization of these compositions for the users.

To control the level of KPI children that should be returned, you can use the query parameter kpiChildLevels. The default is 0, meaning only the top level KPIs will be returned, no children.

API Call: GET /merchants/{merchant_code}/sections/{section_code}?kpiChildLevels={levels}

The General Dimensions (generalDims) of a section represent the filtering dimensions that can be applied to all KPIs of that section. Their children represent the possible values a user can choose from. In the example above, there is a dimension with a code called currency, and the options to choose from would be EUR and GBP. Other currencies do not appear in the underlying data set, so they are not offered.

For more information on dimensions and filtering see Filtering.

Example Response


{
  "code":"SALES",
  "label":"Sales",
  "kpis":[
    {
      "code":"GSL",
      "label":"Gross Sales",
      "children":[
        {
          "code":"SIC",
          "label":"Successful Immediate Charges",
          "operation":"+"
        },
        {
          "code":"OCG",
          "label":"Opened Charges",
          "operation":"+",
          "children":[
            {
              "code":"ODF",
              "label":"Opened Deferred Charges",
              "operation":"+"
            },
            {
              "code":"ODD",
              "label":"Opened Demanded Charges",
              "operation":"+"
            },
            {
              "code":"ORY",
              "label":"Opened Scheduled Retry Charges",
              "operation":"+"
            },
            {
              "code":"ORD",
              "label":"Opened Redirect Charges",
              "operation":"+"
            }
          ]
        }
      ]
    }
  ],
  "generalDims":[
    {
      "code":"region",
      "label":"Region",
      "children":[
        {
          "code":"AT",
          "label":"Austria"
        },
        {
          "code":"DE",
          "label":"Germany"
        },
        {
          "code":"GB",
          "label":"United Kingdom"
        }
      ]
    },
    {
      "code":"currency",
      "label":"Currency",
      "children":[
        {
          "code":"EUR",
          "label":"Euro"
        },
        {
          "code":"GBP",
          "label":"Pound Sterling"
        }
      ]
    }
  ]
}

Dimensions of a Section

If your system displays a user interface for filtering, it can only retrieve the general dimensions of a section, without the overhead of the KPI structure, like this:

API Call: GET /merchants/{merchant_code}/sections/{section_code}/dimensions

In this example there are more dimensions available for filtering. The meaning of the object attributes is the same as explained in the context of retrieving the full Section.

You can continue by reading about KPI endpoints.

Example Response


   {
      "code":"region",
      "label":"Region",
      "children":[
         {
            "code":"DE",
            "label":"Germany"
         },
         {
            "code":"GB",
            "label":"United Kingdom"
         },
         {
            "code":"US",
            "label":"USA"
         },
         {
            "code":"DK",
            "label":"Denmark"
         }
      ]
   },
   {
      "code":"currency",
      "label":"Currency",
      "children":[
         {
            "code":"EUR",
            "label":"Euro"
         },
         {
            "code":"GBP",
            "label":"Pound Sterling"
         },
         {
            "code":"USD",
            "label":"US Dollar"
         },
         {
            "code":"DKK",
            "label":"Danish Krone"
         }
      ]
   },
   {
      "code":"provider",
      "label":"Provider",
      "children":[
         {
            "code":"WIRECARD",
            "label":"WireCard"
         },
         {
            "code":"ADYEN",
            "label":"Adyen"
         },
         {
            "code":"PAYPAL",
            "label":"PayPal"
         }
      ]
   },
   {
      "code":"network",
      "label":"Payment Method",
      "children":[
         {
            "code":"VISA",
            "label":"VISA"
         },
         {
            "code":"MASTERCARD",
            "label":"MasterCard"
         },
         {
            "code":"PAYPAL",
            "label":"PayPal"
         }
      ]
   }
]

API Endpoints: Navigation

Please sign in to view further details of this article. Login

Web Content Display

API Endpoints: KPIs

Get all KPI Values of a Section

With this API call, your system can get all the KPIs of a section and their values for a given time period. There are multiple parameters to control the output.

API Call:

GET /merchants/{merchant_code}/sections/{section_code}/kpis

Optional parameters:

evaluate: true or false (default). Indicates whether the KPIs should be returned with their calculated values for the given time period; i.e., if KpiValue objects should be included.
periodEnd: timestamp with the UTC offset and a geographical location such as 2015-09-30T16:00:00+02:00Europe/Berlin. Default is now. Indicates the end of the Selected Period for which the KPI values should be calculated. The period end itself does not belong to the time period anymore. See also Time Handling.
sliceUnit: One of hour, day, week, month, quarter, or year. Indicates which time unit should be used to determine the length of the time period for which the KPI values should be calculated. Is required if evaluate=true.
sliceUnitCount: Integer number like 3. Default: 1. Can be used to increase the length of the time period, because the sliceUnitCount value will be multiplied with the sliceUnit. This way you can define periods like 12 hours or 15 days.
dimensionCode: filter the KPI according to available Dimensions: general and specific ones (except merchant which is given in URL path).
drillDown: true or false (default). Indicates whether KPI values for the Drill Down Period should be evaluated.
drillUp: true or false (default). Is used to specify whether KPI Values for the Drill Up Period should be evaluated.
{dimensionCode}: Providing a dimension code as parameter name and one or more of its data point codes as values, filters the result accordingly (see also Filtering). Example: region=DE;FR. Available dimensions could be different for different sections, they can be retrieved through Navigation Calls.
generalDims: true or false (default). Indicates whether the general dimensions for the KPI should be evaluated. Detailed information about general dimensions can be found at Filtering.
kpiChildLevels: Integer number like 4. Default: 0. Indicates the level of KPI children in the data tree structure that should be returned. 0 means only the top level KPIs are returned, no children.
kpiTrend: true or false (default). Determines whether data about the comparison KPI value should be returned. The comparison KPI value for a KPI with calendaric time period is a KPI value for the previous calendaric time period, e.g., this week's KPI value will be compared to the KPI value from the last week. For the KPIs with rolling time period, the comparison KPI value is calculated for the Drill-Up Period.
aggregationCurrencyCode: ISO 4217 currency code; e.g., USD. Default EUR. Currency used to normalize all KPI values, meaning to convert in case they originated from one or multiple different currencies.

Example Requests:

GET /merchants/UBUY/sections/SALES/kpis?evaluate=true&periodEnd=2016-06-24T00:00:00+02:00Europe2%FBerlin&sliceUnit=day&provider=WIRECARD;ALLPAGO

...returns all values of (top level) Transaction KPIs on the day 23rd of June 2016 (not the 24th) that were processed by the providers (which is an applicable dimension in this section) WireCard and Allpago.

GET /merchants/UBUY/sections/SALES/kpis?evaluate=true&sliceUnit=hour&sliceUnitCount=12&aggregationCurrencyCode=USD&kpiChildLevels=3

...returns the values of Transaction KPIs (and up to 3 child levels) in the last 12 hours (starting now). There is no rounding to a full hour; e.g., at 16:23h it would return everything between 15:23h and 16:23h. All values will be (also) shown in USD.

Example Response (see right column):

...for a query like:

GET /merchants/UBUY/sections/SALES/kpis?evaluate=true&region=GB

This example response basically represents the Gross Sales GSL tree from the Transactions KPIs, and leaves out the rest for readability.

Note: The amountInAggregationCurrency will always be present if the KPIs are evaluated. This contains the "value" of the KPI. amountInLocalCurrency will only be returned if all transactions in the scope of the applied filters actually had the same currency (which is then considered local).

quantity is the number of transactions (as opposed to their monetary value).

In the future, there will also be the optional response attribute percentage to express KPIs like conversion ratios.

The other attributes are the same as described in the context of Navigation Calls.

Example Response

[{
  "code": "GSL",
  "label": "Gross Sales",
  "kpiValue": {
    "amountInAggregationCurrency": {
      "unit": "EUR",
      "value": 25046.50
    },
    "amountInLocalCurrency": {
      "unit": "GBP",
      "value": 20872.08
    },
    "quantity": 1416
  },
  "children": [{
    "code": "SIC",
    "label": "Successful Immediate Charges",
    "operation": "+",
    "kpiValue": {
      "amountInAggregationCurrency": {
        "unit": "EUR",
        "value": 24242.42
      },
      "amountInLocalCurrency": {
        "unit": "GBP",
        "value": 20202.02
      },
      "quantity": 1212
    }
  },
  {
    "code": "OCG",
    "label": "Opened Charges",
    "operation": "+",
    "kpiValue": {
      "amountInAggregationCurrency": {
        "unit": "EUR",
        "value": 4844.48
      },
      "amountInLocalCurrency": {
        "unit": "GBP",
        "value": 4004.04
      },
      "quantity": 204
    },
    "children": [{
      "code": "ODF",
      "label": "Opened Deferred Charges",
      "operation": "+",
      "kpiValue": {
        "amountInAggregationCurrency": {
          "unit": "EUR",
          "value": 1211.12
        },
        "amountInLocalCurrency": {
          "unit": "GBP",
          "value": 1001.01
        },
        "quantity": 51
      }
    },
    {
      "code": "ODD",
      "label": "Opened Demanded Charges",
      "operation": "+",
      "kpiValue": {
        "amountInAggregationCurrency": {
          "unit": "EUR",
          "value": 1211.12
        },
        "amountInLocalCurrency": {
          "unit": "GBP",
          "value": 1001.01
        },
        "quantity": 51
      }
    },
    {
      "code": "ORY",
      "label": "Opened Scheduled Retry Charges",
      "operation": "+",
      "kpiValue": {
        "amountInAggregationCurrency": {
          "unit": "EUR",
          "value": 1211.12
        },
        "amountInLocalCurrency": {
          "unit": "GBP",
          "value": 1001.01
        },
        "quantity": 51
      }
    },
    {
      "code": "ORD",
      "label": "Opened Redirect Charges",
      "operation": "+",
      "kpiValue": {
        "amountInAggregationCurrency": {
          "unit": "EUR",
          "value": 1211.12
        },
        "amountInLocalCurrency": {
          "unit": "GBP",
          "value": 1001.01
        },
        "quantity": 51
      }
    }]
  }]
},
...
]

Get Children of one KPI

Returns an array of immediate children of the given KPI, and possibly their subtrees, optionally evaluated (i.e., with calculated values). Specific Dimension will not be returned. In that sense the call is similar to requesting all KPIs of a section, but with less overhead in the response about the root KPI and its siblings. The request parameters are exactly the same.

Optional parameters:
All but the generalDims parameter are present as in the API endpoint: GET /merchants/{merchant_code}/sections/{section_code}/kpis

API Call:

GET /merchants/{merchant_code}/sections/{section_code}/kpis/{kpi_code}/children

Example Request:

GET /merchants/UBUY/sections/SALES/kpis/GSL/children

Example Response:

[
    {
        "code": "SIC",
        "label": "Successful Immediate Charges",
        "operation": "+",
        "kpiValue": {
            "amountInAggregationCurrency": {
                "unit": "EUR",
                "value": 24242.42
            },
            "amountInLocalCurrency": {
                "unit": "GBP",
                "value": 20202.02
            },
            "quantity": 1212
        }
    },
    {
        "code": "OCG",
        "label": "Opened Charges",
        "operation": "+",
        "kpiValue": {
            "amountInAggregationCurrency": {
                "unit": "EUR",
                "value": 4844.48
            },
            "amountInLocalCurrency": {
                "unit": "GBP",
                "value": 4004.04
            },
            "quantity": 204
        },
        "children": [
            {
                "code": "ODF",
                "label": "Opened Deferred Charges",
                "operation": "+",
                "kpiValue": {
                    "amountInAggregationCurrency": {
                        "unit": "EUR",
                        "value": 1211.12
                    },
                    "amountInLocalCurrency": {
                        "unit": "GBP",
                        "value": 1001.01
                    },
                    "quantity": 51
                }
            },
            {
                "code": "ODD",
                "label": "Opened Demanded Charges",
                "operation": "+",
                "kpiValue": {
                    "amountInAggregationCurrency": {
                        "unit": "EUR",
                        "value": 1211.12
                    },
                    "amountInLocalCurrency": {
                        "unit": "GBP",
                        "value": 1001.01
                    },
                    "quantity": 51
                }
            },
            {
                "code": "ORY",
                "label": "Opened Scheduled Retry Charges",
                "operation": "+",
                "kpiValue": {
                    "amountInAggregationCurrency": {
                        "unit": "EUR",
                        "value": 1211.12
                    },
                    "amountInLocalCurrency": {
                        "unit": "GBP",
                        "value": 1001.01
                    },
                    "quantity": 51
                }
            },
            {
                "code": "ORD",
                "label": "Opened Redirect Charges",
                "operation": "+",
                "kpiValue": {
                    "amountInAggregationCurrency": {
                        "unit": "EUR",
                        "value": 1211.12
                    },
                    "amountInLocalCurrency": {
                        "unit": "GBP",
                        "value": 1001.01
                    },
                    "quantity": 51
                }
            }
        ]
    }
]

Get all Details of one KPI

This call delivers the most extensive information about one specific KPI within the given time and dimension filters. It returns Specific Dimensions, which is a contrast to General Dimensions that does not apply to all the other KPIs of the section. It can also show the KPI values over the course of time within a Drill Up or Drill Down Period, along with some data that compares the selected period with these periods.

API Call:

GET /merchants/{merchant_code}/sections/{section_code}/kpis/{kpi_code}

The same parameters as when retrieving all KPIs of a section can be used. On top of that, these are possible:

generalDims: true or false (default). Indicates whether General Dimensions for the KPI should be returned. Usually, General Dimensions should only be returned in the scope of a section call for performance reasons, because they are equal across a whole section. However, when requesting a KPI in the context of the customizable dashboard (and therefore outside of a section), it may be handy to get the General Dimensions to explicitly show all available filtering options by setting this parameter to true .
specificDims: true or false (default). If you set to true, the response not only returns the available Specific Dimensions and their possible data points for Filtering but it will also calculate and return the KPI values for each of these data points. For the Gross Transactions KPI (GSL) it would, for example, show the Specific Dimension Recurring Flow with the two data points Recurring and Non-Recurring, and reflect which amount of the total KPI value falls into each of these categories. However, General dimensions cannot be evaluated in this call.

Example Response

...as sown on the right column is for a query like:

GET /merchants/UBUY/sections/SALES/kpis/GSL?evaluate=true&aggregationCurrency=USD&specificDims=true&drillUp=true&generalDims=true&kpiChildLevels=1

There are two "new" major attributes returned in this call:

specificDims : The Specific Dimensions can be handled like the General Dimensions, and they are returned in the same data structure, as described in navigation calls . They reflect additional filter dimensions (and their potential values) that do not apply to all KPIs in that section, but only some (including the one in question). Therefore, they will be included for every KPI individually, if they exist.

drillUp: If explicitly requested, the response will contain KPI data not only for the selected period, but also for corresponding periods before and after that, which together constitute the Drill Up Period. The example response here corresponds largely to the visualization on the Time Handling page.

The Drill Up Period is specifically described in the sub attribute timePeriod, having a periodEnd and a sliceCount; i.e., the number of time slices that will follow. Each time slice has the same sliceUnit and a sliceUnitCount that describe their length in time. A typical example would be 1 day, but it could also be 12 hours, etc. This length is equal to the length of the selected period from the request. The result is a linear distribution that can be used to draw charts.

In addition, there are 3 corner values that give more information about the Drill Up Period:

avgValue: The average across all time slices in the Drill Up Period.
minValue and maxValue: The minimum and maximum values of slices in the Drill Up Period.

By comparing these values to the actual KPI value of the selected period the user can get a better feeling about how this number relates to the bigger picture in the context of the Drill Up Period.

The actual values of the time slices of the Drill Up Period will be reflected in the array called kpiValues. Actually, the selected period is one of these slices. The selectedPeriodValueIndex will tell you exactly which one (with 0 being the first element in the array).

The attributes previousSelectedPeriod and nextSelectedPeriod allow the you to navigate back and forth of the selected period (e.g., next and previous day) and to jump between Drill Up Periods (e.g., next or previous week, which typically corresponds to what you are seeing on the screen as a graph). They also indicate which selected period a request would need to specify in order to shift one whole Drill Up Period back or forth. Note that in the request a client cannot specify the Drill Up Period directly, therefore the corresponding Selected Periods are calculated and returned here.

See Time Handling for a more extensive explanation and visualization of the time related concepts.

Example Response

{
  "code": "GSL",
  "label": "Gross Sales",
  "kpiValue": {
    "amountInAggregationCurrency": {
      "unit": "USD",
      "value": 5789.12
    },
    "amountInLocalCurrency": {
      "unit": "EUR",
      "value": 5262.84
    },
    "quantity": 321,
    "timePeriod": {
      "periodEnd": "2016-08-08T00:00:00.000+02Europe/Berlin",
      "sliceUnit": "day",
      "sliceUnitCount": 1
    }
  },
  "specificDims": [{
    "code": "recurring",
    "label": "Recurring Flow",
    "children": [{
      "code": "N",
      "label": "Non-Recurring",
      "kpiValue": {
        "amountInAggregationCurrency": {
          "unit": "USD",
          "value": 2332.52
        },
        "amountInLocalCurrency": {
          "unit": "EUR",
          "value": 2120.47
        },
        "quantity": 150
      }
    },
    {
      "code": "R",
      "label": "Recurring",
      "kpiValue": {
        "amountInAggregationCurrency": {
          "unit": "USD",
          "value": 3456.60
        },
        "amountInLocalCurrency": {
          "unit": "EUR",
          "value": 3142.36
        },
        "quantity": 171
      }
    }]
  },
  {
    "code": "trigger",
    "label": "Trigger",
    "children": [{
      "code": "N",
      "label": "New Account",
      "kpiValue": {
        "amountInAggregationCurrency": {
          "unit": "USD",
          "value": 2332.52
        },
        "amountInLocalCurrency": {
          "unit": "EUR",
          "value": 2120.47
        },
        "quantity": 150
      }
    },
    {
      "code": "R",
      "label": "Recurring Account",
      "kpiValue": {
        "amountInAggregationCurrency": {
          "unit": "USD",
          "value": 3456.60
        },
        "amountInLocalCurrency": {
          "unit": "EUR",
          "value": 3142.36
        },
        "quantity": 171
      }
    }]
  }],
  "generalDims": [{
    "code": "region",
    "label": "Region",
    "children": [{
      "code": "DE",
      "label": "Germany"
    },
    {
      "code": "AT",
      "label": "Austria"
    },
    {
      "code": "FR",
      "label": "France"
    }]
  },
  {
    "code": "currency",
    "label": "Currency",
    "children": [{
      "code": "EUR",
      "label": "Euro"
    }]
  },
  {
    "code": "network",
    "label": "Network",
    "children": [{
      "code": "VISA",
      "label": "VISA"
    },
    {
      "code": "MASTERCARD",
      "label": "MasterCard"
    },
    {
      "code": "PAYPAL",
      "label": "PayPal"
    }]
  },
  {
    "code": "provider",
    "label": "Provider",
    "children": [{
      "code": "WIRECARD",
      "label": "WireCard"
    },
    {
      "code": "PAYPAL",
      "label": "PayPal"
    }]
  }],
  "drillUp": {
    "kpiValues": [{
      "amountInAggregationCurrency": {
        "unit": "EUR",
        "value": 124.56
      },
      "amountInLocalCurrency": {
        "unit": "USD",
        "value": 103
      },
      "quantity": 133,
      "timePeriod": {
        "periodEnd": "2016-08-02T00:00:00.000+02:00Europe/Berlin",
        "sliceUnit": "day",
        "sliceUnitCount": 1
      }
    },
    {
      "amountInAggregationCurrency": {
        "unit": "EUR",
        "value": 107.5
      },
      "amountInLocalCurrency": {
        "unit": "USD",
        "value": 97.5
      },
      "quantity": 123,
      "timePeriod": {
        "periodEnd": "2016-08-03T00:00:00.000+02:00Europe/Berlin",
        "sliceUnit": "day",
        "sliceUnitCount": 1
      }
    },
    {
      "amountInAggregationCurrency": {
        "unit": "EUR",
        "value": 124.03
      },
      "amountInLocalCurrency": {
        "unit": "USD",
        "value": 115
      },
      "quantity": 89,
      "timePeriod": {
        "periodEnd": "2016-08-04T00:00:00.000+02:00Europe/Berlin",
        "sliceUnit": "day",
        "sliceUnitCount": 1
      }
    },
    {
      "amountInAggregationCurrency": {
        "unit": "EUR",
        "value": 154.56
      },
      "amountInLocalCurrency": {
        "unit": "USD",
        "value": 143.5
      },
      "quantity": 116,
      "timePeriod": {
        "periodEnd": "2016-08-05T00:00:00.000+02:00Europe/Berlin",
        "sliceUnit": "day",
        "sliceUnitCount": 1
      }
    },
    {
      "amountInAggregationCurrency": {
        "unit": "EUR",
        "value": 165
      },
      "amountInLocalCurrency": {
        "unit": "USD",
        "value": 154
      },
      "quantity": 112,
      "timePeriod": {
        "periodEnd": "2016-08-06T00:00:00.000+02:00Europe/Berlin",
        "sliceUnit": "day",
        "sliceUnitCount": 1
      }
    },
    {
      "amountInAggregationCurrency": {
        "unit": "EUR",
        "value": 234.5
      },
      "amountInLocalCurrency": {
        "unit": "USD",
        "value": 197.4
      },
      "quantity": 149,
      "timePeriod": {
        "periodEnd": "2016-08-07T00:00:00.000+02:00Europe/Berlin",
        "sliceUnit": "day",
        "sliceUnitCount": 1
      }
    },
    {
      "amountInAggregationCurrency": {
        "unit": "EUR",
        "value": 566.8
      },
      "amountInLocalCurrency": {
        "unit": "USD",
        "value": 537
      },
      "quantity": 349,
      "timePeriod": {
        "periodEnd": "2016-08-08T00:00:00.000+02:00Europe/Berlin",
        "sliceUnit": "day",
        "sliceUnitCount": 1
      }
    }],
    "timePeriod": {
      "periodEnd": "2016-08-08T00:00:00.000+02:00Europe/Berlin",
      "sliceUnit": "day",
      "sliceUnitCount": 1,
      "sliceCount": 7
    },
    "avgValue": {
      "amountInAggregationCurrency": {
        "unit": "EUR",
        "value": 210.9
      },
      "amountInLocalCurrency": {
        "unit": "USD",
        "value": 203.5
      }
    },
    "minValue": {
      "amountInAggregationCurrency": {
        "unit": "EUR",
        "value": 107.5
      },
      "amountInLocalCurrency": {
        "unit": "USD",
        "value": 98.2
      }
    },
    "maxValue": {
      "amountInAggregationCurrency": {
        "unit": "EUR",
        "value": 566.8
      },
      "amountInLocalCurrency": {
        "unit": "USD",
        "value": 545.2
      }
    },
    "selectedPeriodValueIndex": 6
  },
  "children": [{
    "code": "OCG",
    "label": "Opened Charges",
    "operation": "+",
    "kpiValue": {
      "amountInAggregationCurrency": {
        "unit": "USD",
        "value": 1001.123
      },
      "amountInLocalCurrency": {
        "unit": "EUR",
        "value": 910.1
      },
      "quantity": 20
    },
    "specificDims": [{
      "code": "trigger",
      "label": "Trigger",
      "children": [{
        "code": "N",
        "label": "New Account"
      },
      {
        "code": "A",
        "label": "Registered Account"
      }]
    },
    {
      "code": "deferred",
      "label": "Deferred Flow",
      "children": [{
        "code": "N",
        "label": "Non-Deferred"
      },
      {
        "code": "D",
        "label": "Deferred"
      }]
    },
    {
      "code": "recurring",
      "label": "Recurring Flow",
      "children": [{
        "code": "N",
        "label": "Non-Recurring"
      },
      {
        "code": "R",
        "label": "Recurring"
      }]
    }]
  },
  {
    "code": "SIC",
    "label": "Successful Immediate Charges",
    "operation": "+",
    "kpiValue": {
      "amountInAggregationCurrency": {
        "unit": "USD",
        "value": 4788.01
      },
      "amountInLocalCurrency": {
        "unit": "EUR",
        "value": 4352.74
      },
      "quantity": 301
    },
    "specificDims": [{
      "code": "recurring",
      "label": "Recurring Flow",
      "children": [{
        "code": "N",
        "label": "Non-Recurring"
      },
      {
        "code": "R",
        "label": "Recurring"
      }]
    },
    {
      "code": "trigger",
      "label": "Trigger",
      "children": [{
        "code": "N",
        "label": "New Account"
      },
      {
        "code": "A",
        "label": "Registered Account"
      }]
    }]
  }]
}

API Endpoints: KPIs

Please sign in to view further details of this article. Login

Web Content Display

OPX Reports

As a merchant you can retrieve the transaction data of selected or all divisions within any given time period (up to one year) through this API. This also gives you the possibility to reconcile against the transaction statuses as they were received by the OPG from the individual providers.

Note that the Report API is designed to be a list of individual transactions. Depending on your use case you could also;

use OPX Analytics in order to retrieve aggregated data for Business Intelligence purposes,
do GET requests on CHARGE objects to get full details on a single transaction,
use the Transaction Monitor from the portal to access the same data base manually through a graphical user interface.

Available Data Fields

For each transaction the following data fields are available through the API. In the response they will be ordered as shown here. Bold means the attribute is contained in the current default report type called payments.

We recommend that you create your own report type, so that you can minimize file sizes, increase download speed, and keep a format that is guaranteed to never change. We will show you how to do this below.

Attribute	Description
merchant	You merchant code. Handy when compiling reports across multiple merchants.
division	The division code
timestamp	Time of transaction creation, incl. time zone information
transactionId	As assigned by your system in the List Request
longId	ID of the transaction given by OPG (uniqueness guaranteed)
shortId	Short ID of the transaction as given by the OPG. Simplification for support communication.
registrationId	The `customerRegistrationId` as created by the OPG for a new customer registration.
referredId	`longId` of a parent operation. Handy for tracking PAYOUT transaction back to original CHARGE or CLOSING transactions, etc.
invoiceId	As (potentially) assigned by your system in the List Request
network	Code of the payment method used in processing
provider	Code of provider used in processing
operation	Code of operation type: `LIST`, `CHARGE`, `CLOSING`, or `PAYOUT`.
channel	As (potentially) assigned by your system in the LIST Request to indicate where the payment request comes from. For instance: `WEB_ORDER`, `MOBILE_ORDER`, `RECURRING`.
country	Country where the payment originated, as provided by your system in the LIST Request.
resultCode	See Result Codes. We recommend to use the simpler Status, Interaction, or Return Codes for most use cases instead.
resultInfo	Textual result info to the relevant operation. The source could be the OPG, a PSP, or bank, so therefore, the textual representation varies. Mostly intended for debugging.
returnCodeName	Unified provider response, see Return Codes
returnCodeSource	Source of the Return Code, see Return Codes
interactionCode	A recommendation for the merchant system on how to proceed after a transaction. See Interaction Codes.
interactionReason	See Interaction Codes
statusCode	Describes the current state of an operation. See Status Codes.
reasonCode	See Status Codes
holderName	Account holder name
customerNumber	As assigned by your system in the LIST Request
customerName	As assigned by your system in the LIST Request
customerEmail	As assigned by your system in the LIST Request
amount	Processed payment amount
currency	Processed payment currency
providerCostsAmount	The processing costs charged by provider per transaction
providerCostsCurrency	The currency applied to provider costs amount

Naturally, there will be overlapping with respect to the data provided in the Status Notifications.

Base URLs

For each of the API calls use these as base URLs:

Sandbox: reportapi.sandbox.oscato.com
Live: reportapi.live.oscato.com

As a result the final URL could look like: https://reportapi.sandbox.oscato.com/reports/merchants/UBUY/reporttypes

Authentication

You need separate tokens to access the Report API. They will be provided on request.

You can use them together with your merchant code in analogy to the payment API authentication.

They are different for Live and Sandbox. You cannot use the payment tokens.

Web Content Display

Managing Report Types

The default report type could be changed any time by optile. Therefore we highly recommend that you create your own report type with exactly the data fields you need for production usage.

Creating a Report Type

You can specify the data fields you want to be returned for each transaction and set some other options with this API call:

POST /reports/merchants/{merchant_code}/reporttypes

In the request body for this API call you can customize the report options.

Report options:

code: Choosable by the requester, will identify the new report type in future calls. Has to be URL-compatible and match the regex "[a-zA-Z0-9]{1,500}".
delimiter: Determines the type of delimiter (comma, or semicolon) that is used to separate data fields, either:
- ; (directly recognized by German Excel versions) or
- , (default, recognized by many other Excel versions)
fields: Specifies which data fields are in a report, see attribute table above. Must be provided.
heading: true (default) or false. Indicates whether the names of data fields are included at the beginning of a report. If multiple reports are merged by the merchant it can be convenient to leave out the headings.
operations: specifies which types of operations are included in a report. Potential values:
- LIST: List Requests, not directly payment related, and not included in the default report.
- CHARGE: CHARGE Requests that trigger a direct payment, deferred payment, or initialize an external payment session with customer redirect (e.g., PayPal).
- CLOSING: The capture of a deferred payment.
- PAYOUT: Trigger refunds or credit

Example Request:

POST /reports/merchants/UBUY/reporttypes

Example Request Body >>

If you make the API call with this request body, it will create a report type with the code MyReport. From that actual reports can be retrieved, that will contain the specified data fields and include CHARGE and PAYOUT transactions.

Further Handling of Report Types

In a REST manner you can also read or delete a Report Type:

GET    /reports/merchants/UBUY/reporttypes/myReport

DELETE /reports/merchants/UBUY/reporttypes/myReport

You cannot change (update) a Report Type, though, in order to prevent involuntary breaking changes. Create a new one with a new code instead.

A list of existing Report Types you can get like that:

GET    /reports/merchants/UBUY/reporttypes

Example Request

{
  "code": "MyReport",
  "delimiter": ";",
  "fields": [
      "division",
      "transactionId",
      "network",
      "provider",
      "operation",
      "amount",
      "currency"
  ],
  "heading": false,
  "operations": [
      "CHARGE",
      "PAYOUT"
   ]
}

Managing Report Types

Please sign in to view further details of this article. Login

Web Content Display

Retrieving Reports

Once you have created a report type or you want to test with the default report, you can retrieve a report for a period of time up to one year, with or without compression.

Example Requests:

GET /reports/merchants/UBUY/divisions/default/payments.csv?from=2016-01-01T00%3A00%3A00%2B0100&to=2016-02-01T00%3A00%3A00%2B0100

GET /reports/merchants/UBUY/alldivisions/MyReport.csv.gz?from=2016-01-01T00%3A00%3A00%2B0100&to=2016-02-01T00%3A00%3A00%2B0100

Request Parameters:

Division (URL path): You can filter by division using;
- /divisions/{divisionName} only returns transactions of the given division, in the example default.
- alldivisions returns transactions for all divisions.
Report type (file name): The code of your custom report type, in the example myReport, or the default type payments.
Compression (via file extension):
- csv uncompressed
- csv.gz compressed: recommended to decrease data volume and increase download speed
from (query parameter): the starting timepoint, from which transactions are included in the report. The examples show a URL-encoded version of 2016-01-01T00:00:00+0100.
to (query parameter): the ending timepoint, until which transactions are included. The maximal period length is one year. The examples show a URL-encoded version of 2016-02-01T00:00:00+0100, so the request covers January 2016 in the CET time zone.

Example Response


merchant,division,timestamp,transactionId,longId,network,provider,operation,channel,country,customerNumber,amount,currency
UBUY,Default,2016-06-07T00:01:20.464+0200,201606070001_2,5755f2b0e4b054ed79da6567c,VISA,ADYEN,CHARGE,WEB_ORDER,DE,c40404,42.11,EUR
UBUY,Primary,2016-07-07T00:01:20.464+0200,201606070001_2,6755f2b0e4b054ed79da8888c,VISA,ADYEN,CHARGE,WEB_ORDER,DE,c40505,50.20,EUR
...

Web Content Display

OPX Accounts

OPX Accounts is a universal accounts booking API, based on double entry bookkeeping principles, which can be used for different applications, such as wallets, loyalty programs, transaction aggregation, micro payments, etc.

Web Content Display

Introduction

Transactions and Transaction Safety

OPX Accounts supports transactions between accounts which result in two opposing Entries, one Credit and one Debit. These transactions adhere to the ACID principle, so they will always be atomic without the possibility for partial execution, create consistent states, isolated against concurrent events, and stored durably.

In the following example a customer returns goods worth 100 EUR, so the opposing bookings are made: the cash account gets credited, the returns account gets debited. Both entries together constitute one transaction. On the right hand side you see the general data structure of how Accounts, Entries and Transactions relate to each other.

Subscription Billing

For subscription management you would typically have a "receivables" account for each customer. This serves as an intermediary between subscription cycles and payment cycles.

The subscription cycles credit the account for each time a payment is due according to the contract with the customer. For example, 10 EUR on the 1^st of each month. This will result in a balance that reflects the total amount the customer owes. The payment cycles typically follow closely to the subscription cycles and try to make a recurring charge of the amount of the current balance. If a payment was successful, the account will be debited accordingly. The goal of the payment cycle is therefore to bring the balance of the receivables account back to 0 again.

In the happy case this is a straight-forward process. The full value of the intermediary account unfolds when it comes to additional use cases or edge cases, for example:

A payment was not successful: The customer may accumulate another subscription amount, resulting in a higher account balance, for example 20 EUR. The payment cycle then picks up automatically on the total amount due instead of just a single rate, and may be able to fetch the whole 20 EUR after a while.
Additional purchases or discounts: A customer may be able to make one-time purchases of additional items, e.g. movies that are not included in the subscription. These amounts can be credited to the receivables account any time. Since they are reflected in the balance they will be picked up by the next payment run automatically and bundled together into one payment transaction.
Any kind of pay-per-use or wallet auto-loading functionality, that allows users to purchase on temporary credit (i.e., into a negative balance) until the account is cleared, also falls into this category, even without a fixed subscription amount.
The same goes for anything that lowers the payment amount. For example, you could debit a few EUR from the receivables account if the customer takes part in a survey or subscribes to a newsletter. They may also return / cancel a purchase they made, so you debit the whole item price. In these cases you can spare explicit refunds to the customer and just account for them in the next payment run, thereby merging them into a single payment transaction again.

As a result the receivables account can have multiple additions before it gets set to 0 again by a successful payment cycle, as visualized in this example:

The history of entries on the receivables account between two (regular) payment cycles typically corresponds to the invoice you can present to a customer, e.g. for one month. Also the whole history together with the payment entries (potentially bringing down the balance to 0 again) and the resulting balance after each entry can be made transparent to the customer, typically in a self-service area, so that they know how their payment amounts are composed.

As contra accounts for the transactions described above you could have "paid" for received money, "subscription revenue" and "one time revenue" for your revenue streams, as well as "discounts" and "returns" for your credits to customers, or whatever classification is most helpful for your purposes.

Tree Structures

OPX Accounts offers indefinite nesting of accounts to enable advanced structures. They can be customly set up by the merchant through the API. This way complex business domains can be modeled, and balances of subaccounts are automatically aggregated into their parent accounts.

This is an example of an account tree which will also be used throughout the rest of the documentation:

You can read more about the API for manipulationg account structures and transactions, and some fundamental principles in the following sections.

Please contact us if you want to access OPX Accounts.

This documentation is work in progress. Some examples still need to be completed.

Web Content Display

Basic Operations

First steps with some basic operations are shown here.

Basic Operations

First steps with some basic operations are shown here.

Please sign in to view further details of this article. Login

Web Content Display

Create and Read Accounts

In the API accounts are resources in the REST sense. Therefore, if you have merchant access to OPX Accounts (in this example we use the merchant code SHOP1), you can create accounts within your domain with POST requests as shown in the examples to the right.

In our example we will create two accounts with these assigned codes:

one
two

POST /merchants/SHOP1/accounts
{
  "code": "one"
}

POST /merchants/SHOP1/accounts
{
  "code": "two"
}

Accounts can be identified by their code in the resource URL. They can contain letters, numbers, underscore, minus, and dot. They are case sensitive.

Now you can read the accounts again with a simple GET request and the code which you assigned.

You can also use the longId instead of the code. There's more information about the differences and implications below.

GET /merchants/SHOP1/accounts/one

...returns:

{
  "longId": "abcd-1234",
  "code": "one"
}

To retrieve a list of (sub)accounts you can just make a GET on the collection, see example.

GET /merchants/SHOP1/accounts/

Create and Read Accounts

Please sign in to view further details of this article. Login

Web Content Display

Make Transactions between Accounts

Following double entry bookkeeping principles, a transaction always involves two accounts. In each it will create an entry:

One debit entry in the first account
One corresponding credit entry in the second account

These transactions adhere to the ACID principle, so they will always be atomic without the possibility for partial execution, create consistent states, isolated against concurrent events, and stored durably.

Entries in accounts cannot be created directly, only through transactions, which will always involve two opposing entries: one credit and one debit. A credit increases the balance of an account. A debit decreases it.

In our example we will transfer money from one account to the other.

The resultingBalance of the transaction's entries and the balance when reading the accounts again reveal that both accounts have now opposing balances:

Account one: balance = 100
Account two: balance = -100

This means we successfully transfered from one account to another.

POST /merchants/SHOP1/accounts/one/transactions
{
  ...
}

...returns:

{
  ...
}

Make Transactions between Accounts

Please sign in to view further details of this article. Login

Web Content Display

Read Account History Entries

If you want to see the bookings on one account, you can GET its entries, see example on the right.

A transaction always involves two accounts through its two entries. An entry, however, belongs to exactly one account. So the booking history of an account consists of its entries.

GET /merchants/SHOP1/accounts/two/entries

...returns:

{
  ...
}

You can also just get the credit or debit entries, see further examples on the right.

GET /merchants/SHOP1/accounts/two/credits
GET /merchants/SHOP1/accounts/two/debits

To paginate and sort the result (a list of entries) you can use these query parameters:

Parameter	Type	Description	Example
`pageNumber`	Integer	Page to be retrieved, 0 indexed, defaults to 0.	`pageNumber=3`
`pageSize`	Integer	Size of the page to be retrieved (number of entries), defaults to 25.	`pageSize=50`
`sort`	String	Property that should be sorted by in the format `property(,asc\|desc)`. Default sort property is `createdAt`, default direction is descending.	`sort=createdAt,asc`
`sort` (advanced)	String	For advanced sorting by multiple properties you can use the format `property1,property2(,asc\|desc)`. Use multiple `sort` parameters if you want to switch directions, e.g. `?sort=property1,desc&sort=property2,asc`. This makes sense if there is additional, application specific meta data attached to the entries. For example, bookings could be attributed to a `marketingCampaign` and a `name`.	`?sort=marketingCampaign,createdAt,desc&sort=name,asc`

GET /merchants/SHOP1/accounts/two/entries?pageNumber=3&pageSize=50&sort=createdAt,asc

The current balance of an account with entries is always the aggregation of all its entries, where credits and debits oppose each other.

In the example to the right the account with two entries has a negative balance of -3.50, but that would change with additional entries, of course.

/accounts/MYTX/entry/001/
{"type": "debit", "amount": 6.5, ...}

and

/accounts/MYTX/entry/002/
{"type": "credit", "amount": 10.0, ...}

/accounts/MYTX/
{"balance": -3.5, ...}

Read Account History Entries

Please sign in to view further details of this article. Login

Web Content Display

Account Tree Structures

OPX Accounts offers indefinite nesting of accounts, with the following set of principles in place. This way complex business domains can be modeled, and balances of subaccounts are automatically aggregated into their parent accounts.

The following example URLs will omit the merchant part in the beginning, so...

/merchants/SHOP1/accounts/customers/

...will just be displayed as...

/accounts/customers/

The following examples apply to an account tree that looks like this:

Account Tree Visualization

Accounts can have subaccounts. Subaccounts are accounts also, therefore subaccounts can have subaccounts again. There is no conceptual limit of nesting accounts. The example on the right identifies the account with code cash of the parent account 87654321, which again has the parent account customers.

/accounts/customers/subaccounts/87654321/subaccounts/cash/

Any account (i.e., also subaccounts) can also be accessed by providing its longId instead of code. OPX Accounts will automatically detect whether a longId was provided. Both URLs in the example would identify the same account.

/accounts/customers/subaccounts/87654321/
==
/accounts/b1e9-3bb8-cbb8-4e5e/

If an account is identified by longId, its subaccounts can still be accessed by their code, but not by their longId.

/accounts/b1e9-3bb8-cbb8-4e5e/subaccounts/cash/
... is valid. This is invalid:
~~/accounts/b1e9-3bb8-cbb8-4e5e/subaccounts/c2a0-485dd-f5b5-4a80/~~

An account code is unique in the context of its parent account, but not neccessarily globally unique. It could be the code/number/id assigned by an external provider. Top level accounts (like customers in our example) also have unique codes among themselves in scope of their owner (i.e., the merchant). In the example 87654321 could be a customer number, and it will be a unique subaccount of the customers account. But in theory there could be another account with code 87654321 on a different level, which identifies a different account resource.

/accounts/customers/subaccounts/87654321/

/accounts/87654321/

An account can have alias codes. Providing an alias code in the resource URL is equivalent to providing the "main" code and will return the same result. Alias codes and "main" codes are all unique in the a scope of a parent account.

/accounts/customers/subaccounts/87654321/

/accounts/customers/subaccounts/john.doe.01/

An account can only have subaccounts with the same currency (identified by currencyCode).

/accounts/customers/
{"currencyCode": "EUR", ...}

<=>

/accounts/customers/subaccounts/87654321/
{"currencyCode": "EUR", ...}

An account can either contain Entries (Credits / Debits) or Subaccounts, but not both. As a consequence an Entry belongs to exactly one (sub)account that doesn't have further subaccounts. A subaccount cannot be created for an account that already has entries.

If this resource exists...

/accounts/customers/subaccounts/87654321/

...then this would return an empty result set:

/accounts/customers/entries/

The balance of an account with subaccounts is always the sum of the balances of its subaccounts.

/accounts/customers/subaccounts/87654321/
{"balance": 100, ...}

and

/accounts/customers/subaccounts/98765432/
{"balance": -20, ...}

/accounts/customers/
{"balance": 80, ...}

Account Tree Structures

Please sign in to view further details of this article. Login

Web Content Display

Advanced Operations

Filtering for accounts and conditional transaction execution are additional operations that are supported by OPX Accounts.

Advanced Operations

Filtering for accounts and conditional transaction execution are additional operations that are supported by OPX Accounts.

Please sign in to view further details of this article. Login

Web Content Display

Filtering Accounts

You can get a list of accounts or subaccounts filtered by their current balance, using the balance query parameter, a relational operator, and a value which may contain a minus to indicate negative values. See the full list with examples below.

The example on the right would return all customer accounts with a balance greater than 0.

Relational Operators

Operator code	Math syntax	Name	Example
eq	=	equal	.../subaccounts?balance=eq0
ne	?	not equal	.../subaccounts?balance=ne0
gt	>	greater than	.../subaccounts?balance=gt20
lt	<	less than	.../subaccounts?balance=lt-10
ge	?	greater than or equal to	.../subaccounts?balance=ge-500
le	?	less than or equal to	.../subaccounts?balance=le30

This operator syntax is based on https://en.wikipedia.org/wiki/Relational_operator#Standard_relational_operators

GET /merchants/SHOP1/accounts/customers/subaccounts?balance=gt0

Filtering Accounts

Please sign in to view further details of this article. Login

Web Content Display

Conditional Transactions

Transactions can be requested in a conditional way, meaning they should only be executed if the resultingBalance regarding the source account would fulfill the given statement after the transaction. This way you can, for example, ensure that an account's balance never gets negative (see example on the right). This is then guarateed by OPX Accounts according to the ACID principles, meaning you don't need to take care of race conditions and other adverse effects yourself.

The available relational operators are the same as for filtering accounts, see above.

POST /accounts/b1e9-3bb8-cbb8-4e5e/transactions?resultingBalance=ge0

Conditional Transactions

Please sign in to view further details of this article. Login