> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.paymentkit.com/guides/payment-orchestration/fraud-rules/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.paymentkit.com/_mcp/server.

# Fraud rules

# How fraud rules work

PaymentKit evaluates your fraud rules after card tokenization, before a payment is authorized. Each rule contains one or more **conditions**; if a rule matches, the card is blocked and the customer sees a decline message.

```mermaid
flowchart TD
    A[Customer submits card] --> B[Card tokenization]
    B --> C{Fraud rules enabled?}
    C -->|No| G[Proceed to processor]
    C -->|Yes| D[Evaluate rules in order]
    D --> E{Any rule matches?}
    E -->|Yes| F[Block — show decline message]
    E -->|No| G
    G --> H[Payment attempted]
```

Rules are evaluated in the order they are listed. The first matching rule wins and blocks the card — subsequent rules are not evaluated.

---

# Fraud settings vs. fraud rules

There are two related but distinct concepts:

| Concept            | What it controls                                                     |
| ------------------ | -------------------------------------------------------------------- |
| **Fraud settings** | Account-level toggle (`enabled`) and optional custom decline message |
| **Fraud rules**    | Individual card-matching rules (CRUD resource)                       |

Fraud rules are only evaluated when `enabled` is `true` in your account's fraud settings.

---

# Manage fraud settings

## Get fraud settings

```bash
curl https://app.paymentkit.com/api/accounts/{account_id}/fraud-settings \
  -H "Authorization: Bearer sk_live_..."
```

Response:

```json
{
  "enabled": true,
  "fraud_rules": [],
  "custom_message": null
}
```

## Update fraud settings

```bash
curl -X PATCH https://app.paymentkit.com/api/accounts/{account_id}/fraud-settings \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": true,
    "custom_message": "This payment method is not accepted."
  }'
```

| Field            | Type           | Description                                                                   |
| ---------------- | -------------- | ----------------------------------------------------------------------------- |
| `enabled`        | boolean        | Whether fraud protection is active                                            |
| `custom_message` | string \| null | Decline message shown to customers. Overrides the per-rule `reason` when set. |

> **Note**
>
> Setting `custom_message` replaces the per-rule `reason` for all rules. Leave it `null` to show each rule's individual reason to the customer.

## Reset fraud settings

Resets all fraud settings to defaults (`enabled: false`, no custom message):

```bash
curl -X DELETE https://app.paymentkit.com/api/accounts/{account_id}/fraud-settings \
  -H "Authorization: Bearer sk_live_..."
```

> **Warning**
>
> This does **not** delete your fraud rules — it only resets the account-level settings. Your rules remain and can be re-enabled.

---

# Manage fraud rules

## Create a rule

```bash
curl -X POST https://app.paymentkit.com/api/{account_id}/fraud-rules \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Block prepaid cards",
    "logic": "AND",
    "enabled": true,
    "reason": "Prepaid cards are not accepted.",
    "conditions": [
      {
        "field": "card_type",
        "operator": "equals",
        "value": "prepaid"
      }
    ]
  }'
```

Response:

```json
{
  "id": "frule_live_a1b2c3d4e5f6g7h8",
  "name": "Block prepaid cards",
  "logic": "AND",
  "enabled": true,
  "reason": "Prepaid cards are not accepted.",
  "conditions": [
    {
      "field": "card_type",
      "operator": "equals",
      "value": "prepaid"
    }
  ],
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
```

### Rule fields

| Field        | Required | Default | Description                                                               |
| ------------ | -------- | ------- | ------------------------------------------------------------------------- |
| `name`       | Yes      | —       | Display name (max 255 chars)                                              |
| `logic`      | No       | `AND`   | `AND` — all conditions must match; `OR` — any condition triggers the rule |
| `enabled`    | No       | `true`  | Whether this rule is active                                               |
| `reason`     | Yes      | —       | Decline reason shown to the customer (max 500 chars)                      |
| `conditions` | Yes      | —       | One or more conditions (see below)                                        |

### Conditions

Each condition has three fields:

| Field      | Options                                                              |
| ---------- | -------------------------------------------------------------------- |
| `field`    | `country`, `brand`, `card_type`, `amount`, `iin`                     |
| `operator` | `equals`, `in`, `not_in`, `greater_than`, `less_than`, `starts_with` |
| `value`    | String, number, or list of strings (depending on operator)           |

#### Field reference

| Field       | Description                                                                 | Example values                                   |
| ----------- | --------------------------------------------------------------------------- | ------------------------------------------------ |
| `country`   | Card billing country (ISO 3166-1 alpha-2)                                   | `"US"`, `["RU", "KP", "IR"]`                     |
| `brand`     | Card network                                                                | `"visa"`, `"mastercard"`, `"amex"`, `"discover"` |
| `card_type` | Card funding type                                                           | `"credit"`, `"debit"`, `"prepaid"`               |
| `amount`    | Transaction amount in the account's default currency (integer, minor units) | `5000` (= \$50.00)                               |
| `iin`       | Card IIN/BIN (first 6 digits of card number)                                | `"411111"`, `["411111", "555555"]`               |

#### Operator compatibility

| Operator       | Compatible fields                      | Value type       |
| -------------- | -------------------------------------- | ---------------- |
| `equals`       | All fields                             | String or number |
| `in`           | `country`, `brand`, `card_type`, `iin` | List of strings  |
| `not_in`       | `country`, `brand`, `card_type`, `iin` | List of strings  |
| `greater_than` | `amount`                               | Number           |
| `less_than`    | `amount`                               | Number           |
| `starts_with`  | `iin`, `country`                       | String           |

## List rules

```bash
curl "https://app.paymentkit.com/api/{account_id}/fraud-rules?page=1&page_size=20" \
  -H "Authorization: Bearer sk_live_..."
```

Supports pagination, filtering, and sorting:

| Parameter         | Description                                               |
| ----------------- | --------------------------------------------------------- |
| `page`            | Page number (default: 1)                                  |
| `page_size`       | Results per page                                          |
| `filter[name]`    | Filter by rule name                                       |
| `filter[enabled]` | Filter by enabled status                                  |
| `sort`            | Sort field: `name`, `enabled`, `created_at`, `updated_at` |
| `order`           | `asc` or `desc`                                           |
| `search`          | Full-text search across `name` and `reason`               |

## Get a rule

```bash
curl https://app.paymentkit.com/api/{account_id}/fraud-rules/{rule_id} \
  -H "Authorization: Bearer sk_live_..."
```

## Update a rule

All fields are optional — only include the fields you want to change:

```bash
curl -X PATCH https://app.paymentkit.com/api/{account_id}/fraud-rules/{rule_id} \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "enabled": false
  }'
```

## Delete a rule

```bash
curl -X DELETE https://app.paymentkit.com/api/{account_id}/fraud-rules/{rule_id} \
  -H "Authorization: Bearer sk_live_..."
```

Returns `204 No Content` on success.

---

# Example: multi-condition rule

Block high-value transactions from specific countries, using `AND` logic (both conditions must match):

```bash
curl -X POST https://app.paymentkit.com/api/{account_id}/fraud-rules \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High-value restricted countries",
    "logic": "AND",
    "enabled": true,
    "reason": "This transaction cannot be processed.",
    "conditions": [
      {
        "field": "country",
        "operator": "in",
        "value": ["RU", "KP", "IR"]
      },
      {
        "field": "amount",
        "operator": "greater_than",
        "value": 100000
      }
    ]
  }'
```

Block any card from a set of specific BINs using `OR` logic (either condition triggers the rule):

```bash
curl -X POST https://app.paymentkit.com/api/{account_id}/fraud-rules \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Blocked BINs",
    "logic": "OR",
    "enabled": true,
    "reason": "This card cannot be used for this purchase.",
    "conditions": [
      {
        "field": "iin",
        "operator": "in",
        "value": ["411111", "555555", "378282"]
      }
    ]
  }'
```

---

# Permissions

| Action                        | Required permission         |
| ----------------------------- | --------------------------- |
| View fraud settings           | `SETTINGS:VIEW`             |
| Update / reset fraud settings | `SETTINGS:EDIT`             |
| View fraud rules              | `BILLING_OBJECT:VIEW`       |
| Create fraud rules            | `BILLING_OBJECT:CREATE`     |
| Update fraud rules            | `BILLING_OBJECT:EDIT`       |
| Delete fraud rules            | `BILLING_OBJECT:DEACTIVATE` |

> Block cards at checkout based on card properties and transaction amount using configurable rules evaluated before each payment attempt.