Analytics API
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"
}
Note
You can fetch up to one year of data.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
}
}
Note
A high granularity level in combination with a long date range may result in a too large data set. In this case you will receive a ‘bad request’ HTTP error (error code 400).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"
}
Note
You can fetch up to 4 dimensions.
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"
Note
Beware that filter values are case sensitive.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:
|
| 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 |