API Reference

Endpoint

POST /transaction/analyze

Analyzes a financial transaction in real-time, executing configured rules and returning a decision along with alerts and recommended actions.

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
X-Organization-ID: your-org-id

Request Body

Transaction Core

{
  "transaction": {
    "externalId": "string",        // Your unique transaction ID
    "type": "string",               // PAYMENT, TRANSFER, WITHDRAWAL, DEPOSIT, REFUND
    "amount": number,               // Transaction amount
    "currency": "string",           // ISO 4217 currency code (USD, BRL, EUR, etc.)
    "timestamp": "string",          // ISO 8601 timestamp
    "originEntityId": "string",     // Origin entity ID (optional)
    "destinationEntityId": "string", // Destination entity ID (optional)
    "mccCode": "string",            // Merchant Category Code (optional)
    "description": "string",        // Transaction description (optional)
    "tags": ["string"],             // Custom tags (optional)
    "metadata": {}                  // Custom metadata (optional)
  }
}

Transaction Types

Type	Description
`PAYMENT`	Purchase or payment to merchant
`TRANSFER`	Transfer between accounts/users
`WITHDRAWAL`	Cash withdrawal or account debit
`DEPOSIT`	Deposit or account credit
`REFUND`	Refund of a previous transaction
`CHARGEBACK`	Chargeback dispute
`REVERSAL`	Transaction reversal
`FEE`	Fee or commission charge
`ADJUSTMENT`	Balance adjustment
`OTHER`	Other transaction type

Entity References

{
  "originEntityId": "customer_maria_001",
  "destinationEntityId": "merchant_loja_002"
}

Entities can be:

Pre-existing in your gu1 account
Created automatically during transaction analysis
Referenced by your external ID

Payment Details

{
  "origin": {
    "paymentMethod": "CARD",
    "accountType": "PERSONAL",
    "accountId": "4532********1234",
    "bankCode": "001",
    "cardBrand": "VISA"
  },
  "destination": {
    "paymentMethod": "BANK_ACCOUNT",
    "accountType": "BUSINESS",
    "accountId": "1234567890",
    "bankCode": "033"
  }
}

Payment Methods

Cards:

CARD - Credit/debit card (generic)
CREDIT_CARD - Credit card
DEBIT_CARD - Debit card
PREPAID_CARD - Prepaid card

Bank Transfers:

BANK_TRANSFER - Generic bank transfer
WIRE - Wire transfer
ACH - ACH transfer (US)
SEPA - SEPA transfer (EU)

Digital Wallets:

WALLET - Generic digital wallet
PAYPAL - PayPal
APPLE_PAY - Apple Pay
GOOGLE_PAY - Google Pay
SAMSUNG_PAY - Samsung Pay
VENMO - Venmo
ZELLE - Zelle

Latin America:

PIX - Brazilian instant payment
CBU - Argentine bank account
CVU - Argentine virtual wallet
DEBIN - Argentine direct debit
SPEI - Mexican instant payment
PSE - Colombian online payment

Cryptocurrency:

CRYPTO - Cryptocurrency (generic)
BITCOIN - Bitcoin
ETHEREUM - Ethereum
STABLECOIN - Stablecoins (USDT, USDC, etc.)

Cash & Other:

CASH - Cash payment
CHECK - Check
MONEY_ORDER - Money order
MOBILE_MONEY - Mobile money (M-Pesa, etc.)
OTHER - Other payment method

Account Types

PERSONAL - Personal account
BUSINESS - Business account
MERCHANT - Merchant account
SAVINGS - Savings account
CHECKING - Checking account
INVESTMENT - Investment account
ESCROW - Escrow account
PREPAID - Prepaid account
OTHER - Other account type

Device Data

{
  "originDeviceData": {
    "deviceId": "device_android_001",
    "ipAddress": "177.20.145.30",
    "userAgent": "Mozilla/5.0...",
    "platform": "android",
    "location": {
      "latitude": -23.550520,
      "longitude": -46.633308,
      "country": "BR",
      "city": "São Paulo",
      "region": "SP"
    }
  }
}

Device Platforms

web - Web browser
ios - iOS app
android - Android app
mobile_web - Mobile browser
api - Direct API call
other - Other platform

MCC Codes

Merchant Category Codes (MCC) classify business types:

{
  "mccCode": "5411"  // Grocery Stores
}

Common examples:

5411 - Grocery Stores
5812 - Restaurants
5999 - Miscellaneous Retail
6011 - ATM/Cash Withdrawal
7995 - Gambling

Tags and Metadata

{
  "tags": ["high_value", "first_transaction", "promotional"],
  "metadata": {
    "campaignId": "summer_2024",
    "referralCode": "FRIEND10",
    "customField": "any_value"
  }
}

Multi-Currency Support

gu1 provides automatic currency conversion for all transactions. Each organization has a configured base currency (default: USD), and all transactions are automatically converted to this base currency for consistent rule evaluation and reporting.

How It Works

Automatic Detection: When a transaction’s currency differs from your organization’s base currency, automatic conversion is triggered
Real-Time Rates: Exchange rates are fetched from our currency service in real-time
Dual Amount Storage: Both original and converted amounts are stored
Rule Evaluation: Rules can use either amount (original) or amountBaseCurrency (converted)

Supported Currencies

150+ currencies supported including:

Major: USD, EUR, GBP, JPY, CHF, CAD, AUD
Latin America: BRL, ARS, MXN, COP, CLP, PEN, UYU
Asia: CNY, INR, KRW, SGD, HKD, THB, MYR
Crypto: BTC, ETH, USDT, USDC
And many more (ISO 4217 standard)

Exchange Rate Sources

Source	Description	When Used
`ms-provider`	Real-time rates from currency microservice	Primary source
`cache-fallback`	Cached rates when service unavailable	Fallback (< 1h old)
`no-conversion`	No conversion needed (same currency)	Same as base
`client-provided`	Custom rate provided by client	Optional override

Response Fields

When currency conversion occurs, the response includes:

{
  "currencyConversion": {
    "originalAmount": 500.00,
    "originalCurrency": "BRL",
    "convertedAmount": 100.00,
    "baseCurrency": "USD",
    "exchangeRate": 0.20,
    "rateSource": "ms-provider",
    "convertedAt": "2024-10-28T14:30:00Z"
  }
}

Using Converted Amounts in Rules

Rules can reference both amounts:

{
  "conditions": [
    {
      "field": "amount",
      "operator": "GREATER_THAN",
      "value": 1000
    }
  ]
}

Or use the converted amount for consistent thresholds:

{
  "conditions": [
    {
      "field": "amountBaseCurrency",
      "operator": "GREATER_THAN",
      "value": 10000
    }
  ]
}

Best Practice: Use amountBaseCurrency in rules to ensure consistent thresholds regardless of transaction currency.

Error Handling

If currency conversion fails:

Transaction processing continues with original amount
currencyConversion field will be omitted from response
Rules using amountBaseCurrency will use original amount as fallback
Error is logged but doesn’t block transaction

Example: Multi-Currency Transaction

{
  "transaction": {
    "externalId": "txn_euro_001",
    "type": "PAYMENT",
    "amount": 850.00,
    "currency": "EUR",
    "timestamp": "2024-10-28T15:00:00Z",
    "originEntityId": "customer_france_001",
    "destinationEntityId": "merchant_usa_001"
  }
}

Response includes conversion:

{
  "success": true,
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "state": "APPROVE"
  },
  "currencyConversion": {
    "originalAmount": 850.00,
    "originalCurrency": "EUR",
    "convertedAmount": 935.00,
    "baseCurrency": "USD",
    "exchangeRate": 1.10,
    "rateSource": "ms-provider",
    "convertedAt": "2024-10-28T15:00:01Z"
  }
}

Complete Request Example

PIX Transfer (Brazil)

curl -X POST https://api.gu1.ai/transaction/analyze \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Organization-ID: your-org-id" \
  -d '{
    "transaction": {
      "externalId": "txn_pix_12345",
      "type": "TRANSFER",
      "amount": 500.00,
      "currency": "BRL",
      "timestamp": "2024-10-28T14:30:00Z",
      "originEntityId": "customer_maria_001",
      "destinationEntityId": "merchant_loja_002",
      "description": "Purchase at Online Store",
      "origin": {
        "paymentMethod": "PIX",
        "accountType": "PERSONAL",
        "accountId": "[email protected]"
      },
      "destination": {
        "paymentMethod": "PIX",
        "accountType": "BUSINESS",
        "accountId": "11222333000144"
      },
      "originDeviceData": {
        "deviceId": "device_android_001",
        "ipAddress": "177.20.145.30",
        "platform": "android",
        "location": {
          "latitude": -23.550520,
          "longitude": -46.633308,
          "country": "BR",
          "city": "São Paulo"
        }
      },
      "tags": ["pix", "retail"],
      "metadata": {
        "storeId": "store_002",
        "orderId": "order_789"
      }
    }
  }'

High-Risk Card Payment

const response = await fetch('https://api.gu1.ai/transaction/analyze', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json',
    'X-Organization-ID': 'your-org-id'
  },
  body: JSON.stringify({
    transaction: {
      externalId: 'txn_card_67890',
      type: 'PAYMENT',
      amount: 1250.00,
      currency: 'USD',
      timestamp: new Date().toISOString(),
      originEntityId: 'customer_john_003',
      destinationEntityId: 'merchant_electronics_001',
      mccCode: '5732', // Electronics Stores
      description: 'Laptop purchase',
      origin: {
        paymentMethod: 'CARD',
        accountType: 'PERSONAL',
        accountId: '4532********8765',
        cardBrand: 'VISA'
      },
      destination: {
        paymentMethod: 'BANK_ACCOUNT',
        accountType: 'BUSINESS',
        accountId: '9876543210'
      },
      originDeviceData: {
        deviceId: 'device_web_chrome_001',
        ipAddress: '185.220.101.45',
        userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64)...',
        platform: 'web',
        location: {
          latitude: 55.7558,
          longitude: 37.6173,
          country: 'RU',
          city: 'Moscow'
        }
      },
      tags: ['high_value', 'electronics'],
      metadata: {
        sessionId: 'sess_abc123',
        isFirstTransaction: true
      }
    }
  })
});

const result = await response.json();
console.log(result);

Python Example

import requests
from datetime import datetime

url = "https://api.gu1.ai/transaction/analyze"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json",
    "X-Organization-ID": "your-org-id"
}

payload = {
    "transaction": {
        "externalId": "txn_python_001",
        "type": "TRANSFER",
        "amount": 750.50,
        "currency": "EUR",
        "timestamp": datetime.utcnow().isoformat() + "Z",
        "originEntityId": "user_alice_001",
        "destinationEntityId": "user_bob_002",
        "origin": {
            "paymentMethod": "SEPA",
            "accountType": "PERSONAL",
            "accountId": "ES1234567890123456789012"
        },
        "destination": {
            "paymentMethod": "SEPA",
            "accountType": "PERSONAL",
            "accountId": "DE89370400440532013000"
        },
        "originDeviceData": {
            "deviceId": "device_ios_001",
            "ipAddress": "89.145.123.45",
            "platform": "ios",
            "location": {
                "country": "ES",
                "city": "Madrid"
            }
        }
    }
}

response = requests.post(url, json=payload, headers=headers)
result = response.json()

print(f"Decision: {result['decision']}")
print(f"Risk Score: {result['riskScore']}")

Response

Success Response (200 OK)

{
  "transactionId": "550e8400-e29b-41d4-a716-446655440000",
  "decision": "APPROVE",
  "riskScore": 25,
  "alerts": [
    {
      "id": "alert_001",
      "severity": "low",
      "type": "velocity_check",
      "message": "User has 3 transactions in the last hour",
      "ruleId": "rule_velocity_001",
      "ruleName": "Transaction Velocity Monitor"
    }
  ],
  "actions": [
    {
      "type": "log_transaction",
      "priority": "normal"
    }
  ],
  "executionMetadata": {
    "syncRulesExecuted": 5,
    "asyncRulesExecuted": 12,
    "executionTimeMs": 234,
    "rulesMatched": 1
  },
  "currencyConversion": {
    "originalCurrency": "BRL",
    "baseCurrency": "USD",
    "originalAmount": 500.00,
    "convertedAmount": 100.00,
    "exchangeRate": 0.20,
    "conversionTimestamp": "2024-10-28T14:30:00Z"
  },
  "entitiesResolved": {
    "origin": {
      "id": "customer_maria_001",
      "type": "customer",
      "isNew": false
    },
    "destination": {
      "id": "merchant_loja_002",
      "type": "merchant",
      "isNew": false
    }
  }
}

Decision Types

Decision	Description	Recommended Action
`APPROVE`	Transaction approved	Process normally
`REJECT`	Transaction rejected	Block transaction
`HOLD`	Transaction on hold	Manual review required
`REVIEW_REQUIRED`	Needs review	Queue for analyst
`ADDITIONAL_AUTH_REQUIRED`	Need more verification	Request 2FA/3DS

Risk Score

Risk score from 0 to 100:

0-30: Low risk (green)
31-60: Medium risk (yellow)
61-80: High risk (orange)
81-100: Critical risk (red)

Alert Severity Levels

low - Informational, no immediate action
medium - Monitor, may need attention
high - Requires review within hours
critical - Immediate action required

Error Responses

400 Bad Request

{
  "error": "VALIDATION_ERROR",
  "message": "Invalid transaction payload",
  "details": [
    {
      "field": "transaction.amount",
      "message": "Amount must be a positive number"
    },
    {
      "field": "transaction.currency",
      "message": "Currency must be a valid ISO 4217 code"
    }
  ]
}

401 Unauthorized

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

429 Too Many Requests

{
  "error": "RATE_LIMIT_EXCEEDED",
  "message": "Too many requests",
  "retryAfter": 60
}

500 Internal Server Error

{
  "error": "INTERNAL_ERROR",
  "message": "An unexpected error occurred",
  "requestId": "req_abc123"
}

Rate Limiting

Standard Plan: 1,000 requests per minute
Professional Plan: 5,000 requests per minute
Enterprise Plan: Custom limits

Rate limit headers:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 987
X-RateLimit-Reset: 1635780000

Idempotency

Use the Idempotency-Key header to prevent duplicate processing:

curl -X POST https://api.gu1.ai/transaction/analyze \
  -H "Idempotency-Key: txn_unique_key_123" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  ...

Idempotency keys are stored for 24 hours.

Best Practices

Always include device data - Improves fraud detection accuracy
Use external IDs consistently - Enables proper entity resolution
Include relevant metadata - Useful for custom rules and analysis
Handle all decision types - Don’t just check for APPROVE/REJECT
Implement retry logic - With exponential backoff for failures
Monitor rate limits - Track headers and throttle accordingly
Use idempotency keys - For critical transactions to prevent duplicates

Next Steps

Rules Configuration

Learn to create rules

Fraud Detection

Fraud detection examples

AML Monitoring

AML compliance rules

Overview

Back to overview

Getting Started

API Reference

Data Ingestion

Entities

Documents

Know Your Business (KYB)

Know Your Customer (KYC)

Transaction Monitoring

Interactive Tutorials

​Endpoint

​Authentication

​Required Headers

​Request Body

​Transaction Core

​Transaction Types

​Entity References

​Payment Details

​Payment Methods

​Account Types

​Device Data

​Device Platforms

​MCC Codes

​Tags and Metadata

​Multi-Currency Support

​How It Works

​Supported Currencies

​Exchange Rate Sources

​Response Fields

​Using Converted Amounts in Rules

​Error Handling

​Example: Multi-Currency Transaction

​Complete Request Example

​PIX Transfer (Brazil)

​High-Risk Card Payment

​Python Example

​Response

​Success Response (200 OK)

​Decision Types

​Risk Score

​Alert Severity Levels

​Error Responses

​400 Bad Request

​401 Unauthorized

​429 Too Many Requests

​500 Internal Server Error

​Rate Limiting

​Idempotency

​Best Practices

​Next Steps