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

Getting Started

Use Cases

Webhooks

Workflows

Monitoring (entities)

Person

Messaging

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

Documentation Index

​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