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.

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:

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:

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

Transactions KPIs

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

Conversion KPIs

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

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.

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.

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:

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

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: 

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

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. 

API Endpoints: 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

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.

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.

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.

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.

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.

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

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.

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.

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.

Managing Report Types

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

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.