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.

Trigger List

To view and manage an inbox-style list of all your existing triggers, click Triggers in the navigation bar. When you click on a trigger in the Trigger List, a Trigger Details side panel opens containing all the fields configured to generate that trigger.

From the Trigger List, you can configure new triggers, and disable or delete existing triggers.

Configuring Triggers

To configure a trigger in Canary:

  1. Open the Canary Service Panel, then click Triggers.
  2. Click + Add Trigger.
  3. Give your trigger a Name 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. Narrow down your trigger threshold by applying up to two 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
  • Approved Count - The total number of approved transactions in a given time period
  • 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
  • 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
  • Decline Rate - The percentage of total attempted transactions declined; calculated by dividing the total number of declines by the total number of transactions
  • 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 Amount - The total amount of funds refunded to customers in a given time period
  • Refund Count - The total number of refunds processed 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 refunds processed by the total number of transactions
  • Total Processed Volume - The total volume of all transactions processed in a given time period
  • Transaction Count - The total number of transactions processed in a given time period
  • Transaction Count Velocity - The period-over-period change of transaction count

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.

Trigger Filters

When you configure a trigger in Canary, you have the option of adding Filters. Filters tell Canary what specific segments of your transaction data to monitor.

To apply filters to a trigger:

  1. Under Filters in the Trigger Configuration panel, click +Add Filter(s).
  2. Select a filter option from the drop-down menu.
  3. Click the checkbox beside the parameter(s) you want to filter your data by. To create a trigger that monitors each parameter of that filter separately, click the checkbox beside All. Learn more about the implications of selecting more than one parameter in the section below.
  4. Click Apply.
  5. To add a second filter, click Edit Filter(s), then repeat the steps to select a filter option and the desired parameters. At this time, you can only apply up to two filters to a Canary trigger.
  6. (Optional) To clear the parameters selected for a filter option, click the X beside the filter name. To change out a filter option, click Edit Filter(s), then click the filter name to remove it from your trigger; you can then select a different option.

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:

  • Metric: Authorization Rate
  • Filter: Stored Credential
  • Selected filter parameter: recurring

Filter Options

You can apply up to two of the following filter options to a Canary trigger:

  • AVS Line Code
  • AVS Post Code
  • BIN
  • Card Brand
  • Card Type
  • Currency
  • CVV
  • Decline Code - Keep in mind, the decline code filter only functions for triggers with a selected Metric that includes declined transaction data (e.g. Transaction Count, Transaction Count Velocity, Average Order Value, and Total Processed Volume)
  • Issuer Country
  • Issuing Bank
  • Processor
  • Soft Descriptor
  • Stored Credential

Filtering Triggers by More Than One Parameter

When you apply a Filter to a trigger and select more than one—or All—parameters available for the chosen filter option, Canary effectively creates a different trigger for each segment of your transaction data associated with those parameters. For example, imagine you created a simple threshold trigger to alert you if your approval rate drops below 95% and you applied the Card Brand filter with both the Visa and Mastercard parameters selected; you’d then receive a separate alert when your Visa card approval rate dropped below 95% as you would when the same happens to your Mastercard approval rate.

For relative threshold triggers, Canary calculates a different threshold range for every parameter variable in the chosen filter option. 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 that’s filtered by Currency with All parameters checked, 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.

🚧

Note:

With the BIN, Currency, Issuing Bank, Soft Descriptor, and Issuing Country filters, you can only select up to 12 parameters for a trigger.

Disabling and Deleting Triggers

You can disable or delete a trigger at any time.

When you disable a trigger, Canary stops generating events based on that trigger's configuration until you enable it again. To do so, click the trigger in the Trigger List to open the Trigger Details side panel; beside Status, click the toggle to disable the trigger.

To completely delete a trigger, click the trigger in the Trigger List, then click the trash icon and click Remove to confirm.


What’s Next