Using the Conditions Utility
Depending on your business requirements you might want to route payments in EUR down one path, and payments in USD down another. You can also create multiple routes based on other available data, from payment status down to individual e-mail addresses if you would want to.
The Conditions Utility enables you to create all these conditions.
Conditions are used to evaluate if a certain path should be followed during the execution of the workflow. They are based on selecting a field (for example: Currency), an operator (for example: equals), and a value (for example: EUR).
Available fields
Available fields for any condition depend on the Outputs from previous blocks. A condition can use information from any block upstream, like the amount and currency for a payment, or a link to a created ticket with Freshdesk.
Available operators
The available operators to evaluate a condition depend on the data type of the field.
Supported operators are:
| Operator | Description |
|---|---|
| Equal / not equal | The value passed in needs to be equal to or not equal to the value set up in the condition. |
| Greater than or equal / less than or equal | The value passed in needs to be greater than or equal to, or less than or equal to, the value set up in the condition. |
| One of | If multiple options are set up, either one will be accepted to follow the route for this condition. For example "Currency is one of EUR, GBP, USD" will evaluate to true for GBP, but not for NOK. |
| Not one of | If multiple options are set up, either one will be accepted to follow the route for this condition. For example "Currency is not one of EUR, GBP, USD" will follow NOK payments, but not EUR, GBP, or USD. |
| Between | evaluates if a numeric value is between two other values, for example ”is amount between 30 and 90”. ℹ️ the range is inclusive of the values entered. |
We plan to introduce additional operators over time.
Assign values
Values for the condition can either be entered manually (like e-mails) or select from a list of available values (like currencies or payment states), dependent on the data type of the selected field.
Using metadata for routing
One special type of conditions is based on unstructured data sent in via the metadata field attached to the Client Session when creating a payment. This field is used to send additional information with the payment outside of the available fields from the Payments API. This can also be used to attach information to create routes on, like custom risk scores or customer account status.
When using metadata for routing, make sure to specify the full path like in the example here.
1234567
"metadata": { "customObject": { "customField": "TEST" }, "accountStanding": "VIP", "internalRisk": "LOW",}
Condition evaluation
All conditions are evaluated together (AND) by default, meaning that if there are three conditions set up, like Amount>100, Currency=EUR, Payment Type=UNSCHEDULED, then all three need to be fulfilled for the path to be followed during workflow execution.
To avoid having to create too many routes based on specific conditions, you can also create groups of conditions by using the OR evaluation. In this example, a blocking route is created evaluating if a payment uses certain e-mail addresses or if a custom flag with the value "BLOCK" is sent in.
You can use multiple conditions in a group to achieve an outcome of (A AND B) **OR** (C) **OR** (D AND E) **OR** (F AND G AND H).
It is not possible to nest these groups further, but the ability to use trigger conditions, multiple condition builders, and multiple routes already gives you a lot of opportunity for complex branching.
Conditions are evaluated top down
Creating multiple sets of conditions is a great way to branch a workflow into multiple routes. Each block can have its own name, making it easier to keep track, as well as debug the workflow log.
When multiple sets are used, they are evaluated from top to bottom. In this example, first the conditions within the email block will be checked and if they match, that path will be taken. Otherwise, the conditions within “recurring payments” will be checked, and so on until the “all other conditions” block at the bottom is reached.
You need to put the most specific routes on top and getting more generic towards the bottom. If you create a route with “Currency=EUR” first and then a second one with “Currency=EUR AND Risk=high” below, then the second one will never be evaluated.
All other conditions
When the Conditions Utility is used within a workflow, then a fallback condition called “all other conditions” is always at the bottom. This could be used as an else path, creating a route that is set up more generic than the specialized routes above, or could also be left empty. If left empty and the Workflow Run reaches this condition, the workflow will still end with as the workflow ended without a failure.
Trigger Conditions define when to start a workflow
It is perfectly valid to have more than one published workflows based on the same trigger. However, if you want to start each workflow only in very specific cases, be sure to set up the Trigger accordingly.
If an event is sent that would trigger a workflow, but the conditions prevent that workflow from being started, then the workflow will neither run nor create a record in the Runs section, because the conditions do not apply.
Conditions within a workflow are evaluated top to bottom, but this logic does not apply to Triggers with Conditions as each workflow is evaluated independently.
Use explicitly
We recommend being very specific about how to use the Trigger Conditions to avoid unnecessarily starting unrelated workflows.
If there are two workflows for Cards & Klarna, they can have a triggering condition where for one the payment method is explicitly set to cards, and for the other it’s explicitly set to Klarna. Now each workflow only gets started, when the right payment method is used.
Best practices
Head over to the best practices guide to see our recommendations on how to use create granular flows based on distinct use cases.