> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gu1.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Complete Transaction Monitoring Flow

> End-to-end guide for creating, analyzing, and monitoring transactions with automatic risk scoring — in the gu1 transaction monitoring product for fraud and AML.

## Overview

This guide covers the complete flow for transaction monitoring, from creation through automatic risk analysis and alert generation. Transactions are evaluated against transaction-specific rules to detect suspicious patterns, unusual amounts, high-risk jurisdictions, and other red flags.

## Flow Diagram

```mermaid theme={null}
graph TD
    A[Create Transaction] --> B[POST /transactions]
    B --> C{Currency Conversion Needed?}

    C -->|Yes| D[Convert to USD]
    C -->|No| E[Transaction Created]

    D --> F{Conversion Successful?}
    F -->|Yes| G[Store USD Amount]
    F -->|No| H[Store Without USD]

    G --> E
    H --> E

    E --> I{executeRules = true?}
    I -->|Yes| J[Auto Risk Analysis]
    I -->|No| K[Return Transaction]

    J --> L[Load Transaction Context]
    L --> M[Select Transaction Rules]
    M --> N[Execute Rules Engine]

    N --> O[Calculate Risk Score]
    O --> P{Score > Threshold?}

    P -->|Yes| Q[Flag Transaction]
    P -->|No| R[Approve Transaction]

    Q --> S[Create Alerts]
    R --> T[Update Risk Score]

    S --> U[Consolidate Alerts]
    T --> V[Return Result]

    U --> W[Create Investigation]
    W --> X[Send Notifications]
    X --> V
```

## Step 1: Create Transaction

Transactions are created via the transaction API with automatic currency conversion and optional rule execution.

**Endpoint**: `POST /transactions`

**Request**:

```json theme={null}
{
  "externalId": "TXN-2024-00001",
  "type": "TRANSFER",
  "status": "PENDING",
  "amount": 50000,
  "currency": "EUR",
  "paymentMethod": "bank_transfer",
  "originEntityId": "sender-entity-uuid",
  "originName": "John Doe",
  "originCountry": "FR",
  "destinationEntityId": "receiver-entity-uuid",
  "destinationName": "Acme Corporation",
  "destinationCountry": "US",
  "description": "Business payment for services",
  "category": "B2B",
  "transactedAt": "2025-12-24T10:30:00Z",
  "executeRules": true,
  "metadata": {
    "ip": "192.168.1.1",
    "userAgent": "Mozilla/5.0...",
    "sessionId": "sess_abc123"
  }
}
```

**Field Descriptions**:

| Field                 | Type     | Required | Description                                                                                                    |
| --------------------- | -------- | -------- | -------------------------------------------------------------------------------------------------------------- |
| externalId            | string   | Yes      | Your unique identifier for this transaction                                                                    |
| type                  | enum     | Yes      | Transaction type: PAYMENT, TRANSFER, WITHDRAWAL, DEPOSIT, REFUND, CHARGEBACK, REVERSAL, FEE, ADJUSTMENT, OTHER |
| status                | enum     | No       | Transaction status (default: PENDING)                                                                          |
| amount                | number   | Yes      | Transaction amount in original currency                                                                        |
| currency              | string   | Yes      | ISO 4217 currency code (e.g., USD, EUR, GBP)                                                                   |
| paymentMethod         | enum     | No       | Payment method used                                                                                            |
| originEntityId        | uuid     | No       | Sender entity ID (if entity exists in system)                                                                  |
| originExternalId      | string   | No       | Sender external identifier                                                                                     |
| originName            | string   | No       | Sender name                                                                                                    |
| originCountry         | string   | No       | Sender country (ISO 3166-1 alpha-2)                                                                            |
| destinationEntityId   | uuid     | No       | Receiver entity ID (if entity exists in system)                                                                |
| destinationExternalId | string   | No       | Receiver external identifier                                                                                   |
| destinationName       | string   | No       | Receiver name                                                                                                  |
| destinationCountry    | string   | No       | Receiver country (ISO 3166-1 alpha-2)                                                                          |
| description           | string   | No       | Transaction description                                                                                        |
| category              | string   | No       | Transaction category                                                                                           |
| transactedAt          | datetime | No       | When the transaction occurred (default: now)                                                                   |
| executeRules          | boolean  | No       | Execute rules automatically (default: true)                                                                    |
| metadata              | object   | No       | Additional custom metadata                                                                                     |

**What happens automatically**:

1. **Currency Conversion**:
   * If currency is not USD, converts amount to USD using real-time exchange rates
   * Stores: `amountInUsd`, `exchangeRate`, `rateSource`, `rateTimestamp`
   * On conversion failure, transaction is still created (without USD amount)

2. **Transaction Creation**:
   * Transaction record created in database
   * Unique ID generated
   * Links to origin/destination entities if provided

3. **Automatic Risk Analysis** (if `executeRules: true`):
   * Executes transaction-specific rules
   * Calculates risk score
   * Creates alerts for matched rules
   * Updates transaction status if needed

**Response (with risk analysis)**:

```json theme={null}
{
  "transaction": {
    "id": "txn-uuid",
    "organizationId": "org-uuid",
    "externalId": "TXN-2024-00001",
    "type": "TRANSFER",
    "status": "PENDING",
    "amount": "50000.00",
    "currency": "EUR",
    "amountInUsd": "54500.00",
    "exchangeRate": "1.09",
    "rateSource": "fixer.io",
    "rateTimestamp": "2025-12-24T10:30:00Z",
    "convertedAt": "2025-12-24T10:30:01Z",
    "originEntityId": "sender-entity-uuid",
    "originName": "John Doe",
    "originCountry": "FR",
    "destinationEntityId": "receiver-entity-uuid",
    "destinationName": "Acme Corporation",
    "destinationCountry": "US",
    "riskScore": "68.00",
    "flagged": true,
    "riskFactors": [
      "Large transaction amount detected",
      "Cross-border transaction to high-risk jurisdiction"
    ],
    "transactedAt": "2025-12-24T10:30:00Z",
    "createdAt": "2025-12-24T10:30:02Z"
  },
  "rulesExecutionSummary": {
    "rulesHit": [
      {
        "name": "Large Transaction Amount",
        "description": "Flags transfers above threshold",
        "score": 30,
        "priority": 10,
        "category": "transaction-monitoring",
        "status": "active",
        "conditions": [{ "field": "amount", "operator": "gte", "value": "50000" }],
        "actions": [{ "type": "add_risk_score", "value": 30 }]
      },
      {
        "name": "High-Risk Jurisdiction Transfer",
        "description": "Cross-border high-risk corridor",
        "score": 38,
        "priority": 20,
        "category": "transaction-monitoring",
        "status": "active",
        "conditions": [],
        "actions": [
          { "type": "add_risk_score", "value": 38 },
          { "type": "create_alert", "result": { "alertId": "alert-uuid" } }
        ]
      }
    ],
    "rulesNoHit": [],
    "actionsExecuted": {
      "alerts": [{ "ruleId": "rule-uuid-2", "severity": "critical" }]
    },
    "totalScore": 68,
    "matchedRulesCount": 2,
    "executionTimeMs": 850,
    "trigger": "created",
    "riskMatrixName": "Default Transaction Matrix"
  }
}
```

## Step 2: Currency Conversion

### How Currency Conversion Works

1. **Automatic Conversion**: If `currency !== 'USD'`, system automatically converts to USD
2. **Provider**: Uses `ms-providers` service (configured via `MS_PROVIDERS_URL`)
3. **Caching**: Exchange rates cached for 1 minute (TTL)
4. **Resilience**: Circuit breaker pattern with fallback to stale cache
5. **Graceful Degradation**: If conversion fails, transaction still created (without USD amount)

**Conversion Metadata**:

```json theme={null}
{
  "amountInUsd": "54500.00",
  "exchangeRate": "1.09",
  "rateSource": "fixer.io",
  "rateTimestamp": "2025-12-24T10:30:00Z",
  "convertedAt": "2025-12-24T10:30:01Z"
}
```

**USD Transactions**:

* If `currency: 'USD'`, no conversion needed
* `amountInUsd = amount`
* `exchangeRate = 1`
* `rateSource = 'no-conversion'`

### Conversion Failure Handling

If currency service is unavailable:

```json theme={null}
{
  "transaction": {
    "amount": "50000.00",
    "currency": "EUR",
    "amountInUsd": null,
    "exchangeRate": null,
    "rateSource": null
  }
}
```

Transaction is created successfully, but USD amount is unavailable. Rules that depend on USD amounts will use original amount instead.

## Step 3: Transaction Risk Analysis

### How Transaction Risk Analysis Works

The **RulesExecutionService** evaluates transactions using transaction-specific rules:

1. **Context Loading**:
   * Loads transaction data
   * Loads linked entities (origin/destination) with enrichment data
   * Prepares execution context

2. **Rule Selection**:
   * Filters rules by `targetEntityTypes: ['transaction']`
   * Filters by trigger: `'created'` (for automatic) or `'manual_evaluation'`
   * Filters by status: `enabled: true` and `status: 'active'`

3. **Rules Execution**:
   * Evaluates rule conditions against transaction context
   * Executes actions for matched rules (add score, create alerts, update status)
   * Accumulates risk score

4. **Score Update**:
   * Updates transaction `riskScore`
   * Sets `flagged: true` if score > 50
   * Stores `riskFactors` array with reasons

5. **Alert Creation**:
   * Rules with `create_alert` action generate alerts
   * Alerts linked to transaction
   * Alerts consolidated into investigations after 5-second delay

### Transaction-Specific Rules Examples

**Rule 1: Large Transaction Amount**

```json theme={null}
{
  "name": "Large Transaction Amount",
  "targetEntityTypes": ["transaction"],
  "triggers": ["created"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "amountInUsd",
        "operator": "greater_than",
        "value": 50000
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 30
    }
  ]
}
```

**Rule 2: High-Risk Jurisdiction Transfer**

```json theme={null}
{
  "name": "High-Risk Jurisdiction Transfer",
  "targetEntityTypes": ["transaction"],
  "triggers": ["created"],
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "originCountry",
        "operator": "in_list",
        "value": ["AF", "IR", "KP", "SY"]
      },
      {
        "field": "destinationCountry",
        "operator": "in_list",
        "value": ["AF", "IR", "KP", "SY"]
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 50
    },
    {
      "type": "create_alert",
      "severity": "critical",
      "description": "Transaction involves high-risk jurisdiction"
    }
  ]
}
```

**Rule 3: Rapid Transaction Velocity**

```json theme={null}
{
  "name": "Rapid Transaction Velocity",
  "targetEntityTypes": ["transaction"],
  "triggers": ["created"],
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "originEntityId",
        "operator": "historical_count",
        "timeWindow": "1h",
        "comparison": "greater_than",
        "value": 10
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 40
    },
    {
      "type": "create_alert",
      "severity": "warning",
      "description": "Unusual transaction velocity detected"
    }
  ]
}
```

**Rule 4: Sanctioned Entity Transaction**

```json theme={null}
{
  "name": "Sanctioned Entity Transaction",
  "targetEntityTypes": ["transaction"],
  "triggers": ["created"],
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "originEntity.enrichment.sanctionsMatch",
        "operator": "equals",
        "value": true
      },
      {
        "field": "destinationEntity.enrichment.sanctionsMatch",
        "operator": "equals",
        "value": true
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 100
    },
    {
      "type": "update_status",
      "status": "blocked"
    },
    {
      "type": "create_alert",
      "severity": "critical",
      "description": "Transaction involves sanctioned entity"
    }
  ]
}
```

### Transaction Context Structure

The rules engine receives this context:

```json theme={null}
{
  "transaction": {
    "id": "txn-uuid",
    "type": "TRANSFER",
    "amount": 50000,
    "currency": "EUR",
    "amountInUsd": 54500,
    "originEntityId": "sender-uuid",
    "originName": "John Doe",
    "originCountry": "FR",
    "destinationEntityId": "receiver-uuid",
    "destinationName": "Acme Corp",
    "destinationCountry": "US",
    "transactedAt": "2025-12-24T10:30:00Z"
  },
  "originEntity": {
    "id": "sender-uuid",
    "type": "person",
    "name": "John Doe",
    "enrichmentData": {
      "isPep": false,
      "sanctionsMatch": false,
      "riskScore": 25
    }
  },
  "destinationEntity": {
    "id": "receiver-uuid",
    "type": "company",
    "name": "Acme Corp",
    "enrichmentData": {
      "sanctionsMatch": false,
      "riskScore": 42
    }
  }
}
```

## Step 4: Batch Transaction Creation

For high-volume scenarios, use the batch endpoint to create multiple transactions efficiently.

**Endpoint**: `POST /transactions/batch`

**Request**:

```json theme={null}
{
  "transactions": [
    {
      "externalId": "TXN-001",
      "type": "PAYMENT",
      "amount": 1000,
      "currency": "USD",
      "originName": "Customer A",
      "destinationName": "Merchant X"
    },
    {
      "externalId": "TXN-002",
      "type": "PAYMENT",
      "amount": 2500,
      "currency": "EUR",
      "originName": "Customer B",
      "destinationName": "Merchant X"
    }
  ],
  "executeRules": true,
  "skipDuplicates": true
}
```

**Features**:

* Bulk insert for better performance
* Optimized currency conversion (caches rates for same currency)
* Automatic duplicate detection (by externalId)
* Optional rule execution on all transactions
* Max 1000 transactions per batch
* 2-minute timeout

**Response**:

```json theme={null}
{
  "summary": {
    "total": 2,
    "created": 2,
    "duplicates": 0,
    "failed": 0,
    "flagged": 0,
    "totalCost": 150
  },
  "transactions": [
    {
      "id": "txn-uuid-1",
      "externalId": "TXN-001",
      "riskScore": "15.00",
      "flagged": false
    },
    {
      "id": "txn-uuid-2",
      "externalId": "TXN-002",
      "riskScore": "22.00",
      "flagged": false
    }
  ],
  "executionTimeMs": 3200
}
```

## Step 5: Manual Transaction Analysis

If you created a transaction with `executeRules: false`, you can manually trigger risk analysis later.

**Endpoint**: `POST /entities/:transactionId/analyze`

**Request**:

```json theme={null}
{
  "entityType": "transaction",
  "enrichIfNeeded": false
}
```

**Use Cases**:

* Re-analyze transaction after entity enrichment
* Analyze transaction after rule updates
* Periodic re-scoring of pending transactions

**Response**: Same as automatic risk analysis result

## Step 6: Transaction Queries and Monitoring

### List Transactions with Filtering

**Endpoint**: `GET /transactions`

**Query Parameters**:

```
GET /transactions?flagged=true&minAmount=10000&sortBy=risk_score&sortOrder=desc&limit=50
```

**Available Filters**:

* `flagged`: Filter by flagged status (true, false, all)
* `minAmount` / `maxAmount`: Amount range filter (in original currency)
* `currency`: Filter by currency
* `type`: Filter by transaction type
* `status`: Filter by transaction status
* `entityId`: Filter by origin or destination entity
* `startDate` / `endDate`: Date range filter
* `search`: Free-text search (externalId, description, names)
* `sortBy`: Sort field (transacted\_at, amount, risk\_score, created\_at)
* `sortOrder`: Sort direction (asc, desc)

**Response**:

```json theme={null}
{
  "transactions": [
    {
      "id": "txn-uuid",
      "externalId": "TXN-2024-00001",
      "type": "TRANSFER",
      "amount": "50000.00",
      "currency": "EUR",
      "amountInUsd": "54500.00",
      "riskScore": "68.00",
      "flagged": true,
      "originName": "John Doe",
      "destinationName": "Acme Corp",
      "transactedAt": "2025-12-24T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 150,
    "limit": 50,
    "offset": 0
  }
}
```

### Get Transaction Details

**Endpoint**: `GET /transactions/:transactionId`

**Response**: Full transaction object with risk analysis details

### View Transaction Alerts

**Endpoint**: `GET /alerts?transactionId=:transactionId`

**Response**: All alerts generated for the transaction

## Step 7: Alert Consolidation and Investigations

After risk analysis, alerts are automatically consolidated into investigations:

1. **Alert Creation**: Rules with `create_alert` action create individual alerts
2. **5-Second Delay**: System waits to collect all related alerts
3. **Consolidation**: Related alerts consolidated into single investigation
4. **Investigation Creation**: Investigation created with:
   * Priority based on highest alert severity
   * Status: "open"
   * All related alerts linked
5. **Notifications**: Analysts notified of new investigation

**Investigation Structure**:

```json theme={null}
{
  "id": "investigation-uuid",
  "organizationId": "org-uuid",
  "title": "High-Risk Transaction: TXN-2024-00001",
  "priority": "critical",
  "status": "open",
  "relatedTransactions": ["txn-uuid"],
  "relatedEntities": ["sender-uuid", "receiver-uuid"],
  "alerts": [
    {
      "id": "alert-uuid-1",
      "severity": "critical",
      "type": "HIGH_RISK_JURISDICTION",
      "description": "Transaction involves high-risk jurisdiction"
    },
    {
      "id": "alert-uuid-2",
      "severity": "warning",
      "type": "LARGE_AMOUNT",
      "description": "Transaction amount exceeds threshold"
    }
  ],
  "createdAt": "2025-12-24T10:30:07Z"
}
```

## Best Practices

1. **Always Enable Auto-Rules**: Set `executeRules: true` (default) to catch suspicious transactions immediately.

2. **Use Batch API for Volume**: For bulk imports or high-volume scenarios, use `/transactions/batch` for better performance.

3. **Link Entities**: Always provide `originEntityId` and `destinationEntityId` when available. This enables:
   * Entity enrichment data in rule evaluation
   * Better risk aggregation
   * Entity-level transaction patterns

4. **External ID Mapping**: Always set unique `externalId` for correlation with your systems.

5. **Currency Handling**: System handles currency conversion automatically. Ensure `MS_PROVIDERS_URL` is configured correctly.

6. **Rule Configuration**: Configure transaction rules for your risk appetite:
   * Amount thresholds appropriate for your business
   * High-risk jurisdictions based on your compliance requirements
   * Velocity rules based on normal transaction patterns

7. **Status Management**: Use transaction `status` field to track lifecycle:
   * PENDING → APPROVED/REJECTED/CANCELLED
   * Update status based on manual review or external validation

8. **Monitoring**: Set up dashboards to monitor:
   * Flagged transaction rate
   * Average risk scores
   * Alert volume by type
   * Investigation resolution time

## Advanced Patterns

### Pattern 1: Entity Risk Affects Transaction Risk

Configure rules that consider entity risk:

```json theme={null}
{
  "name": "High-Risk Entity Transaction",
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "originEntity.riskScore",
        "operator": "greater_than",
        "value": 70
      },
      {
        "field": "destinationEntity.riskScore",
        "operator": "greater_than",
        "value": 70
      }
    ]
  },
  "actions": [
    {
      "type": "add_risk_score",
      "value": 35
    }
  ]
}
```

### Pattern 2: Velocity and Pattern Detection

Use historical queries in rules:

```json theme={null}
{
  "name": "Unusual Transaction Pattern",
  "conditions": {
    "operator": "AND",
    "conditions": [
      {
        "field": "originEntityId",
        "operator": "historical_sum",
        "aggregateField": "amountInUsd",
        "timeWindow": "24h",
        "comparison": "greater_than",
        "value": 100000
      }
    ]
  }
}
```

### Pattern 3: Sanctions Screening on Transaction

```json theme={null}
{
  "name": "Transaction Sanctions Check",
  "conditions": {
    "operator": "OR",
    "conditions": [
      {
        "field": "originEntity.enrichment.sanctionsMatch",
        "operator": "equals",
        "value": true
      },
      {
        "field": "destinationEntity.enrichment.sanctionsMatch",
        "operator": "equals",
        "value": true
      }
    ]
  },
  "actions": [
    {
      "type": "update_status",
      "status": "blocked"
    },
    {
      "type": "add_risk_score",
      "value": 100
    }
  ]
}
```

## Error Handling

### Currency Conversion Failures

```json theme={null}
{
  "transaction": {
    "amountInUsd": null,
    "exchangeRate": null
  },
  "warnings": [
    "Currency conversion failed: fixer.io service unavailable"
  ]
}
```

Transaction created successfully, rules use original amount.

### Rule Execution Failures

```json theme={null}
{
  "rulesExecutionSummary": null,
  "warnings": [
    "Rules engine timeout after 30000ms"
  ]
}
```

Transaction created, but risk not calculated. Manually trigger analysis later.

### Batch Partial Failures

```json theme={null}
{
  "summary": {
    "total": 100,
    "created": 95,
    "failed": 5
  },
  "failures": [
    {
      "externalId": "TXN-042",
      "error": "Validation failed: invalid currency code"
    }
  ]
}
```

Successful transactions created, failures reported separately.

## Next Steps

* [Configure Transaction Rules](/en/use-cases/transaction-monitoring/rules-configuration)
* [Set Up Velocity Rules](/en/use-cases/transaction-monitoring/fraud-detection)
* [Alert Investigation Workflow](/en/workflows/overview)
* [Transaction Analytics Dashboard](/en/use-cases/transaction-monitoring/overview)