> For the complete documentation index, see [llms.txt](https://docs.akinon.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.akinon.com/technical-guides/commerce/payment-option-rules.md).

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

```json
{
  "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.

```json
{
  "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.

```json
{
  "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**.

```json
{
  "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`.

```json
{
  "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`.

```json
{
  "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.

```json
{
  "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.

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

To require at least one product to have the attribute:

```json
{
  "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       | <p><code>"all"</code> (default): all products must have the attribute.<br><code>"any"</code>: at least one product must have the attribute.</p> |

### BasketProductsAttributeRule

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

```json
{
  "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       | <p><code>"all"</code> (default): all products must match the attribute value.<br><code>"any"</code>: at least one product must match the attribute value.</p> |

### BasketHasTradableItemRule

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

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

***

## User Rules

### LoginRequiredRule

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

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

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

| Parameter | Type     | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                 |
| --------- | -------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `page`    | `string` | No       | <p>The checkout shipping page type to match. Defaults to <code>"ShippingOptionSelectionPage"</code>.<br>Available values: <code>"ShippingOptionSelectionPage"</code>, <code>"DataSourceShippingOptionSelectionPage"</code>, <code>"AttributeBasedShippingOptionSelectionPage"</code>, <code>"RemoteAttributeBasedShippingOptionSelectionPage"</code>, <code>"RemoteShippingOptionSelectionPage"</code>.</p> |

This rule checks the `CHECKOUT_SHIPPING_OPTION_SELECTION_PAGE` dynamic setting only, so it applies to every basket at once. To decide per basket (for example, only when the whole basket uses one shipping option), use [SingleShippingOptionRule](#singleshippingoptionrule).

### SingleShippingOptionRule

The payment option is available only if the whole basket ships with a single shipping option, and that option is in the allowed list. It is intended for payment options such as cash on delivery (COD) when the basket can be split into several shipping groups with [Attribute Based Shipping Options](https://docs.akinon.com/technical-guides/commerce/attribute-based-shipping-options.md).

With attribute based shipping, a basket can have a different shipping option for each group, but the pre-order keeps only the first one as the "selected" shipping option. For this reason, [ShippingOptionRule](#shippingoptionrule) and [PayOnDeliveryRule](#payondeliveryrule) only see the first group's option. `SingleShippingOptionRule` checks every selected group instead.

```json
{
  "rule": {
    "klass": "omnishop.payments.rules.SingleShippingOptionRule",
    "params": {
      "slugs": ["express", "standard"]
    }
  }
}
```

| Parameter | Type    | Required | Description                                 |
| --------- | ------- | -------- | ------------------------------------------- |
| `slugs`   | `array` | Yes      | Slugs of the shipping options that qualify. |

The payment option is available only when all of the following are true:

* Exactly one distinct shipping option is used across all selected groups, and its slug is in `slugs`. Several groups that use the same shipping option count as one.
* The group value of every selected group is also in `slugs`. This assumes that the group values are the same as the shipping option slugs, which is the case when the remote service returns the shipping option slugs as its group labels (`attributeValue`) in the [remote attribute based flow](https://docs.akinon.com/technical-guides/commerce/attribute-based-shipping-options.md#remote-attribute-based-shipping-options).

The payment option is hidden when no shipping option has been selected yet.

**The `None` group.** In the remote flow, items that the remote service did not allocate, items whose split is inconsistent, and all items when the remote service is unavailable are placed in a fallback group named `None`. Since `None` is not a shipping option slug, the payment option is hidden for any basket that contains a `None` group. To keep it available in that case, add `"None"` to `slugs` (the rule still requires that all groups use the same shipping option).

**Other pages.**

* With the standard `AttributeBasedShippingOptionSelectionPage`, the group values are product attribute values (for example `pendik`), not shipping option slugs. If you use this rule there, list those attribute values in `slugs` as well.
* On pages that do not group (such as `ShippingOptionSelectionPage`), the rule checks the single selected shipping option.
* Do not use it with `DataSourceShippingOptionSelectionPage`, because that page also stores only the first group's option as the selected shipping option.

{% hint style="warning" %}
`slugs` is required. If it is missing or empty, the payment option is hidden for every basket and an error is logged (`[PAYMENT RULE] SingleShippingOptionRule has no 'slugs' configured`), which is reported to the error tracker. Fix the payment option configuration to make it available again.
{% endhint %}

To combine this rule with another rule, wrap both in an [AndRule](#andrule):

```json
{
  "rule": {
    "klass": "omnishop.payments.rules.AndRule",
    "params": {
      "children": [
        {
          "klass": "omnishop.payments.rules.BasketAmountRule",
          "params": {"min_total_amount": 100}
        },
        {
          "klass": "omnishop.payments.rules.SingleShippingOptionRule",
          "params": {"slugs": ["express", "standard"]}
        }
      ]
    }
  }
}
```

### RetailStoreStockRule

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

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

```json
{
  "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.

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

### LiquerRule

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

```json
{
  "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`. |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.akinon.com/technical-guides/commerce/payment-option-rules.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
