Payment Option Rules

Payment option rules determine whether a payment option is available to a user during checkout. Each rule evaluates the current state of the pre-order (basket, user, shipping, etc.) and either passes or raises an exception.

Rules are configured in the config.rule field of a Payment Option using JSON. The klass field specifies the rule class and params contains the rule's parameters.

{
  "rule": {
    "klass": "omnishop.payments.rules.RuleClassName",
    "params": {
      "error_level": "soft",
      "error_message": "This payment option is not available."
    }
  }
}

Common Parameters

All rules accept the following optional parameters:

Parameter	Type	Default	Description
error_level	string	"hard"	"soft" shows the payment option as unavailable with an error message. "hard" hides it completely.
error_message	string or object	""	Error message shown when error_level is "soft". Can be a plain string or a localized object keyed by language code (e.g. {"tr": "...", "en": "..."}).
error_code	string	"00"	A code to identify the error.

---

Composite Rules

Composite rules allow combining multiple rules with logical operators.

AndRule

The payment option is available only if all child rules pass.

{
  "klass": "omnishop.payments.rules.AndRule",
  "params": {
    "error_level": "soft",
    "error_message": "This payment option is not available.",
    "children": [
      {
        "klass": "omnishop.payments.rules.RuleA",
        "params": {}
      },
      {
        "klass": "omnishop.payments.rules.RuleB",
        "params": {}
      }
    ]
  }
}

Parameter	Type	Required	Description
children	array	Yes	List of child rule objects, each with klass and params.
error_level	string	No	If set, overrides child error levels and forces a unified exception.

OrRule

The payment option is available if at least one child rule passes.

{
  "klass": "omnishop.payments.rules.OrRule",
  "params": {
    "error_level": "hard",
    "children": [
      {
        "klass": "omnishop.payments.rules.RuleA",
        "params": {}
      },
      {
        "klass": "omnishop.payments.rules.RuleB",
        "params": {}
      }
    ]
  }
}

Parameter	Type	Required	Description
children	array	Yes	List of child rule objects, each with klass and params.

NotRule

Inverts a child rule. The payment option is available if the child rule fails.

{
  "klass": "omnishop.payments.rules.NotRule",
  "params": {
    "child": {
      "klass": "omnishop.payments.rules.RegisteredUserRule",
      "params": {}
    }
  }
}

Parameter	Type	Required	Description
child	object	Yes	A single rule object with klass and params.

---

Basket Rules

BasketAmountRule

The payment option is available only if the discounted basket total is greater than or equal to min_total_amount.

{
  "klass": "omnishop.payments.rules.BasketAmountRule",
  "params": {
    "min_total_amount": "500.00"
  }
}

Parameter	Type	Required	Description
min_total_amount	string	Yes	Minimum discounted basket amount.

TotalProductAmountRule

The payment option is available only if the undiscounted basket total is greater than or equal to min_total_amount.

{
  "klass": "omnishop.payments.rules.TotalProductAmountRule",
  "params": {
    "min_total_amount": "500.00"
  }
}

Parameter	Type	Required	Description
min_total_amount	string	Yes	Minimum undiscounted basket amount.

BasketProductSkuRule

The payment option is not available if the basket contains a product with the specified SKU.

{
  "klass": "omnishop.payments.rules.BasketProductSkuRule",
  "params": {
    "sku": "PRODUCT-SKU-123"
  }
}

Parameter	Type	Required	Description
sku	string	Yes	The SKU of the product that should not be in the basket.

BasketProductsHasAttributeRule

The payment option is available only if basket products have the specified attribute key.

{
  "klass": "omnishop.payments.rules.BasketProductsHasAttributeRule",
  "params": {
    "attribute_key": "is_digital",
    "mode": "all"
  }
}

To require at least one product to have the attribute:

{
  "klass": "omnishop.payments.rules.BasketProductsHasAttributeRule",
  "params": {
    "attribute_key": "is_digital",
    "mode": "any"
  }
}

Parameter	Type	Required	Description
attribute_key	string	Yes	The product attribute key to check.
mode	string	No	"all" (default): all products must have the attribute. "any": at least one product must have the attribute.

BasketProductsAttributeRule

The payment option is available only if basket products have the specified attribute key with the specified value.

{
  "klass": "omnishop.payments.rules.BasketProductsAttributeRule",
  "params": {
    "attribute_key": "product_type",
    "attribute_value": "digital",
    "mode": "all"
  }
}

Parameter	Type	Required	Description
attribute_key	string	Yes	The product attribute key to check.
attribute_value	any	Yes	The expected value for the attribute.
mode	string	No	"all" (default): all products must match the attribute value. "any": at least one product must match the attribute value.

BasketHasTradableItemRule

The payment option is available only if the basket contains at least one tradable item. No parameters required.

{
  "klass": "omnishop.payments.rules.BasketHasTradableItemRule",
  "params": {}
}

---

User Rules

LoginRequiredRule

The payment option is available only if the user is logged in. No parameters required.

{
  "klass": "omnishop.payments.rules.LoginRequiredRule",
  "params": {}
}

RegisteredUserRule

The payment option is available only if the user is a registered (non-guest) user. No parameters required.

{
  "klass": "omnishop.payments.rules.RegisteredUserRule",
  "params": {}
}

UserRegisteredAndHasValidPhoneNumberRule

The payment option is available only if the user is registered and has a valid phone number. No parameters required.

{
  "klass": "omnishop.payments.rules.UserRegisteredAndHasValidPhoneNumberRule",
  "params": {}
}

SavedCreditCardRule

The payment option is available only if the user is logged in and has at least one saved credit card.

{
  "klass": "omnishop.payments.rules.SavedCreditCardRule",
  "params": {
    "filter_by_pos": false
  }
}

Parameter	Type	Required	Description
filter_by_pos	boolean	No	If true, checks only for saved cards associated with the payment option's POS. Defaults to false.

StoredCardRequiredRule

The payment option is available only if the user is logged in and has stored cards in the configured POS gateway. No parameters required.

{
  "klass": "omnishop.payments.rules.StoredCardRequiredRule",
  "params": {}
}

---

Shipping Rules

PayOnDeliveryRule

The payment option is available only if the selected shipping option's slug is in the allowed list.

{
  "klass": "omnishop.payments.rules.PayOnDeliveryRule",
  "params": {
    "available_shipping_options": ["standard-delivery", "express-delivery"]
  }
}

Parameter	Type	Required	Description
available_shipping_options	array	Yes	List of allowed shipping option slugs.

ShippingCityRule

The payment option is available based on the city of the shipping address.

{
  "klass": "omnishop.payments.rules.ShippingCityRule",
  "params": {
    "cities": [1, 2, 3],
    "exclude": false
  }
}

Parameter	Type	Required	Description
cities	array	Yes	List of city IDs.
exclude	boolean	No	If false (default), the payment option is available only for listed cities. If true, it is available for all cities except the listed ones.

ShippingOptionRule

The payment option is available only if the selected shipping option matches the specified name or slug.

{
  "klass": "omnishop.payments.rules.ShippingOptionRule",
  "params": {
    "slug": "standard-delivery"
  }
}

Parameter	Type	Required	Description
name	string	No*	Shipping option name to match.
slug	string	No*	Shipping option slug to match.

* At least one of name or slug must be provided.

ShippingOptionPageRule

The payment option is available only if the active checkout shipping option selection page matches the specified page type. Useful when certain payment options should only appear on specific checkout flows.

{
  "klass": "omnishop.payments.rules.ShippingOptionPageRule",
  "params": {
    "page": "DataSourceShippingOptionSelectionPage"
  }
}

Parameter	Type	Required	Description
page	string	No	The checkout shipping page type to match. Defaults to "ShippingOptionSelectionPage". Available values: "ShippingOptionSelectionPage", "DataSourceShippingOptionSelectionPage", "AttributeBasedShippingOptionSelectionPage", "RemoteShippingOptionSelectionPage".

RetailStoreStockRule

The payment option is available only if retail store stock is confirmed for the basket items based on the shipping address location.

{
  "klass": "omnishop.payments.rules.RetailStoreStockRule",
  "params": {
    "use_city": true,
    "use_township": true,
    "use_county": false,
    "use_district": false,
    "extra_params": {}
  }
}

Parameter	Type	Required	Description
use_city	boolean	No	Use the city from the shipping address as a tag. Defaults to false.
use_township	boolean	No	Use the township from the shipping address as a tag. Defaults to false.
use_county	boolean	No	Use the county from the shipping address as a tag. Defaults to false.
use_district	boolean	No	Use the district from the shipping address as a tag. Defaults to false.
extra_params	object	No	Additional parameters passed to the stock control service.

---

Order Rules

OnlyOnePayOnDeliveryRule

The payment option is available only if the user has no active pay-on-delivery orders. Prevents multiple concurrent cash-on-delivery orders. No parameters required.

{
  "klass": "omnishop.payments.rules.OnlyOnePayOnDeliveryRule",
  "params": {}
}

RecentOrderCountLimitRule

Limits usage based on the user's order count within the specified time period. The payment option is unavailable if the user has placed max_order_count or more orders in the last period_hours hours.

Orders with cancelled, refunded, or merged statuses are excluded from the count.

{
  "klass": "omnishop.payments.rules.RecentOrderCountLimitRule",
  "params": {
    "max_order_count": 5,
    "period_hours": 24,
    "use_same_payment_option": false
  }
}

Parameter	Type	Required	Description
max_order_count	integer	Yes	Maximum number of orders allowed within the period.
period_hours	integer	Yes	The time window in hours to look back (e.g. 24 for daily, 168 for weekly).
use_same_payment_option	boolean	No	If true, only orders placed with the same payment option are counted. Defaults to false.

RecentOrderAmountLimitRule

Limits usage based on the user's total order amount within the specified time period. The payment option is unavailable if the user's total order amount reaches or exceeds max_total_order_amount in the last period_hours hours.

Orders with cancelled, refunded, or merged statuses are excluded from the total.

{
  "klass": "omnishop.payments.rules.RecentOrderAmountLimitRule",
  "params": {
    "max_total_order_amount": "200000.00",
    "period_hours": 48,
    "use_same_payment_option": false
  }
}

Parameter	Type	Required	Description
max_total_order_amount	string	Yes	Maximum total order amount allowed within the period.
period_hours	integer	Yes	The time window in hours to look back (e.g. 24 for daily, 168 for weekly).
use_same_payment_option	boolean	No	If true, only orders placed with the same payment option are included in the total. Defaults to false.

---

Other Rules

CurrencyRule

The payment option is available based on the order currency.

{
  "klass": "omnishop.payments.rules.CurrencyRule",
  "params": {
    "currencies": ["try", "usd"],
    "exclude": false
  }
}

Parameter	Type	Required	Description
currencies	array	Yes	List of currency codes.
exclude	boolean	No	If false (default), the payment option is available only for listed currencies. If true, it is available for all currencies except the listed ones.

ClientTypeRule

The payment option is available only if the basket's client type is in the allowed list.

{
  "klass": "omnishop.payments.rules.ClientTypeRule",
  "params": {
    "clients": ["b2b", "instore"]
  }
}

Parameter	Type	Required	Description
clients	array	Yes	List of allowed client type values (e.g. "default", "b2b", "instore").

LoyaltyMoneyRule

The payment option is available only if loyalty money is enabled and covers the full order amount. No parameters required.

{
  "klass": "omnishop.payments.rules.LoyaltyMoneyRule",
  "params": {}
}

GiftCardRule

The payment option is available only if the basket has gift card reservations that cover the full order amount. No parameters required.

{
  "klass": "omnishop.payments.rules.GiftCardRule",
  "params": {}
}

PostCheckoutRule

The payment option is available only during post-checkout (after an order has been created). No parameters required.

{
  "klass": "omnishop.payments.rules.PostCheckoutRule",
  "params": {}
}

B2BPaymentRule

The payment option is available only if the request contains a valid B2B authorization header (X-B2B). The header value is verified against a hash of the basket items and the configured B2B_EXTENSION_CONF password. No parameters required.

{
  "klass": "omnishop.payments.rules.B2BPaymentRule",
  "params": {}
}

LiquerRule

A flexible rule that evaluates a custom query using the liquery DSL against the pre-order context.

{
  "klass": "omnishop.payments.rules.LiquerRule",
  "params": {
    "query": {
      "basket__user_id": 123
    }
  }
}

Parameter	Type	Required	Description
query	object	Yes	A liquery DSL query object evaluated against basket, pre_order, and request.