Rules Configuration

Introduction

gu1’s rules engine allows you to create custom logic to analyze transactions in real-time. Rules can be synchronous (affect transaction decision) or asynchronous (monitoring only).

Sync vs Async Rules

Synchronous Rules (SYNC)

Execute during API call and affect transaction decision When to use:

Block fraudulent transactions
Enforce transaction limits
Require additional authentication
Regulatory requirements

Characteristics:

Evaluated before response
Can change transaction state
Performance target: < 100ms
Limited to lightweight operations

Example:

Daily limit exceeded → REJECT transaction

Asynchronous Rules (ASYNC)

Execute in parallel without affecting transaction When to use:

Pattern monitoring
Behavioral analysis
Complex aggregations
Historical analysis

Characteristics:

Don’t block API response
Can perform heavy queries
Generate alerts only
Feed Intelligence Dashboard

Example:

User has 15 transactions today → Generate MEDIUM alert

Rule Structure

{
  "name": "Rule Name",
  "category": "fraud|aml|compliance|risk",
  "priority": 100,
  "enabled": true,
  "evaluationMode": "sync|async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND|OR",
    "conditions": [...]
  },
  "actions": [...]
}

Configuration Fields

Basic Fields

Field	Type	Description
`name`	string	Rule name (unique)
`category`	string	Category: fraud, aml, compliance, risk
`priority`	number	Execution priority (1-1000, higher = first)
`enabled`	boolean	Enable/disable rule
`evaluationMode`	string	”sync” or “async”
`targetEntityTypes`	array	Entity types to evaluate ([“transaction”])

Conditions

Rules use a flexible conditions system:

{
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amount",
        "operator": "GREATER_THAN",
        "value": 10000
      },
      {
        "field": "currency",
        "operator": "IN",
        "value": ["USD", "EUR", "GBP"]
      }
    ]
  }
}

Condition Operators

Operator	Description	Example
`EQUALS`	Exact equality	`"type" EQUALS "PAYMENT"`
`NOT_EQUALS`	Not equal	`"status" NOT_EQUALS "blocked"`
`GREATER_THAN`	Greater than	`"amount" > 1000`
`GREATER_THAN_OR_EQUAL`	Greater or equal	`"amount" >= 1000`
`LESS_THAN`	Less than	`"amount" < 100`
`LESS_THAN_OR_EQUAL`	Less or equal	`"amount" <= 100`
`IN`	In list	`"country" IN ["US", "CA"]`
`NOT_IN`	Not in list	`"country" NOT_IN ["KP", "IR"]`
`CONTAINS`	String contains	`"description" CONTAINS "test"`
`NOT_CONTAINS`	String doesn’t contain	`"email" NOT_CONTAINS "@temp"`
`STARTS_WITH`	String starts with	`"accountId" STARTS_WITH "4532"`
`ENDS_WITH`	String ends with	`"domain" ENDS_WITH ".ru"`
`REGEX`	Regex match	`"email" REGEX "^[a-z]+@"`
`EXISTS`	Field exists	`"metadata.userId" EXISTS`
`NOT_EXISTS`	Field doesn’t exist	`"referralCode" NOT_EXISTS`

Available Transaction Fields

// Core Fields
transaction.externalId
transaction.type          // PAYMENT, TRANSFER, WITHDRAWAL, etc.
transaction.amount
transaction.currency
transaction.timestamp

// Entity References
transaction.originEntityId
transaction.destinationEntityId

// Payment Details
transaction.origin.paymentMethod
transaction.origin.accountType
transaction.destination.paymentMethod

// Device Data
transaction.originDeviceData.ipAddress
transaction.originDeviceData.platform
transaction.originDeviceData.location.country
transaction.originDeviceData.location.city

// MCC and Description
transaction.mccCode
transaction.description

// Tags and Metadata
transaction.tags
transaction.metadata.*     // Any custom field

// Computed Fields (available in rules)
amountInUsd               // Amount converted to USD
metadata.userTransactionCount30d
metadata.merchantChargebackRate
metadata.deviceFirstSeen
metadata.ipRiskScore

Actions

Rules can trigger multiple actions:

1. Generate Alert

{
  "type": "generate_alert",
  "config": {
    "severity": "low|medium|high|critical",
    "type": "custom_alert_type",
    "message": "Alert description with {{variables}}"
  }
}

2. Set Decision (SYNC only)

{
  "type": "set_decision",
  "config": {
    "decision": "APPROVE|REJECT|HOLD|REVIEW_REQUIRED|ADDITIONAL_AUTH_REQUIRED",
    "reason": "Reason for decision"
  }
}

3. Create Investigation

{
  "type": "create_investigation",
  "config": {
    "priority": "low|medium|high|critical",
    "assignToTeam": "team_id",
    "assignToUser": "user_id",
    "requiresSAR": true
  }
}

Example Rules

1. Daily Transaction Limit (SYNC)

{
  "name": "Daily Limit - $10,000",
  "category": "compliance",
  "priority": 950,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.userTransactionSum24h",
        "operator": "GREATER_THAN",
        "value": 10000
      },
      {
        "field": "amount",
        "operator": "GREATER_THAN",
        "value": 0
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "daily_limit_exceeded",
        "message": "User {{originEntityId}} exceeded daily limit of $10,000"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "HOLD",
        "reason": "Daily transaction limit exceeded"
      }
    }
  ]
}

2. Transaction Velocity Alert (ASYNC)

{
  "name": "High Transaction Velocity",
  "category": "fraud",
  "priority": 800,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.userTransactionCount1h",
        "operator": "GREATER_THAN",
        "value": 10
      },
      {
        "field": "metadata.userAverageTransactionsPerHour",
        "operator": "LESS_THAN",
        "value": 3
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "medium",
        "type": "velocity_anomaly",
        "message": "User has {{metadata.userTransactionCount1h}} transactions in last hour (average: {{metadata.userAverageTransactionsPerHour}})"
      }
    }
  ]
}

3. High-Risk Country Block (SYNC)

{
  "name": "Block High-Risk Countries",
  "category": "fraud",
  "priority": 1000,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "originDeviceData.location.country",
        "operator": "IN",
        "value": ["KP", "IR", "SY"]
      },
      {
        "field": "amount",
        "operator": "GREATER_THAN",
        "value": 100
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "critical",
        "type": "high_risk_country",
        "message": "Transaction from high-risk country: {{originDeviceData.location.country}}"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "REJECT",
        "reason": "Transaction from sanctioned country"
      }
    }
  ]
}

4. Structuring Pattern Detection (ASYNC)

{
  "name": "Possible Structuring - $10K Threshold",
  "category": "aml",
  "priority": 900,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amountInUsd",
        "operator": "GREATER_THAN",
        "value": 9000
      },
      {
        "field": "amountInUsd",
        "operator": "LESS_THAN",
        "value": 10000
      },
      {
        "field": "metadata.userTransactionsSameAmountRange7d",
        "operator": "GREATER_THAN_OR_EQUAL",
        "value": 3
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "possible_structuring",
        "message": "User has {{metadata.userTransactionsSameAmountRange7d}} transactions near $10K threshold in last 7 days"
      }
    },
    {
      "type": "create_investigation",
      "config": {
        "priority": "high",
        "assignToTeam": "aml_compliance",
        "requiresSAR": true
      }
    }
  ]
}

5. New Card High Amount (SYNC)

{
  "name": "New Card - High Amount Alert",
  "category": "fraud",
  "priority": 850,
  "enabled": true,
  "evaluationMode": "sync",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "origin.paymentMethod",
        "operator": "EQUALS",
        "value": "CARD"
      },
      {
        "field": "metadata.cardFirstSeen",
        "operator": "LESS_THAN",
        "value": "{{timestamp - 3600}}"
      },
      {
        "field": "amount",
        "operator": "GREATER_THAN",
        "value": 500
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "high",
        "type": "new_card_high_amount",
        "message": "First transaction with new card for ${{amount}}"
      }
    },
    {
      "type": "set_decision",
      "config": {
        "decision": "ADDITIONAL_AUTH_REQUIRED",
        "reason": "High amount transaction with new card - require 3DS"
      }
    }
  ]
}

6. Unusual Time Pattern (ASYNC)

{
  "name": "Transaction Outside Normal Hours",
  "category": "fraud",
  "priority": 700,
  "enabled": true,
  "evaluationMode": "async",
  "targetEntityTypes": ["transaction"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "metadata.transactionHour",
        "operator": "IN",
        "value": [0, 1, 2, 3, 4, 5]
      },
      {
        "field": "metadata.userNormalHours",
        "operator": "NOT_CONTAINS",
        "value": "{{metadata.transactionHour}}"
      },
      {
        "field": "amount",
        "operator": "GREATER_THAN",
        "value": 1000
      }
    ]
  },
  "actions": [
    {
      "type": "generate_alert",
      "config": {
        "severity": "medium",
        "type": "unusual_time",
        "message": "Transaction at {{metadata.transactionHour}}:00 - outside user's normal hours"
      }
    }
  ]
}

Advanced Conditions

Nested Conditions

{
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "operator": "AND",
        "conditions": [
          {"field": "amount", "operator": "GREATER_THAN", "value": 5000},
          {"field": "type", "operator": "EQUALS", "value": "WITHDRAWAL"}
        ]
      },
      {
        "operator": "AND",
        "conditions": [
          {"field": "amount", "operator": "GREATER_THAN", "value": 10000},
          {"field": "type", "operator": "EQUALS", "value": "TRANSFER"}
        ]
      }
    ]
  }
}

Regex Patterns

{
  "field": "description",
  "operator": "REGEX",
  "value": "^(test|demo|fake).*"
}

Time-Based Aggregations

{
  "field": "metadata.userTransactionCount",
  "operator": "GREATER_THAN",
  "value": 5,
  "timeWindow": "1h"
}

Best Practices

✅ DO

Use appropriate evaluation mode
- SYNC for decisions that must block
- ASYNC for monitoring and analysis
Set correct priorities
- Critical blocks: 900-1000
- Standard checks: 500-899
- Monitoring: 100-499
Include meaningful messages
- Use template variables: {{field}}
- Provide context for analysts
- Include relevant metrics
Test thoroughly
- Start with ASYNC mode
- Monitor false positive rate
- Adjust thresholds based on data
Use metadata fields
- Aggregate data for patterns
- Track historical behavior
- Calculate risk scores

❌ DON’T

Don’t use heavy queries in SYNC rules
- Keep SYNC rules fast (< 100ms)
- Move complex logic to ASYNC
Don’t over-block
- Start with HOLD instead of REJECT
- Allow for manual review
- Monitor customer impact
Don’t create overlapping rules
- One rule should handle one pattern
- Use priorities correctly
- Avoid redundant checks
Don’t ignore false positives
- Track and analyze
- Adjust thresholds
- Use machine learning when available

Testing Rules

Test Mode

Enable test mode to evaluate rules without affecting transactions:

{
  "name": "Test Rule",
  "enabled": true,
  "testMode": true,
  ...
}

A/B Testing

Create variant rules to compare effectiveness:

{
  "name": "Fraud Check - Variant A",
  "variant": "A",
  "percentage": 50,
  ...
}

Monitoring Metrics

Track for each rule:

Execution count: How often rule runs
Match rate: % of times conditions met
False positive rate: Incorrectly flagged
True positive rate: Correctly flagged
Average execution time: Performance

Next Steps

Fraud Detection

Production-ready fraud rules

AML Monitoring

AML compliance rules

Merchant Monitoring

Merchant risk rules

API Reference

Complete API documentation

Custom lists API

Create lists and items for in_custom_list and related operators

​Introduction

​Sync vs Async Rules

​Synchronous Rules (SYNC)

​Asynchronous Rules (ASYNC)

​Rule Structure

​Configuration Fields

​Basic Fields

​Conditions

​Condition Operators

​Available Transaction Fields

​Actions

​1. Generate Alert

​2. Set Decision (SYNC only)

​3. Create Investigation

​Example Rules

​1. Daily Transaction Limit (SYNC)

​2. Transaction Velocity Alert (ASYNC)

​3. High-Risk Country Block (SYNC)

​4. Structuring Pattern Detection (ASYNC)

​5. New Card High Amount (SYNC)

​6. Unusual Time Pattern (ASYNC)

​Advanced Conditions

​Nested Conditions

​Regex Patterns

​Time-Based Aggregations

​Best Practices

​✅ DO

​❌ DON’T

​Testing Rules

​Test Mode

​A/B Testing

​Monitoring Metrics

​Next Steps