API Reference - Transaction Monitoring

Canonical endpoint reference

The official reference for POST /transactions (response shape, errors, all fields) is: Create transaction (API Reference → Transactions) There you’ll find the actual response: transaction is an object (the created transaction), and when rules run, rulesExecutionSummary appears at the response root (see Rules Execution Summary). This page adds use-case context for monitoring: currency conversion, payment-method examples (PIX, card, multi-currency), and detailed field descriptions.

Endpoint: Create Transaction

POST http://api.gu1.ai/transactions

Creates a new transaction. Amounts are converted to USD when currency is not USD. With executeRules: true (default), the rules engine runs and the response includes rulesExecutionSummary at the root when rules execute.

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

Request Body

externalId

string

required

Your unique identifier for this transaction in your systemType: string (min length: 1)

type

string

required

Type of transaction. Options:

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

Type: enum -

'PAYMENT' | 'TRANSFER' | 'WITHDRAWAL' | 'DEPOSIT' | 'REFUND' | 'CHARGEBACK' | 'REVERSAL' | 'FEE' | 'ADJUSTMENT' | 'OTHER'

status

string

default:"CREATED"

Transaction status. Follows a state machine with open and closed states.Open States (can transition to other states):

CREATED - Transaction created (default)
PROCESSING - Transaction being processed
SUSPENDED - Transaction temporarily suspended

Closed States (final, cannot transition back to open states):

SENT - Transaction sent/transmitted
EXPIRED - Transaction expired
DECLINED - Transaction declined/rejected
REFUNDED - Transaction refunded/reversed
SUCCESSFUL - Transaction completed successfully

amount

number

required

Transaction amount (must be positive)Type: number (> 0)

currency

string

required

ISO 4217 currency code (e.g., “USD”, “BRL”, “EUR”)Type: string (length: 3)

paymentMethod

string

Payment method used for the transactionType: string (enum, optional)Possible Values:

CARD - Credit or debit card payment
ACH - Automated Clearing House (US bank transfer)
PIX - Brazilian instant payment system
TED - Brazilian wire transfer (Transferência Eletrônica Disponível)
BOLETO - Brazilian payment slip
WALLET - Digital wallet (PayPal, Venmo, etc.)
SWIFT - SWIFT international wire transfer
IBAN - IBAN-based bank transfer
CBU - Argentine bank account (Clave Bancaria Uniforme)
CVU - Argentine virtual account (Clave Virtual Uniforme)
DEBIN - Argentine instant debit system
GENERIC_BANK_ACCOUNT - Generic bank account transfer
MPESA - M-Pesa mobile money (Kenya)
UPI - Unified Payments Interface (India)
CHECK - Check payment
ECHECK - Electronic check
QR_CODE - QR code payment
ONLINE_PAYMENT - Generic online payment
WITHDRAWAL_ORDER - Withdrawal order

Example: "PIX" or "CARD"

originEntityId

string

UUID of the origin entity (sender) in gu1 systemType: string (uuid, optional)

originExternalId

string

Your external ID for the origin entityType: string (optional)

originName

string

Name of the origin entity (sender)Type: string (max length: 500, optional)

originCountry

string

ISO 3166-1 alpha-2 country code of origin entityType: string (length: 2, optional)

originDetails

object

Contextual information about the origin of the transaction (device, geolocation, account, security flags). These fields match the API schema; you can also send additional custom fields (e.g. nested paymentDetails or any other keys) and they will be stored.Type: object (optional, validated structure; extra keys allowed)Key Difference:

originCountry (direct field) = Entity’s country
originDetails.country = Device/IP country at transaction time (can differ if traveling)

Supported Fields:Device/Technical:

deviceId (string) - Device identifier
deviceFingerprint (string) - Device fingerprint hash
deviceType (enum) - mobile | desktop | tablet | pos | atm
userAgent (string) - Browser user agent
ipAddress (string) - IP address (validated format)

Geolocation:

country (string) - ISO 2-letter code
city (string) - City name
region (string) - State/province
latitude (number) - Latitude (-90 to 90)
longitude (number) - Longitude (-180 to 180)
timezone (string) - Timezone identifier

Payment Details (nested object):

paymentDetails (object) - Payment-specific information for the origin. You can send any payment-related fields here:
- Bank/Account Details:
  - accountNumber (string) - Account number
  - accountType (enum) - checking | savings | business | personal
  - bankCode (string) - Bank code
  - bankName (string) - Bank name
  - routingNumber (string) - Routing number (US)
  - swiftCode (string) - SWIFT/BIC code
  - iban (string) - IBAN (International Bank Account Number)
- PIX Details (Brazil):
  - pixKey (string) - PIX key
  - pixType (enum) - PIX key type: email | phone | cpf | cnpj | random
- Card Details:
  - cardLast4 (string) - Last 4 digits of card
  - cardBrand (string) - Card brand (Visa, Mastercard, Amex, etc.)
  - cardholderName (string) - Name on card
  - cardBin (string) - First 6 digits of card (BIN)
  - cardType (enum) - credit | debit | prepaid
  - cardCountry (string) - Card issuing country (ISO 2-letter)
  - cardExpiry (string) - Expiration date (MM/YY)
  - cardFingerprint (string) - Unique card fingerprint/hash for tracking
- Crypto Details:
  - walletAddress (string) - Cryptocurrency wallet address
  - walletType (string) - Wallet type (e.g., “metamask”, “coinbase”)
  - blockchain (string) - Blockchain network (e.g., “ethereum”, “bitcoin”)
  - tokenSymbol (string) - Token symbol (e.g., “ETH”, “BTC”, “USDT”)
- Wallet/Digital Payment:
  - walletId (string) - Digital wallet identifier
  - walletProvider (string) - Wallet provider (e.g., “paypal”, “venmo”, “cashapp”)
  - walletEmail (string) - Email associated with wallet
- And any other payment-related fields you need

Reference: For suggested structures by payment method (card, PIX, CBU/CVU, SPEI, PSE, DEBIN, crypto, wallet, cash, check, etc.) see Payment Details Schema. Nothing is enforced; custom fields are allowed.Security Flags:

isVpn (boolean) - VPN detected
isTor (boolean) - Tor network detected
isProxy (boolean) - Proxy detected
governmentAccount (boolean) - Government account flag

Example:

{
  "deviceType": "mobile",
  "ipAddress": "189.123.45.67",
  "country": "BR",
  "city": "São Paulo",
  "isVpn": false,
  "paymentDetails": {
    "accountNumber": "12345",
    "accountType": "personal",
    "bankName": "Banco do Brasil",
    "pixKey": "user@email.com",
    "pixType": "email"
  }
}

Custom fields are allowed - the system will validate known fields and preserve custom ones.

destinationEntityId

string

UUID of the destination entity (receiver) in gu1 systemType: string (uuid, optional)

destinationExternalId

string

Your external ID for the destination entityType: string (optional)

destinationName

string

Name of the destination entity (receiver)Type: string (max length: 500, optional)

destinationCountry

string

ISO 3166-1 alpha-2 country code of destination entityType: string (length: 2, optional)

destinationDetails

object

Contextual information about the destination of the transaction (merchant, device, geolocation, account, risk flags). These fields match the API schema; you can also send additional custom fields (e.g. nested paymentDetails or any other keys) and they will be stored.Type: object (optional, validated structure; extra keys allowed)Supported Fields:Merchant Info:

mcc (string) - Merchant Category Code (4 digits, ISO 18245)
mccDescription (string) - MCC description (e.g., “Restaurants”)
merchantId (string) - Merchant identifier
merchantName (string) - Merchant name
merchantType (string) - Merchant type/category

Device/Technical:

deviceId (string) - Device identifier
deviceType (enum) - pos | online | mobile | atm
ipAddress (string) - IP address (validated format)

Geolocation:

country (string) - ISO 2-letter code
city (string) - City name
region (string) - State/province

Payment Details (nested object):

paymentDetails (object) - Payment-specific information for the destination. You can send any payment-related fields here:
- Bank/Account Details:
  - accountNumber (string) - Destination account number
  - accountType (enum) - checking | savings | business | merchant
  - bankCode (string) - Bank code
  - bankName (string) - Bank name
  - routingNumber (string) - Routing number (US)
  - swiftCode (string) - SWIFT/BIC code
  - iban (string) - IBAN (International Bank Account Number)
- PIX Details (Brazil):
  - pixKey (string) - PIX key
  - pixType (enum) - PIX key type: email | phone | cpf | cnpj | random
- Card Details:
  - cardLast4 (string) - Last 4 digits of card
  - cardBrand (string) - Card brand (Visa, Mastercard, Amex, etc.)
  - cardholderName (string) - Name on card
  - cardBin (string) - First 6 digits of card (BIN)
  - cardType (enum) - credit | debit | prepaid
  - cardCountry (string) - Card issuing country (ISO 2-letter)
  - cardExpiry (string) - Expiration date (MM/YY)
  - cardFingerprint (string) - Unique card fingerprint/hash for tracking
- Crypto Details:
  - walletAddress (string) - Cryptocurrency wallet address
  - walletType (string) - Wallet type (e.g., “metamask”, “coinbase”)
  - blockchain (string) - Blockchain network (e.g., “ethereum”, “bitcoin”)
  - tokenSymbol (string) - Token symbol (e.g., “ETH”, “BTC”, “USDT”)
- Wallet/Digital Payment:
  - walletId (string) - Digital wallet identifier
  - walletProvider (string) - Wallet provider (e.g., “paypal”, “venmo”, “cashapp”)
  - walletEmail (string) - Email associated with wallet
- And any other payment-related fields you need

Reference: For suggested structures by payment method see Payment Details Schema. Nothing is enforced; custom fields are allowed.Risk Flags:

cryptoExchange (boolean) - Is cryptocurrency exchange
highRisk (boolean) - High risk merchant flag
privateSector (boolean) - Private sector flag

Example:

{
  "mcc": "5812",
  "mccDescription": "Restaurants",
  "merchantName": "Restaurant ABC",
  "country": "US",
  "highRisk": false,
  "paymentDetails": {
    "accountNumber": "98765",
    "accountType": "merchant",
    "bankName": "Bradesco"
  }
}

Custom fields are allowed - the system will validate known fields and preserve custom ones.

channel

string

The channel through which the transaction was initiated (max 50 characters).Type: string (max length: 50, optional)Common Examples:

mobile_app - Mobile application
web_browser - Web browser
pos_terminal - Point of sale terminal
api - Direct API integration
atm - ATM machine
phone_banking - Phone banking
branch - Physical branch
call_center - Call center
partner_api - Partner integration

Use Case: Helps segment transactions by origin channel for risk analysis, reporting, and business intelligence.Example:

{
  "channel": "mobile_app"
}

reason

string

Optional reason for the transaction outcome (e.g. decline, failure, limit exceeded). The client can send any value from the transaction_reason_type enum. If omitted, the system uses WITHOUT_REASON. Not required — existing integrations remain valid.Type: string (enum, optional, default: WITHOUT_REASON)Common values (full enum has 60+ values):

WITHOUT_REASON - No specific reason (default when omitted)
INSUFFICIENT_FUNDS - Insufficient funds
LIMIT_EXCEEDED, DAILY_LIMIT_EXCEEDED, MONTHLY_LIMIT_EXCEEDED, TRANSACTION_LIMIT_EXCEEDED
ACCOUNT_BLOCKED, ACCOUNT_FROZEN, ACCOUNT_CLOSED
CARD_EXPIRED, CARD_BLOCKED, CARD_LOST_OR_STOLEN, INVALID_CARD, INVALID_ACCOUNT
FRAUD_SUSPECTED, COMPLIANCE_BLOCK, SANCTIONS_MATCH, AML_ALERT, RISK_SCORE_THRESHOLD
MERCHANT_BLOCKED, COUNTRY_RESTRICTION, CURRENCY_NOT_SUPPORTED, CHANNEL_NOT_ALLOWED
SYSTEM_ERROR, TIMEOUT, INVALID_AMOUNT, KYC_PENDING, KYC_REJECTED
EXPIRED, CANCELLED_BY_USER, CANCELLED_BY_MERCHANT, REFUSED_BY_ISSUER, DO_NOT_HONOR
INVALID_PIN, PIN_TRIES_EXCEEDED, INSUFFICIENT_LIQUIDITY, VALIDATION_FAILED, OTHER

Full list: See Transaction Reason Enum for all 60+ allowed values.Example:

{
  "reason": "INSUFFICIENT_FUNDS"
}

locationDetails

object

Geographic location information where the transaction occurred. Useful for fraud detection, geographic risk analysis, and compliance reporting.Type: object (optional)Supported Fields:Address Information:

country (string) - ISO 3166-1 alpha-2 country code (e.g., “US”, “BR”, “AR”)
countryName (string) - Full country name
city (string) - City name
region (string) - State or province
address (string) - Full address
street (string) - Street name
streetNumber (string) - Street number
postalCode (string) - Postal/ZIP code
neighborhood (string) - Neighborhood or district

Coordinates (for map visualization):

latitude (number) - Latitude coordinate (-90 to 90)
longitude (number) - Longitude coordinate (-180 to 180)

Additional Information:

timezone (string) - IANA timezone (e.g., “America/Sao_Paulo”)
placeId (string) - Google Places ID or similar identifier

Example:

{
  "country": "BR",
  "countryName": "Brazil",
  "city": "São Paulo",
  "region": "SP",
  "address": "Av. Paulista, 1578",
  "street": "Av. Paulista",
  "streetNumber": "1578",
  "postalCode": "01310-200",
  "latitude": -23.5505,
  "longitude": -46.6333,
  "timezone": "America/Sao_Paulo"
}

Use Cases:

Fraud Detection: Identify transactions from unusual locations or high-risk countries
Geographic Analysis: Analyze transaction patterns by region
Compliance: Track cross-border transactions for regulatory reporting
Velocity Rules: Detect impossible travel (same user in different locations in short time)

deviceDetails

object

Device information for the transaction. Critical for fraud detection, device fingerprinting, and security analysis.Type: object (optional)Supported Fields:Device Identification:

deviceId (string) - Unique device identifier
externalId (string) - Your external device ID

Platform and Operating System:

platform (enum) - Device platform: android, ios, web, desktop, mobile, tablet, pos, atm
osName (string) - Operating system name (e.g., “Android”, “iOS”, “Windows”, “macOS”)
osVersion (string) - OS version (e.g., “13.0”, “16.4”)

Device Information:

manufacturer (string) - Device manufacturer (e.g., “Samsung”, “Apple”)
model (string) - Device model (e.g., “Galaxy S22”, “iPhone 14”)
brand (string) - Device brand
deviceName (string) - User-assigned device name

Browser Information (for web platform):

browser (string) - Browser name (e.g., “Chrome”, “Safari”, “Firefox”)
browserVersion (string) - Browser version
userAgent (string) - Full user agent string

Security Flags:

isEmulator (boolean) - Whether device is an emulator
isRooted (boolean) - Whether device is rooted (Android)
isJailbroken (boolean) - Whether device is jailbroken (iOS)

Network Information:

ipAddress (string) - IP address (validated format)
isVpn (boolean) - Whether connection is through VPN
isTor (boolean) - Whether connection is through Tor
isProxy (boolean) - Whether connection is through proxy

Device Fingerprinting:

deviceFingerprint (string) - Unique device fingerprint hash for tracking

Additional Details:

screenResolution (string) - Screen resolution (e.g., “1920x1080”)
language (string) - Device language
timezone (string) - Device timezone

Example:

{
  "platform": "mobile",
  "osName": "Android",
  "osVersion": "13",
  "manufacturer": "Samsung",
  "model": "Galaxy S22",
  "brand": "Samsung",
  "ipAddress": "192.168.1.1",
  "isVpn": false,
  "isTor": false,
  "isEmulator": false,
  "isRooted": false,
  "deviceFingerprint": "abc123def456...",
  "screenResolution": "1080x2400",
  "language": "pt-BR",
  "timezone": "America/Sao_Paulo"
}

Use Cases:

Fraud Detection: Identify suspicious devices (emulators, rooted devices, VPN usage)
Device Fingerprinting: Track unique devices across transactions for behavioral analysis
Security Analysis: Detect anomalies in device patterns (new device, impossible device velocity)
Compliance: Document device information for audit trails
User Experience: Personalize experience based on device type and capabilities

description

string

Transaction descriptionType: string (max length: 1000, optional)

`tags` (object) - Key-Value Categorization System

The tags field allows you to add custom key-value pairs for flexible categorization, filtering, and workflow management. This is particularly useful for:

Custom filtering in dashboards and reports
Triggering specific business logic
Tracking review status
Categorizing by risk level or source
Custom workflow states

Format: { "key1": "value1", "key2": "value2" }Common Tag Patterns:

risk_level (string) - “low”, “medium”, “high”, “critical”
source (string) - “api”, “web”, “mobile”, “batch”, “import”
channel (string) - “online”, “branch”, “atm”, “call_center”, “partner”
reviewed (boolean) - false (pending review), true (reviewed)
category (string) - “payroll”, “supplier”, “refund”, “investment”, “loan”, “bill_payment”
priority (string) - “low”, “normal”, “high”, “urgent”
team (string) - “compliance”, “fraud”, “support”, “operations”
campaign (string) - Marketing or business campaign identifier
approved_by (string) - User or system that approved
requires_approval (boolean) - Manual approval required
customer_segment (string) - “vip”, “regular”, “new”, “dormant”
product_type (string) - “savings”, “investment”, “loan”, “transfer”
region (string) - “north”, “south”, “latam”, “emea”, “apac”
business_unit (string) - “retail”, “corporate”, “wealth”, “sme”

Use Case Examples:Example 1: Risk-based workflow

{
  "tags": {
    "risk_level": "high",
    "reviewed": false,
    "requires_approval": true,
    "assigned_to": "fraud_team"
  }
}

Example 2: Business categorization

{
  "tags": {
    "category": "payroll",
    "batch_id": "PAY_2025_01",
    "department": "engineering",
    "cost_center": "R&D"
  }
}

Example 3: Multi-channel tracking

{
  "tags": {
    "source": "mobile_app",
    "channel": "online",
    "campaign": "winter_2025",
    "referral_code": "FRIEND123",
    "first_transaction": true,
    "customer_segment": "new"
  }
}

Example 4: Banking operations

{
  "tags": {
    "channel": "branch",
    "business_unit": "retail",
    "product_type": "loan",
    "region": "latam",
    "requires_approval": true,
    "approved_by": "manager_john"
  }
}

Filtering transactions by tags: You can later filter transactions using these tags in list endpoints or dashboards.

Other Metadata Fields:

purpose (string) - Transaction purpose (e.g., “salary”, “invoice_payment”)
frequency (string) - Transaction frequency (e.g., “monthly”, “one-time”)
contract_number (string) - Contract number (for business payments)
enhanced_due_diligence (boolean) - EDD flag
block_reason (string) - Reason for blocking
compliance_alert (boolean) - Compliance alert flag

Complete Example:

{
  "tags": {
    "risk_level": "medium",
    "source": "api",
    "reviewed": false,
    "category": "invoice_payment"
  },
  "purpose": "supplier_payment",
  "frequency": "monthly",
  "contract_number": "CNT-2025-001",
  "enhanced_due_diligence": false
}

Custom fields beyond the standard ones are allowed and will be preserved.

transactedAt

string

When the transaction occurred (ISO 8601 timestamp). Defaults to current time if not provided.Type: string (ISO 8601 datetime, optional)

executeRules

boolean

default:"true"

Whether to execute risk rules automatically after creating the transactionType: boolean (default: true)

Payment Methods

CARD - Credit/debit card payment
ACH - ACH transfer (US)
PIX - Brazilian instant payment
TED - Brazilian bank transfer (TED)
BOLETO - Brazilian boleto payment
WALLET - Digital wallet payment
SWIFT - International SWIFT transfer
IBAN - IBAN-based transfer
CBU - Argentine bank account (CBU)
CVU - Argentine virtual wallet (CVU)
DEBIN - Argentine direct debit
GENERIC_BANK_ACCOUNT - Generic bank account transfer
MPESA - M-Pesa mobile money
UPI - India UPI payment
CHECK - Physical check
ECHECK - Electronic check
QR_CODE - QR code payment
ONLINE_PAYMENT - Generic online payment
WITHDRAWAL_ORDER - Withdrawal order

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

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 amountInUsd (converted to USD)

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

Conversion data is returned on the transaction object, not in a separate block:

transaction.amount, transaction.currency – original amount and currency
transaction.amountInUsd – converted amount in USD (null if conversion failed or not applicable)
transaction.exchangeRate, transaction.rateSource – rate used and source (e.g. ms-provider)

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": "amountInUsd",
      "operator": "GREATER_THAN",
      "value": 10000
    }
  ]
}

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

Error Handling

If currency conversion fails:

Transaction processing continues with original amount
transaction.amountInUsd and transaction.exchangeRate will be null
Rules using amountInUsd will use original amount as fallback if conversion failed
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 (conversion info is on the transaction):

{
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_euro_001",
    "type": "PAYMENT",
    "amount": 850.00,
    "currency": "EUR",
    "amountInUsd": 935.00,
    "exchangeRate": 1.10,
    "rateSource": "ms-provider",
    "status": "CREATED",
    "riskScore": 25,
    "flagged": false,
    "createdAt": "2024-10-28T15:00:01.000Z",
    "updatedAt": "2024-10-28T15:00:01.000Z"
  },
  "rulesExecutionSummary": null
}

Complete Request Examples

PIX Transfer (Brazil)

curl -X POST http://api.gu1.ai/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "txn_pix_12345",
    "type": "TRANSFER",
    "status": "CREATED",
    "amount": 500.00,
    "currency": "BRL",
    "originEntityId": "customer_maria_001",
    "originName": "Maria Silva",
    "originCountry": "BR",
    "originDetails": {
      "deviceId": "device_123",
      "ipAddress": "189.123.45.67",
      "country": "BR",
      "city": "São Paulo",
      "paymentDetails": {
        "pixKey": "maria.silva@example.com",
        "pixType": "email",
        "bankName": "Banco do Brasil"
      }
    },
    "destinationEntityId": "merchant_loja_002",
    "destinationName": "Loja Online",
    "destinationCountry": "BR",
    "destinationDetails": {
      "merchantId": "MER_002",
      "mcc": "5411",
      "paymentDetails": {
        "accountNumber": "98765",
        "accountType": "merchant",
        "bankName": "Bradesco"
      }
    },
    "description": "Purchase at Online Store",
    "category": "retail",
    "metadata": {
      "storeId": "store_002",
      "orderId": "order_789"
    },
    "transactedAt": "2024-12-23T14:30:00Z",
    "executeRules": true
  }'

Card Payment

curl -X POST http://api.gu1.ai/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "txn_card_67890",
    "type": "PAYMENT",
    "amount": 1250.00,
    "currency": "USD",
    "originEntityId": "customer_john_003",
    "originName": "John Smith",
    "originCountry": "US",
    "originDetails": {
      "deviceId": "device_456",
      "deviceType": "desktop",
      "ipAddress": "198.51.100.42",
      "country": "US",
      "paymentDetails": {
        "cardLast4": "8765",
        "cardBrand": "Visa",
        "expiryMonth": "12",
        "expiryYear": "2027"
      }
    },
    "destinationEntityId": "merchant_electronics_001",
    "destinationName": "Electronics Store",
    "destinationCountry": "US",
    "destinationDetails": {
      "mcc": "5732",
      "merchantId": "MER_ELEC_001",
      "paymentDetails": {
        "accountNumber": "ACC123456",
        "accountType": "merchant"
      }
    },
    "description": "Laptop purchase",
    "category": "electronics",
    "metadata": {
      "sessionId": "sess_abc123",
      "isFirstTransaction": true
    },
    "executeRules": true
  }'

Multi-Currency Transfer

curl -X POST http://api.gu1.ai/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "txn_euro_001",
    "type": "TRANSFER",
    "amount": 750.50,
    "currency": "EUR",
    "originEntityId": "user_alice_001",
    "originName": "Alice Martinez",
    "originCountry": "ES",
    "originDetails": {
      "deviceId": "device_789",
      "ipAddress": "88.22.15.10",
      "country": "ES",
      "city": "Madrid",
      "paymentDetails": {
        "accountNumber": "ES1234567890123456789012",
        "bankName": "Banco Santander",
        "accountType": "personal"
      }
    },
    "destinationEntityId": "user_bob_002",
    "destinationName": "Bob Johnson",
    "destinationCountry": "DE",
    "destinationDetails": {
      "country": "DE",
      "paymentDetails": {
        "accountNumber": "DE89370400440532013000",
        "bankName": "Deutsche Bank",
        "accountType": "personal"
      }
    },
    "description": "International transfer",
    "category": "p2p",
    "executeRules": true
  }'

Response

Full response spec: Create transaction. The API returns transaction as an object (single created transaction).

Success Response (201 Created)

{
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_pix_12345",
    "organizationId": "org_uuid",
    "type": "TRANSFER",
    "status": "CREATED",
    "amount": "500.00",
    "currency": "BRL",
    "amountInUsd": "100.00",
    "exchangeRate": "0.2000000000",
    "rateSource": "ms-provider",
    "rateTimestamp": "2024-12-23T14:30:00.000Z",
    "convertedAt": "2024-12-23T14:30:01.000Z",
    "originEntityId": "customer_maria_001",
    "originExternalId": null,
    "originName": "Maria Silva",
    "originCountry": "BR",
    "originDetails": {
      "deviceId": "device_123",
      "ipAddress": "189.123.45.67",
      "country": "BR",
      "city": "São Paulo",
      "paymentDetails": {
        "pixKey": "maria.silva@example.com",
        "pixType": "email",
        "bankName": "Banco do Brasil"
      }
    },
    "destinationEntityId": "merchant_loja_002",
    "destinationExternalId": null,
    "destinationName": "Loja Online",
    "destinationCountry": "BR",
    "destinationDetails": {
      "merchantId": "MER_002",
      "mcc": "5411",
      "paymentDetails": {
        "accountNumber": "98765",
        "accountType": "merchant",
        "bankName": "Bradesco"
      }
    },
    "riskScore": "25.50",
    "riskFactors": [
      {
        "factor": "velocity_check",
        "score": 15,
        "description": "3 transactions in the last hour"
      }
    ],
    "flagged": false,
    "description": "Purchase at Online Store",
    "category": "retail",
    "metadata": {
      "storeId": "store_002",
      "orderId": "order_789"
    },
    "transactedAt": "2024-12-23T14:30:00.000Z",
    "createdAt": "2024-12-23T14:30:01.000Z",
    "updatedAt": "2024-12-23T14:30:01.000Z"
  },
  "rulesExecutionSummary": {
    "rulesHit": [],
    "rulesNoHit": [],
    "actionsExecuted": {},
    "totalScore": 25
  }
}

Response Fields

transaction

object

The created transaction with all its data including:

id (string) - gu1’s internal UUID
externalId (string) - Your external ID
type (enum) - Transaction type
status (enum) - Transaction status
amount (string) - Original amount (numeric string)
currency (string) - Original currency code (ISO 4217)
amountInUsd (string | null) - Converted amount in USD
exchangeRate (string | null) - Exchange rate used (precision: 10 decimals)
rateSource (string | null) - Source of exchange rate
riskScore (string | null) - Risk score 0-100 (precision: 2 decimals) if rules were executed
riskFactors (array) - Array of risk factors identified
flagged (boolean) - Whether transaction was flagged for review
reason (string | null) - Optional outcome reason (e.g. WITHOUT_REASON, INSUFFICIENT_FUNDS); default WITHOUT_REASON when omitted

rulesExecutionSummary

object

At the root of the response. Only present when executeRules is true and the rules engine ran. Summary of which rules matched (hit) vs did not match (no hit), executed actions, and total score. Omitted when executeRules is false. See Rules Execution Summary for the full structure and a complete example.

rulesHit (array) - Rules whose conditions were met. Each item: name, description, score, priority, category, status (e.g. active, shadow), conditions (array of { field, value, operator? }), actions (alerts, suggestion, status, assignedUser).
rulesNoHit (array) - Rules that were evaluated but conditions were not met. Same structure as rulesHit (includes configured actions, not executed).
actionsExecuted (object) - Aggregated executed actions across all rules that hit: alerts (array of { name?, type?, severity?, description? }), suggestion (BLOCK | SUSPEND | FLAG, highest weight), status (entity status applied, if any), assignedUser ({ userId }, if any), customKeys (array of strings, optional) — custom action keys from rules that matched (e.g. require_kyc, flag_for_review). Present when any matched rule has a custom action with a key; used for integrations/workflows.
totalScore (number) - Sum of score of all rules that hit and are not in shadow status.

Transaction Status Values

The transaction status follows a state machine model with open and closed states:

Open States (Can Transition)

Status	Description	Can Transition To
`CREATED`	Transaction created (initial state)	PROCESSING, SUSPENDED, SENT, EXPIRED, DECLINED, SUCCESSFUL
`PROCESSING`	Transaction being processed	SUSPENDED, SENT, EXPIRED, DECLINED, REFUNDED, SUCCESSFUL
`SUSPENDED`	Transaction temporarily suspended	PROCESSING, SENT, EXPIRED, DECLINED, REFUNDED, SUCCESSFUL

Closed States (Final)

Status	Description	Note
`SENT`	Transaction sent/transmitted	Final state - no further transitions
`EXPIRED`	Transaction expired	Final state - no further transitions
`DECLINED`	Transaction declined/rejected	Final state - no further transitions
`REFUNDED`	Transaction refunded/reversed	Final state - no further transitions
`SUCCESSFUL`	Transaction completed successfully	Final state - no further transitions

Important: Once a transaction reaches a closed state, it cannot transition back to an open state. This ensures transaction integrity and proper audit trails.

Risk Score Ranges

Risk score from 0 to 100 (stored with 2 decimal precision):

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

Currency Conversion Rate Sources

The rateSource field indicates how the exchange rate was obtained:

ms-provider: Real-time rate from currency microservice (primary source)
cache-fallback: Cached rate (< 1h old) when service unavailable
no-conversion: No conversion needed (currency is already USD)
null: Conversion failed or not applicable

Error Responses

400 Bad Request - Validation Error

Example 1: Missing required fields

{
  "error": "Validation failed",
  "details": [
    {
      "path": "externalId",
      "message": "Required",
      "code": "invalid_type"
    },
    {
      "path": "amount",
      "message": "Number must be greater than 0",
      "code": "too_small"
    }
  ]
}

Example 2: Invalid paymentDetails for card (nested in originDetails)

{
  "error": "Validation failed",
  "details": [
    {
      "path": "originDetails.paymentDetails.cardLast4",
      "message": "Card last 4 digits must be exactly 4 characters",
      "code": "invalid_length"
    },
    {
      "path": "originDetails.paymentDetails.cardBrand",
      "message": "Invalid card brand",
      "code": "invalid_string"
    }
  ]
}

Example 3: Invalid PIX details (nested in originDetails)

{
  "error": "Validation failed",
  "details": [
    {
      "path": "originDetails.paymentDetails.pixKey",
      "message": "Required",
      "code": "invalid_type"
    },
    {
      "path": "originDetails.paymentDetails.pixType",
      "message": "Invalid PIX type",
      "code": "invalid_enum_value"
    },
    {
      "path": "originDetails.paymentDetails.bankName",
      "message": "String must contain at least 1 character(s)",
      "code": "too_small"
    }
  ]
}

Example 4: Invalid IP address in originDetails

{
  "error": "Validation failed",
  "details": [
    {
      "path": "originDetails.ipAddress",
      "message": "Invalid IP address format",
      "code": "invalid_string"
    },
    {
      "path": "originDetails.country",
      "message": "Country must be ISO 2 letter code",
      "code": "invalid_length"
    }
  ]
}

400 Bad Request - Missing Organization

{
  "error": "Organization ID and User ID are required"
}

401 Unauthorized

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

500 Internal Server Error

{
  "error": "Failed to create transaction",
  "details": "Database connection error"
}

Next Steps

Rules Configuration

Learn to create rules

Fraud Detection

Fraud detection examples

AML Monitoring

AML compliance rules

Overview

Back to overview

Getting Started

Use Cases

Webhooks

Workflows

Person

Messaging

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Canonical endpoint reference

​Endpoint: Create Transaction

​Authentication

​Required Headers

​Request Body

​tags (object) - Key-Value Categorization System

​Other Metadata Fields:

​Payment Methods

​Account Types

​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 Examples

​PIX Transfer (Brazil)

​Card Payment

​Multi-Currency Transfer

​Response

​Success Response (201 Created)

​Response Fields

​Transaction Status Values

​Open States (Can Transition)

​Closed States (Final)

​Risk Score Ranges

​Currency Conversion Rate Sources

​Error Responses

​400 Bad Request - Validation Error

​400 Bad Request - Missing Organization

​401 Unauthorized

​500 Internal Server Error

​Next Steps

Rules Configuration

Fraud Detection

AML Monitoring

Overview

Canonical endpoint reference

Endpoint: Create Transaction

Authentication

Required Headers

Request Body

`tags` (object) - Key-Value Categorization System

Other Metadata Fields:

Payment Methods

Account Types

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 Examples

PIX Transfer (Brazil)

Card Payment

Multi-Currency Transfer

Response

Success Response (201 Created)

Response Fields

Transaction Status Values

Open States (Can Transition)

Closed States (Final)

Risk Score Ranges

Currency Conversion Rate Sources

Error Responses

400 Bad Request - Validation Error

400 Bad Request - Missing Organization

401 Unauthorized

500 Internal Server Error

Next Steps