API Reference - Transaction Monitoring

• 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

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

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

• 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

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

• 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)

• 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

• 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

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

{
  "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"
  }
}

• 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

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

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

• 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

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

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

• 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

{
  "channel": "mobile_app"
}

• 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

{
  "reason": "INSUFFICIENT_FUNDS"
}

• 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

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

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

{
  "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"
}

• 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)

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

• 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”)

• 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 (string) - Browser name (e.g., “Chrome”, “Safari”, “Firefox”)
• browserVersion (string) - Browser version
• userAgent (string) - Full user agent string

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

• 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

• deviceFingerprint (string) - Unique device fingerprint hash for tracking

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

{
  "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"
}

• 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

​

tags (object) - Key-Value Categorization System

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

• 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”

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

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

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

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

​

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

{
  "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
}

• 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

• 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.