Documentation
BETA

Payment method predicates

Learn how to display payment methods based on specific conditions.

With payment method predicates you can define the conditions for displaying a payment method in the checkout process. By setting predicates, you can tailor the availability of payment methods based on particular criteria, such as the cart amount or the customer group, to offer an optimized checkout experience to your customers.

Predicates are conditional statements with a specific syntax that operate on a true/false logic. If the predicate evaluates as true, the payment method is displayed. If it evaluates as false, the payment method is not displayed.

You can set payment method predicates when creating or editing an Application for both commercetools Checkout modes.

Predicate syntax

Payment method 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 method predicates operate on a true/false logic and they are evaluated against the values of the Cart fields, including Custom Fields.

If the predicate evaluates as true, the payment method is displayed among those available for the checkout. If it evaluates as false, the payment method is not displayed.

For example, if you set a predicate to display the PayPal payment method 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 method:

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 method.

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 method.

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

When a payment method is not displayed due to the predicate's conditions, it is replaced by the next eligible one, according to the order in the Application's settings Payment method via Connect tab.

To change the display order, when creating or editing an Application, click Reorder in the Payment method via Connect tab, then drag the payment methods into the desired order and click Save.

Predicate examples

Following are some examples of predicates that you can set to determine payment method conditions. If they evaluate as true, the payment method is displayed. If they evaluate as false, the payment method is not 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 a predicate for a payment method when:

  • Creating an Application: when adding the payment method, enter the text of the predicate in the Payment method conditions via predicates field in the Payment method via Connect tab.
  • Editing an Application: go to the Payment method via Connect tab, select the payment method, and enter the text of the predicate in the Payment method conditions via predicates field. Then, click Save.