Platform APIs

If you followed our setup and integration procedures, you'll already have made your acquaintance with the Payments API. The Payments API lies at the core of your integration, allowing you to invoke all required API calls for completing a payment flow.

As the Payments API becomes second nature to you, you might feel the urge to explore some additional capabilities of the PaymentsOS platform and implement functionalities hidden from the 'non-tech' admin's view. If so, make sure to explore our additional set of APIs that will get your developer heart beating just a tad faster:

  • Management API: Allows you to manage your PaymentsOS account and its configuration.

  • Reporting API: Allows you to generate reports, fetch report data, create a report schedule and more.

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

  • Audit API: allows you to fetch the history of the actions that a user performed in the system.

Let's explore each of these APIs in some more detail.

Management API

The Management API allows you to programmatically manage your PaymentsOS account. It does everything the Control Center UI does, but adds some capabilities that may come in handy depending on your business needs. Consider, for instance, a business model in which you provide a service that allows other merchants to accept payments (like in a marketplace). Using the Management API you can create a PaymentsOS account on behalf of each merchant, under the umbrella of your main account.

Check out the Management API reference for all the capabilities of the Management API.

Reporting API

The Reporting API provides endpoints for querying your payments history and extracting raw transaction data to a report in csv format. Extracting report data programmatically gives you some flexibility not available when creating a report through the Control Center UI. For instance, you can use the API to create a report schedule for generating reports on a scheduled basis.

A report is always based on a template, which has all the details in place for generating a report. Details include the report name, the columns you want to add to the report, the time period to use for the report and any filters you want to apply to the data when the report is generated.

At a high-level, creating a report is a two-step process:

  1. Create the report template.

  2. Create a report request. This submits a request to generate a report based on a specific report template.

Depending on the amount of data you are requesting, reports may take some time to generate. Reports are therefore generated asynchronously and you will be notified by mail when the data is available for download. You can specify the email address for notifications when creating the report template. If not specified, we will use the email address associated with the account of the user for whom the authentication session was created.

Maximum Number of Reports

You can generate up to 40 reports per day and fetch up to a year of data.

Filtering the Report Data

If you want to retrieve a subset of your data, you can do so by passing in a filters array in the template_data object of the Create a Report Template request. Here's an example:

{
  "template_data": {
    "columns": [
      {
        "column": "payment_status", // Exports the column payment_status to the .csv file
        "display_name": "Payment Status"
      },
      ...
    ],
    "filters": [
      {
        "column_name": "currency", // Places a filter on the currency column
        "filter_type": "equal",
        "filter_values": [
          "USD", "EUR" // Exports rows with a currency value of USD or EUR
        ]
      },
      {
        "column_name": "payment_status", // Places a filter on the payment_status column
        "filter_type": "equal",
        "filter_values": [
          "authorized" // Exports rows with a payment status of authorized
        ]
      }
    ],
    ...
  },
  ...

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

(currency == "USD" || "EURO") && (payment_status == "authorized")

There are three additional items to note:

  • You do not have to export the column to which you want to apply a filter. Notice that in our example above, we do not export the currency and payment_status columns (we only apply a filter to them).

  • Filter values must be valid values. A value is valid if it is applicable to the column to which the filter is applied. For instance, passing a filter value of waiting for the payment_status column will return an error since waiting is not a valid payment status. Depending on the filter you specify, the value must also be formatted correctly (a currency, for example, must always be a three character code in ISO-4217 format).

  • While you can apply a filter to data in any column, only the following columns have been optimized for querying: app_id, currency, country_by_ip_address, payment_method, provider_name, transaction_result_status and transaction_type. The report may take longer to generate if you apply data filters to other columns.

Some filters are self-explanatory and do not require much elaboration to be understood. Others, however, require that you follow specific guidelines to ensure you pass in valid filter values. We listed those guidelines in the table below.

Columns Guidelines
currency Must be a three character code in ISO-4217 format
  • transaction_amount
  • installments_first_payment_amount
  • installments_remaining_payments_amount
  • payment_amount
Must be formatted in minor units.
card_country_code Must be formatted in in ISO 3166-1 alpha-3 format.
  • card_type
  • card_issuer
  • card_level
Must be one of the values returned in the relevant field of the Create Token request.
payment_status Valid values: payment_initial, pending_three_d_secure, pending_charge, pending_authorization, authorized, captured, refunded, voided, aborted, initialized.
transaction_result_status Valid values: pending, succeed, failed, cancelled.
  • transaction_result_category
  • transaction_result_sub_category
For an overview of valid values, see Response Category and Response Sub-category in the Payments API Reference.
transaction_type Valid values: created, authorization, charge, capture, void, refund. Note: a transaction has a status of "created" when you invoke the Create Payment API request.
user_email A support agent can initiate a transaction request on behalf of a customer (using the Virtual Terminal or through the Payment Search functionality). The user_email is the email address of the agent who initiated the transaction request.

Analytics API

The Payments Analytics API allows you to fetch detailed statistics on the performance of the transactions passing through your account. It 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.

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:
  • 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

Audit API

Users with a PaymentsOS account can perform actions in the system, in accordance with the role(s) to which they belong. Actions include, for example, initiating a transaction through the Virtual Terminal, performing a payment search or generating a report. For auditing purposes, PaymentsOS tracks and stores the actions that a user performed. You can use the Audit API to retrieve those actions.

The following table lists the type of actions that PaymentsOS keeps tracks of. The action type is returned in the action_type field included in the response of the Retrieve Audit Data API request. For each action type, the table also lists the resource in which the action was created.

Action Type Description Created in Resource
activate_account The user activated the PaymentsOS account in order to gain access to their Live environment. activations
capture The user initiated a Capture request from a payment record returned through the results of a payment search. payment
charge The user charged a customer through the Virtual Terminal. payment
create_business_unit The user created a new Business Unit. app
create_customer The user created a new customer through the Virtual Terminal. customer
create_decision_engine_flow The user created a new Decision Engine flow. flow
create_payment The user initiated a transaction through the Virtual Terminal (under the hood, PaymentsOS creates a Payment Request). payment
create_payment_method The user used the Virtual Terminal to create a new payment method for a customer. payment_method
create_provider_configuration The user created a new provider configuration. processor_configuration
create_report_template The user created a report template. template
create_token The user initiated a transaction through the Virtual Terminal (under the hood, PaymentsOS creates a new Token Request). token
create_webhook_configuration The user created a new webhook configuration. webhook_configuration
deactivate_decision_engine_flow The user deactivated a Decision Engine flow by deleting all decision engine rules. flow
delete_webhook_configuration The user deleted a webhook configuration. webhook_configuration
generate_report The user generated a report. report
get_customer The user retrieved a customer's details through the Virtual Terminal. customer
get_payment The user viewed a payment record returned through the results of a payment search. payment
get_payment_methods The user retrieved a customer's payment methods through the Virtual Terminal. payment
invite_user The user invited another person to join the team on PaymentsOS. user
refund The user initiated a Refund request from a payment record returned through the results of a payment search. payment
replace_authentication_keys The user replaced the API authentication keys in a Business Unit's configuration settings. app
search_payments The user searched payment records using the payment search functionality. payment
update_business_unit The user updated a Business Unit's configuration settings. app
update_provider_configuration The user updated the provider configuration settings. processor_configuration
update_user_permissions The user changed another user's permissions by assigning that user to another role or Business Unit (or by removing that user from a role or Business Unit). user
update_webhook_configuration The user updated the webhook configuration settings. update_webhook_configuration
user_accepts_invite A person invited to join PaymentsOS accepted the invite. user
void The user initiated a Void request from a payment record returned through the results of a payment search. payment

results matching ""

    No results matching ""