Change Transaction Status

Endpoint

Change Transaction Status

PATCH http://api.gu1.ai/transactions/:id/changeStatus

Updates the status of an existing transaction with automatic validation of state transitions and optional rule execution for real-time risk re-assessment. Features:

Automatic validation of status transitions (prevents invalid state changes)
State machine enforcement (open ↔ closed state rules)
Automatic execution of update rules with trigger_transaction_updated trigger
Transaction integrity protection
Comprehensive audit trail

Authentication

All requests must include an API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Required Headers

Content-Type: application/json
Authorization: Bearer YOUR_API_KEY

Path Parameters

string

required

The UUID of the transaction to updateType: string (uuid)

Request Body

status

string

required

New transaction status. Must be a valid status enum value.Valid Statuses:

CREATED - Transaction created (open state)
PROCESSING - Transaction being processed (open state)
SUSPENDED - Transaction temporarily suspended (open state)
SENT - Transaction sent/transmitted (closed state)
EXPIRED - Transaction expired (closed state)
DECLINED - Transaction declined/rejected (closed state)
REFUNDED - Transaction refunded/reversed (closed state)
SUCCESSFUL - Transaction completed successfully (closed state)

State Transition Rules

The endpoint enforces strict state transition rules to maintain transaction integrity:

Open States

States that allow further transitions:

CREATED
PROCESSING
SUSPENDED
SENT

Closed States

Final states that cannot transition to other states:

EXPIRED
DECLINED
REFUNDED
SUCCESSFUL

Transition Matrix

From State	To State	Allowed?	Note
CREATED	PROCESSING	✅ Yes	Normal flow
CREATED	SUSPENDED	✅ Yes	Suspend for review
CREATED	SUCCESSFUL	✅ Yes	Quick approval
PROCESSING	SUSPENDED	✅ Yes	Suspend during processing
PROCESSING	SUCCESSFUL	✅ Yes	Normal completion
PROCESSING	DECLINED	✅ Yes	Reject during processing
SUSPENDED	PROCESSING	✅ Yes	Resume processing
SUSPENDED	SUCCESSFUL	✅ Yes	Approve suspended transaction
SUSPENDED	DECLINED	✅ Yes	Reject suspended transaction
SUCCESSFUL	PROCESSING	❌ No	Cannot reopen closed transaction
DECLINED	PROCESSING	❌ No	Cannot reopen closed transaction
EXPIRED	PROCESSING	❌ No	Cannot reopen closed transaction
REFUNDED	any	❌ No	Cannot change refunded transaction
SUCCESSFUL	DECLINED	❌ No	Cannot change between closed states

Key Rules:

✅ Open → Open: Allowed (e.g., CREATED → PROCESSING)
✅ Open → Closed: Allowed (e.g., PROCESSING → SUCCESSFUL)
❌ Closed → Open: NOT Allowed (e.g., SUCCESSFUL → PROCESSING)
❌ Closed → Closed: NOT Allowed (e.g., DECLINED → REFUNDED)

Update Rules Execution

When a transaction status is changed, the endpoint automatically:

Validates the transition - Ensures the new status is valid and transition is allowed
Updates the status - Changes the transaction status in the database
Executes update rules - Runs all rules with trigger: 'updated' in their scope
Updates risk score - Re-calculates risk based on rule results
Returns updated transaction - Returns the complete transaction with new risk assessment

Rules Trigger

The endpoint uses the trigger_transaction_updated mode, which executes all rules configured with the updated trigger. Example rule scope configuration:

{
  "scope": {
    "triggers": ["updated"],
    "targetEntityTypes": ["transaction"]
  }
}

Complete Request Examples

Approve a Suspended Transaction

curl -X PATCH http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000/changeStatus \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "SUCCESSFUL"
  }'

Decline a Transaction Under Review

curl -X PATCH http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000/changeStatus \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "DECLINED"
  }'

Suspend a Transaction for Manual Review

curl -X PATCH http://api.gu1.ai/transactions/550e8400-e29b-41d4-a716-446655440000/changeStatus \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "SUSPENDED"
  }'

Response

Success Response (200 OK)

{
  "success": true,
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_12345",
    "type": "PAYMENT",
    "status": "SUCCESSFUL",
    "amount": 1500.00,
    "currency": "USD",
    "amountInUsd": 1500.00,
    "origin": {
      "entityId": "customer_001",
      "externalId": "EXT-001",
      "name": "John Doe",
      "country": "US",
      "details": {},
      "type": "person",
      "riskScore": 15.50
    },
    "destination": {
      "entityId": "merchant_002",
      "externalId": "MER-002",
      "name": "Electronics Store",
      "country": "US",
      "details": {},
      "type": "company",
      "riskScore": 8.20
    },
    "riskScore": 22.50,
    "riskFactors": [
      {
        "factor": "status_change",
        "score": 5,
        "description": "Transaction status changed to SUCCESSFUL"
      }
    ],
    "flagged": false,
    "description": "Laptop purchase",
    "category": "electronics",
    "metadata": {},
    "transactedAt": "2024-12-23T14:30:00.000Z",
    "createdAt": "2024-12-23T14:30:00.000Z",
    "updatedAt": "2024-12-23T15:45:00.000Z"
  },
  "statusChanged": {
    "from": "SUSPENDED",
    "to": "SUCCESSFUL"
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "rulesTriggered": 3,
    "executionTimeMs": 245,
    "result": {
      "entityId": "550e8400-e29b-41d4-a716-446655440000",
      "entityType": "transaction",
      "rulesExecuted": [
        {
          "ruleId": "rule_001",
          "ruleName": "High Value Transaction Check",
          "passed": true,
          "score": 5
        }
      ],
      "totalRules": 3,
      "successfulRules": 3,
      "failedRules": 0,
      "overallConfidence": 0.95,
      "riskScore": 22.50,
      "flags": []
    },
    "auditId": "audit_12345",
    "isNewAudit": false
  }
}

Response Fields

success

boolean

Whether the status change was successful

transaction

object

The updated transaction with all its data, including:

id (string) - Transaction UUID
status (string) - New transaction status
origin (object) - Origin party information (nested structure)
- entityId (string) - Origin entity UUID
- name (string) - Origin party name
- country (string) - Origin country
- details (object) - Additional origin details
- type (string) - Origin entity type
- riskScore (number) - Origin entity risk score
destination (object) - Destination party information (nested structure)
- entityId (string) - Destination entity UUID
- name (string) - Destination party name
- country (string) - Destination country
- details (object) - Additional destination details
- type (string) - Destination entity type
- riskScore (number) - Destination entity risk score
riskScore (number) - Updated risk score after re-evaluation
riskFactors (array) - Updated risk factors
flagged (boolean) - Updated flag status
updatedAt (string) - Timestamp of the update

statusChanged

object

Information about the status transition:

from (string) - Previous status
to (string) - New status

rulesResult

object

Complete result of update rules execution (RulesExecutionResult):

success (boolean) - Whether rules executed successfully
executed (boolean) - Whether any rules were executed
result (object | undefined) - Entity analysis result with rule execution details
rulesTriggered (number | undefined) - Number of rules that were executed
rulesExecutionSummary (object | undefined) - When rules ran, detailed summary; see below
executionTimeMs (number | undefined) - Execution time in milliseconds
error (string | undefined) - Error message if execution failed
auditId (string | undefined) - Audit log ID
isNewAudit (boolean | undefined) - Whether a new audit was created
warnings (array | undefined) - Array of warning messages
metadata (object | undefined) - Additional metadata including coverage summary, missing fields, and recommendations

rulesExecutionSummary

object

At the root of the response (same as transactions API). Same value as rulesResult.rulesExecutionSummary. Only present when rules ran. Summary of which rules matched (hit) vs did not match (no hit), executed actions, and total score.

rulesHit (array) - Rules whose conditions were met. Each item: name, description, score, priority, category, status, conditions, actions.
rulesNoHit (array) - Rules evaluated but conditions not met. Same structure as rulesHit.
actionsExecuted (object) - Aggregated executed actions: alerts, suggestion, status, assignedUser, customKeys (array of strings, optional) — custom action keys from rules that matched; for integrations/workflows.
totalScore (number) - Sum of score of all rules that hit (excluding shadow).

Error Responses

400 Bad Request - Invalid Status

{
  "error": "Invalid status",
  "validStatuses": [
    "CREATED",
    "PROCESSING",
    "SUSPENDED",
    "SENT",
    "EXPIRED",
    "DECLINED",
    "REFUNDED",
    "SUCCESSFUL"
  ]
}

400 Bad Request - Invalid Transition

{
  "error": "Cannot transition from closed status to open status",
  "currentStatus": "SUCCESSFUL",
  "requestedStatus": "PROCESSING",
  "message": "Transaction is in a closed state (SUCCESSFUL) and cannot be reopened"
}

404 Not Found

{
  "error": "Transaction not found"
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

500 Internal Server Error

{
  "error": "Failed to change transaction status",
  "details": "Internal server error message"
}

Use Cases

1. Manual Review Workflow

// Step 1: Suspend suspicious transaction
await changeStatus(transactionId, 'SUSPENDED');

// Step 2: Analyst reviews transaction
// ... manual review process ...

// Step 3: Approve or decline based on review
if (approved) {
  await changeStatus(transactionId, 'SUCCESSFUL');
} else {
  await changeStatus(transactionId, 'DECLINED');
}

2. Automated Compliance Check

// Transaction created with CREATED status
const transaction = await createTransaction({...});

// Run additional compliance checks
const complianceResult = await runComplianceChecks(transaction.id);

if (complianceResult.passed) {
  // Move to processing
  await changeStatus(transaction.id, 'PROCESSING');

  // Complete transaction
  await changeStatus(transaction.id, 'SUCCESSFUL');
} else {
  // Decline due to compliance issues
  await changeStatus(transaction.id, 'DECLINED');
}

3. Fraud Detection Response

// Monitor transaction updates
if (fraudDetected) {
  // Immediately suspend transaction
  await changeStatus(transactionId, 'SUSPENDED');

  // Create alert for investigation
  await createAlert({
    transactionId,
    type: 'fraud_suspected',
    severity: 'high'
  });

  // After investigation, take action
  if (confirmed) {
    await changeStatus(transactionId, 'DECLINED');
  } else {
    await changeStatus(transactionId, 'SUCCESSFUL');
  }
}

4. Bulk Status Updates

// Update multiple transactions in parallel
const suspendedTransactions = await getTransactionsByStatus('SUSPENDED');

const results = await Promise.allSettled(
  suspendedTransactions.map(async (txn) => {
    if (shouldApprove(txn)) {
      return await changeStatus(txn.id, 'SUCCESSFUL');
    } else if (shouldDecline(txn)) {
      return await changeStatus(txn.id, 'DECLINED');
    }
  })
);

console.log(`Updated ${results.filter(r => r.status === 'fulfilled').length} transactions`);

Best Practices

Validate before changing - Always check the current status before attempting a status change to avoid unnecessary API calls
Handle transition errors - Implement proper error handling for invalid transitions, as closed transactions cannot be reopened
Use appropriate statuses - Choose the correct status that reflects the actual business state of the transaction
Monitor rule execution - Pay attention to the rulesResult object to ensure update rules are triggering as expected and check execution details, warnings, and metadata
Implement audit logging - Track all status changes in your system for compliance and debugging purposes
Bulk updates - When updating multiple transactions, use Promise.allSettled() to continue processing even if some updates fail
Webhook integration - Consider setting up webhooks to receive notifications when status changes trigger important rules
Testing state transitions - Test all possible state transitions in your development environment before deploying to production

Create Transaction

Create new transactions

Get Transaction

Retrieve transaction details

Rules Configuration

Configure update rules

Overview

Back to overview

Getting Started

Use Cases

Webhooks

Person

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Endpoint