Web Content Display

KPI Analytics

KPI Analytics is a powerful API and frontend application (in the merchant portal) 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

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.

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

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.

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

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.

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

Transaction Analytics & 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 KPI 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 / My Customers from the portal to access the same data base manually through a graphical user interface, with the option to export.

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