Behind every event in Canary by Pagos is a trigger that defines when a particular metric warrants attention. In other words, you configure a trigger and when your data "trips" that trigger, Canary registers an event and notifies you of the change. You can create triggers that alert you of changes to your full data set or just specific segments of data; for example, a trigger can alert you when your aggregate approval rate decreases below a specific value, or when only your approval rate for French banks drops unexpectedly.

Configuring Triggers

To configure a trigger in Canary:

  1. Open the Canary Service Panel, then click Triggers.
  2. Click + Add.
  3. Give your trigger a Title and Description.
  4. Select the Metric you want to monitor from the drop-down menu.
  5. Define the Frequency by which you want Canary to review the metric and search for an event (Hourly or Daily).
  6. Select a Trigger Time:
    1. If you set the trigger Frequency to Daily, this is the time each day (in the time zone specified in your account settings) when Canary reviews the metric and searches for an event.
    2. If you set the trigger Frequency to Hourly, you can choose which hours of each day you want Canary to review the metric. Check All to have Canary search for events every hour of the day (this is the default option), or check only the specific hours when you want Canary to search for events. When you've made your selections, click Apply.
  7. Select the Threshold Type.
  8. (Optional) Narrow down your trigger threshold by setting Groups and Filters.
  9. If you chose Simple for your Threshold Type:
    1. Set a Direction for your trigger. This tells Canary if it should alert you when your metric crosses Above the threshold or Below it.
    2. Set the Threshold. This is the exact value of the threshold trigger for the chosen metric.
  10. If you chose Relative for your Threshold Type:
    1. Set a Direction for your trigger. This tells Canary if it should alert you when your metric crosses Above where 95% of your historical data sits or Below it.
    2. Set a Lookback Window. This is the number of days included in the time period Canary uses to calculate the threshold range of the relative trigger.

Canary Metrics

At this time, you can set up triggers in Canary for the following metrics:

  • Approval Rate - The percentage of transactions processed that were ultimately approved; calculated by dividing by the total number of approved transactions by the total number of attempted transactions within a given time period
  • Refund Amount - The total amount of funds refunded to customers in a given time period
  • Refund Rate - The percentage of total transactions refunded in a given time period; calculated by dividing the total number of transactions by the total number of refunds processed
  • Chargeback Rate - The percentage of transactions processed that ended in a chargeback; calculated by dividing the total number of transactions processed in a given time period by the total number of chargebacks received
  • Average Order Value - The average amount of money each customer spends per transaction; calculated by dividing the total revenue received by the total number of orders processed in a given time period
  • Transaction Count - The total number of transactions processed in a given time period
  • Transaction Count Velocity
  • Approved Count - The total number of approved transactions in a given time period
  • Total Processed Volume - The total volume of all transactions processed in a given time period
  • Disputed Count - The total number of disputed transactions in a given time period
  • Disputed Volume - The total volume of all disputed transactions in a given time period
  • Refund Count - The total number of refunds processed in a given time period

Threshold Types

Canary has two types of thresholds:

  • Simple – A simple threshold detects when your data exceeds a specific minimum or maximum acceptable value. You can customize the threshold value and specify whether you want Canary to notify you if the your data falls above or below that exact value.
  • Relative – A relative threshold detects when your data deviates from your historical average. Canary calculates a threshold range based on where 95% of your historical data sits in the time period specified by your chosen Look back window, and notifies you when your data drops above or below that range.

Choosing a threshold type

How you choose a threshold type—simple or relative—depends on how you and your organization think about your data. The simple threshold is a great option if you already know what good performance looks like and you've established specific KPIs for your business. Similarly, if you have a hypothesis about what data values are “normal” for your business, you can use simple thresholds to track and test that theory.

Relative thresholds are great if you don’t want a noisy trigger from Canary; with a relative threshold, you’ll only receive Canary notifications about 5% of the time. They're also helpful when you don't yet know what "normal" looks like in your data. In due time, a relative threshold will identify what data values to expect and what can be considered out of the ordinary (and worth investigating).

🚧

Tip Regarding Relative Thresholds:

If there is a major change to operations or your payment stack that creates durable changes in your metrics, you'll likely need to create a new relative threshold.

You may need both types of thresholds—you're not limited to just one! For example, if you already have a well-established KPI for Approval Rate, set a simple threshold trigger for that metric. Then, if you're just starting to monitor your Average Order Value (AOV), create a relative threshold for AOV to identify trends in your data. The combinations and possibilities are near-endless and customizable to your business needs.

Groups, Sub Groups, and Filters

By assigning a Group and Sub Group to a trigger, you can tell Canary what specific segments of your transaction data you want to monitor. You can apply the following Groups (and Sub Groups) to a trigger:

After you select a Group and Sub Group, you can segment the data further by setting specific Filter and Sub Filter values. These fields are helpful when you want to exclude certain data in a Group from your trigger monitoring. For all Group (and Sub Group) selections except for BIN and Issuing Bank, these fields are optional.

When you click the Filter (or Sub Filter) field, a menu appears with all the variables available in your data for the chosen Group (or Sub Group); select one or more of the variables, then click Apply.

For example, if you wanted to create a trigger that monitors authorization rates for only recurring transactions, you could set the following parameters when configuring your new trigger:

Groups and Relative Threshold Triggers

When you select a Group for a relative threshold trigger but don't apply a Filter, Canary calculates a different threshold range for every filter variable in that group. For example, if your company processes transactions in three currencies (e.g. USD, CAD, and EUR), and you configure a relative threshold trigger for transaction count grouped by currency, Canary will establish a threshold range for USD, CAD, and EUR transactions separately. You'll then receive an alert every time your USD transaction count drops below the expected range for transactions made in USD; the same is true for CAD and EUR transactions.


Did this page help you?