Analytics API

The Analytics API allows you to fetch detailed statistics on the performance of the transactions passing through your account.

The Analytics API gives you the most flexible access to your payments information allowing you to create visualizations beyond the ones that come with the Control Center Dashboard. The following sections describe the structure of the request and response bodies, and provide examples of both.

API Reference

Click here to view the Analytics API Reference.

Implementation Details

The sections that follow provide some more information about using the Analytics API.

Request Structure

The Analytics API uses the POST HTTP method to access the Analytics resource. When constructing the Create Analytics Report POST request body, include the following:

  • The time range for which you want to fetch the data.

  • The time range granularity level (optional). This instructs the Analytics API to divide the time range into corresponding intervals when fetching the data.

  • The metrics you want to fetch. For example, the total number of payments in USD in the specified date range.

  • The dimensions you want to fetch (optional). For example, the type of transactions (authorization, charge, and so forth) that were initiated in the specified date range. The metrics you pass in will be grouped by the dimensions you specify.

  • A filter for fetching data that matches specific values only (optional).

Here is a sample request with the minimum required fields (refer to the examples for request bodies that include the other options as well):

{
   "time_range": {
      "from": "2018-12-14T22:00:00.000Z",
      "to": "2019-01-15T21:59:59.999Z"
   },
   "metrics": [
      {
         "name": "total_payments"
      },
      {
            "name":"total_amount_usd"
      }
   ],
   "view": "payments"
}

Response Structure

The API request returns the analytics data in a buckets array of objects. Here is a sample response for the sample request above:

{
    "buckets": [
        {
            "time_range": {
                "from": "2018-12-14T22:00:00.000Z",
                "to": "2019-01-15T21:59:59.999Z"
            },
            "data": [
                {
                    "metrics": {
                        "total_payments": 126,
                        "total_amount_usd": 700
                    }
                }
            ]
        }
    ],
    "metadata": {
        "total_records": 1
    }
}

Notice that each object in the buckets array includes a time_range object showing the date range to which the data applies, as well as a data array of objects that show the data itself. The number of objects in the buckets array will vary, depending on your time granularity level (if passed in the request). Likewise, the number of objects in the data array will vary, depending on whether you passed in any dimensions in your request. We will take a look at some examples in the section that follows.

Examples

We already saw an example of a basic request with required fields only, and the response it returns. Let’s build upon that basic example to create some more advanced requests.

Time Range Granularity Level

Along with the time range, you can pass in a time range granularity level as well. If you do so, the Create Analytics Report request will divide the time range into corresponding intervals when fetching the data. Here’s a sample request body for a time range with a granularity level of one day:

{
  "time_range": {
    "from": "2018-12-14T22:00:00.000Z",
    "to": "2019-01-15T21:59:59.999Z",
    "granularity": "day" // We added a granularity level
  },
  "metrics": [
    {
      "name": "total_payments"
    },
    {
       "name":"total_amount_usd"
    }
  ],
  "view": "payments"
}

Here’s a sample response body. Notice that the buckets array now includes multiple objects, one for each day in the specified time range (truncated for brevity).

{
    "buckets": [
        { // day 1
            "time_range": {
                "from": "2018-12-16T00:00:00.000Z",
                "to": "2018-12-17T00:00:00.000Z"
            },
            "data": [
                {
                    "metrics": {
                        "total_payments": 30,
                        "total_amount_usd": 200
                    }
                }
            ]
        },
        {
            "time_range": { // day 2
                "from": "2018-12-17T00:00:00.000Z",
                "to": "2018-12-18T00:00:00.000Z"
            },
            "data": [
                {
                    "metrics": {
                        "total_payments": 51,
                        "total_amount_usd": 100
                    }
                }
            ]
        }
      ... // Objects for additional days
    ],
    "metadata": {
        "total_records": 8
    }
}

Dimensions

Dimensions are characteristics of your data that add an extra “dimension” to your metrics. The action_type dimension, for example, represents the type of transactions (authorization, charge, and so forth) that were initiated in the specified date range. If we were to combine it with the total_payments and total_amount_usd metrics, then your analytics report will show both the total value in USD per transaction type and the total number of payments per transaction type. Here’s a sample request:

{
   "time_range":{
      "from":"2018-12-14T22:00:00.000Z",
      "to":"2019-01-15T21:59:59.999Z",
      "granularity":"day"
   },
   "metrics":[
      {
         "name":"total_payments"
      },
       {
         "name":"total_amount_usd"
      }
   ],
   "dimensions":[
      "action_type" // Let's add in a dimension
   ],
   "view":"payments"
}

The response body will look like this (notice how the data object now includes multiple objects, one for each dimension value):

{
    "buckets": [
        {
            "time_range": {
                "from": "2018-12-16T00:00:00.000Z",
                "to": "2018-12-17T00:00:00.000Z"
            },
            "data": [
                {
                    "dimensions": {
                        "action_type": "payment_initial"
                    },
                    "metrics": {
                        "total_payments": 13,
                        "total_amount_usd": 200
                    }
                },
                {
                    "dimensions": {
                        "action_type": "authorization"
                    },
                    "metrics": {
                        "total_payments": 5,
                        "total_amount_usd": 10
                    }
                },
                {
                    "dimensions": {
                        "action_type": "capture"
                    },
                    "metrics": {
                        "total_payments": 4,
                        "total_amount_usd": 34
                    }
                },
                {
                    "dimensions": {
                        "action_type": "charge"
                    },
                    "metrics": {
                        "total_payments": 4,
                        "total_amount_usd": 44
                    }
                },
                {
                    "dimensions": {
                        "action_type": "refund"
                    },
                    "metrics": {
                        "total_payments": 2
                    }
                },
                {
                    "dimensions": {
                        "action_type": "void"
                    },
                    "metrics": {
                        "total_payments": 2,
                        "total_amount_usd": 89
                    }
                }
            ]
        },
        ... // Additional objects, depending on the time range granularity level
    ],
    "metadata": {
        "total_records": 8
    }
}

See Dimension and Filter Values for an explanation of the dimensions you can fetch.

Multiple Dimensions

Of course, you can also pass in multiple dimensions in the request body’s dimensions array. In this case, the response will aggregate the metrics by the dimension values. For example, if we were to add the action_status (the status of each request type) dimension to our previous request example, then the response data would look like the one below. Notice that the data object will include additional objects, one for each available combination of action_type and action_status (in the sample response below, an object has been added for each authorization and ‘capture’ with a status failed, in addition to each authorization and capture with a status of succeed):

{
            "time_range": {
                "from": "2018-12-16T00:00:00.000Z",
                "to": "2018-12-17T00:00:00.000Z"
            },
            "data": [
                {
                    "dimensions": {
                        "action_type": "authorization",
                        "action_status": "succeed"
                    },
                    "metrics": {
                        "total_payments": 5,
                        "total_amount_usd": 50
                    }
                },
                {
                    "dimensions": {
                        "action_type": "authorization",
                        "action_status": "failed"
                    },
                    "metrics": {
                        "total_payments": 3,
                        "total_amount_usd": 90
                    }
                },
                {
                    "dimensions": {
                        "action_type": "capture",
                        "action_status": "failed"
                    },
                    "metrics": {
                        "total_payments": 2,
                        "total_amount_usd": 20
                    }
                },
                {
                    "dimensions": {
                        "action_type": "capture",
                        "action_status": "succeed"
                    },
                    "metrics": {
                        "total_payments": 2,
                        "total_amount_usd": 15
                    }
                },
                ...
            ]
        },
        ... // Additional objects, depending on the time range granularity level
    ],
    "metadata": {
        "total_records": 8
    }
}

Filters

Sometimes you want to fetch data that matches specific values only. You can do this by applying a filter to one or more dimensions. Here’s a sample request body:

 {
   "time_range":{
      "from":"2018-12-14T22:00:00.000Z",
      "to":"2019-01-15T21:59:59.999Z",
      "granularity":"day"
   },
   "metrics":[
      {
         "name":"total_payments"
      }
   ],
   "dimensions":[
      "action_type",
      "action_status"
   ],
   "filters": [
    {
      "dimension": "currency",
      "values": [
        "USD","EURO"
      ]
    },
    {
      "dimension": "provider_name",
      "values": [
        "PayPal"
      ]
    }
  ],
   "view":"payments"
}

The filer logic applies the AND operator between multiple filter values and between multiple filter objects. In the example above, this will result in the following filter:

(currency == "USD" && "EUR") && provider_name == "PayPal"

See Dimension and Filter Values below, for an explanation of the dimensions you can use for filtering your data.

Dimension and Filter Values

The following table lists the dimensions you can fetch, including an explanation of each dimension. These dimensions can also be passed in the filter array (see Filters above).

Dimension Description
payment_stage The stage of a transaction in the payment flow. This can be one of the following values:
  • successful: Transactions that have been successfully charged.
  • declined: Transactions declined by the providers you are transacting against.
  • initiated: Payments initiated in PaymentsOS.
  • refund: Transactions successfully refunded to your customers.
  • voided: Transactions that have been cancelled before execution.
  • blocked: Transactions that were blocked by the Decision Engine.
currency A three character currency code in ISO-4217 format.
country A country code in ISO 3166-1 alpha-3 format.
provider_name The name of the provider handling the transaction requests.
application_name The identifier of the business unit invoking the transaction requests.
payment_method_type The payment method type. For example, BankTransfer or CreditCard
action_type The type of transaction request that was invoked. Can be one of the following values: authorization, void, payment_initial, capture, refund, charge, three_d_secure
action_status The transaction status. Can be one of the following values: succeed, pending, failed, canceled. For more information, see Payment Status vs Transaction Status.
card_level The credit card level. For example, PREPAID or CLASSIC.
vendor The vendor of the credit card.
card_type The type of card.
card_issuer The name of the bank that issued the card.
card_country_code The country where the credit card was issued. The country code is in ISO 3166-1 alpha-3 format.
error_category The category classifying the transaction request error if one occurred. For more information, see Response Category in the Payments API Reference.
error_sub_category The sub-category classifying the transaction request error if one occurred. For more information, see Response Sub-category in the Payments API Reference.
provider_response_code The response code returned by the provider.
provider_response_description A description returned by the provider in response to a transaction request.
provider_configuration_id The identifier of the provider configuration defined in your Control Center account.
event_type Indicates whether the transaction resource was created or updated. For example: payment.capture.update
Last modified April 29, 2024