Documentation
BETA

Payment predicates

Learn how to use Payment predicates for Payment Integrations and Automated Reversals.

Predicates are conditional statements with a specific syntax that operate on a true/false logic.
You can set Payment predicates when creating or editing an Application for both Checkout modes.

Payment predicates are categorized into two types:

  • Payment Integration predicates: You can use Payment Integration predicates to define the conditions for displaying Payment Integrations in the checkout process. By setting predicates, you can tailor the availability of Payment Integrations based on specific criteria, such as the Cart amount or the Customer Group, to offer an optimized checkout experience to your customers.
  • Automated Reversal predicates: You can use Automated Reversal predicates to define the conditions for automatically canceling or refunding a Payment if the Order-creation process fails.
You can set Payment predicates only for Payment Integrations that are rendered via the web components Payment Integration Type.

Predicate syntax

Payment predicates follow the JSONata query syntax and consist of the following elements:
  • Predicate field identifiers, which can reference all fields of a Cart.
  • Operators, which create logical comparisons between values.
  • Values, which are data to compare with the values of the Cart fields.

For example, let's see this predicate:

billingAddress.country = "DE"

In this example:

  • The predicate field identifier is billingAddress.country.
  • The operator is =.
  • The value is "DE".

In plain English the predicate reads: The country of the billing address is Germany.

You can also combine conditions within a predicate using either the and or or operators, as in the following example:
customerGroup.id = "aef9cf41-94ad-4794-8122-62d308900430" and billingAddress.country = "DE"
In plain English, the predicate reads: The ID of the customer group is aef9cf41-94ad-4794-8122-62d308900430 and the country of the billing address is Germany.

Predicate logic

Payment predicates operate on a true/false logic, and they are evaluated against the values of Cart fields, including Custom Fields.

Automated Reversal predicates

If the Automated Reversal predicate evaluates as true, the Automated Reversal is processed for the relevant payment. If it evaluates as false, the Automated Reversal is not processed for the relevant payment.

Payment integration predicates

If the Payment integration predicate evaluates as true, the Payment Integration is displayed among those available for the checkout. If it evaluates as false, the Payment Integration is not displayed.

For example, if you set a predicate to display the PayPal Payment Integration when the total price of the cart is greater than or equal to 100 Euro, then the predicate is evaluated in one of the following ways:

  • The total amount of the cart is 120 Euro, so PayPal is displayed.
  • The total amount of the cart is 90 Euro, so PayPal is not displayed.

Now let's look at this example from a technical point of view. The following is the predicate you set to determine the condition for the PayPal Payment Integration:

totalPrice.centAmount >= 10000 and totalPrice.currencyCode = "EUR"
If, for the totalPrice field of the current Cart, the value of the centAmount field is 12000 and the value of the currencyCode field is "EUR", PayPal is displayed as a Payment Integration.
If, for the totalPrice field of the current Cart, the value of the centAmount field is 9000 and the value of the currencyCode field is "EUR", PayPal is not displayed as a Payment Integration.

Payment predicates do not affect the order in which Payment Integrations are displayed. For example, it is not possible to set a predicate to display credit card as the first Payment Integration if the country is Germany and as the second Payment Integration if the country is Italy.

When a Payment is not displayed due to the predicate's conditions, it is replaced by the next eligible one according to the order of the Application's settings in the Payment integrations tab.
To change the display order, when creating or editing an Application, click Reorder in the Payment integrations tab, then drag the Payment Integration into the desired order and click Save.

Predicate examples

Here are a few examples of predicates that you can set to determine Payment Integration conditions. If the predicates evaluate as true, the Payment Integration is displayed.

This predicate checks that the country of the billing address for the Cart is Germany:
billingAddress.country = "DE"

This predicate checks that the country of the billing address for the Cart is not Germany:

billingAddress.country != "DE"

This predicate checks that the amount of the total price of the Cart is greater than or equal to 100 and less than 200, and that the currency is Euro:

totalPrice.centAmount >= 10000 and totalPrice.centAmount < 20000 and totalPrice.currencyCode = "EUR"
This predicate checks that the Product Type id of the Line Items in the Cart is c2f93298-c967-44af-8c2a-d2220bf39eb2 or 67751a034a-8691-4a4d-b7be-2f959cb4b65c890:
lineItems.productType.id = "c2f93298-c967-44af-8c2a-d2220bf39eb2" or lineItems.productType.id = "751a034a-8691-4a4d-b7be-2f959cb4b65c"
This predicate checks that the Customer Group id of the Customer to which the Cart belongs is aef9cf41-94ad-4794-8122-62d308900430 or 266f3f1c-d86e-4376-94ec-b41d657040ae:
customerGroup.id = "aef9cf41-94ad-4794-8122-62d308900430" or customerGroup.id = "266f3f1c-d86e-4376-94ec-b41d657040ae"
This predicate checks that the Customer Group id of the Customer to which the Cart belongs is not c2f93298-c967-44af-8c2a-d2220bf39eb2:
customerGroup.id != "c2f93298-c967-44af-8c2a-d2220bf39eb2"

This predicate checks that the Cart contains at least one Line Item:

$sum(lineItems.quantity) = 1
This predicate checks that the Customer Group of the Customer to which the Cart belongs is aef9cf41-94ad-4794-8122-62d308900430 and that the country of the shipping address is The Netherlands or Germany:
customerGroup.id = "aef9cf41-94ad-4794-8122-62d308900430" and (shippingAddress.country = "NL" or shippingAddress.country = "DE")
This predicate checks that the id of the Shipping Method for the Cart is not eb8991df-2dcd-4e24-83fe-5df46ec04422:
shippingInfo.shippingMethod.id != "eb8991df-2dcd-4e24-83fe-5df46ec04422"

Set predicates

You can set predicates when creating or editing an Application.

Set predicates for Payment integrations

  • To set a predicate when creating an Application: when adding the Payment Integration, enter the text of the predicate in the Payment integration conditions via predicates field of the Payment integrations tab.
  • To set a predicate when editing an Application: go to the Payment integrations tab, select the Payment Integration, and enter the text of the predicate in the Payment integration conditions via predicates field. Then, click Save.

Set predicates for Automated Reversals

To set a predicate when creating an Application, do the following:

  1. When adding the Payment Integration, click the Automated reversal toggle to activate Automated Reversals.
  2. Click Add condition.
  3. Enter the relevant predicates.

To set a predicate when editing an Application:

  1. Go to the Payment integrations tab, and then select the Payment Integration.
  2. Click the Automated reversal toggle to activate Automated Reversals.
  3. Click Add condition.
  4. Enter the relevant predicates.
  5. Click Save.