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.

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

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

Response:

1 {
2   "enabled": true,
3   "fraud_rules": [],
4   "custom_message": null
5 }

Update fraud settings

$ curl -X PATCH https://api.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.

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):

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

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

$ curl -X POST https://api.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:

1 {
2   "id": "frule_live_a1b2c3d4e5f6g7h8",
3   "name": "Block prepaid cards",
4   "logic": "AND",
5   "enabled": true,
6   "reason": "Prepaid cards are not accepted.",
7   "conditions": [
8     {
9       "field": "card_type",
10       "operator": "equals",
11       "value": "prepaid"
12     }
13   ],
14   "created_at": "2024-01-15T10:30:00Z",
15   "updated_at": "2024-01-15T10:30:00Z"
16 }

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

$ curl "https://api.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

$ curl https://api.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:

$ curl -X PATCH https://api.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

$ curl -X DELETE https://api.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):

$ curl -X POST https://api.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):

$ curl -X POST https://api.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`