Create Transaction

Endpoints

Create Transaction

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

Creates a new transaction with automatic currency conversion to USD and optional rule execution for real-time risk assessment. Features:

Automatic currency conversion using real-time exchange rates
Caching with 1-minute TTL for performance
Circuit breaker pattern for resilience
Optional automatic rule execution (default: true)
Multi-currency support (150+ currencies)
Flexible payment information within origin and destination details

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, and payment details).Type: object (optional, validated structure)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

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 info, device, and payment details).Type: object (optional, validated structure)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

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.

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

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"
  },
  "rulesResult": {
    "success": true,
    "rulesTriggered": 3,
    "alerts": [
      {
        "id": "alert_001",
        "severity": "low",
        "type": "velocity_check",
        "message": "User has 3 transactions in the last hour"
      }
    ],
    "riskScore": 25.50,
    "decision": "APPROVE"
  }
}

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

rulesResult

object

Result of rules execution (only present if executeRules was true), including:

success (boolean) - Whether rules executed successfully
rulesTriggered (number) - Number of rules that were triggered
alerts (array) - Alerts generated by rules
riskScore (number) - Final calculated risk score
decision (string) - Final decision (APPROVE, REJECT, HOLD, REVIEW_REQUIRED)

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

Best Practices

Use consistent external IDs - Your externalId should be unique across your system to prevent duplicates and enable proper tracking
Include entity references - Link transactions to entities (originEntityId, destinationEntityId) for better risk assessment and relationship analysis
Provide comprehensive metadata - Include relevant business context in the metadata field for custom rules and future analysis
Set transactedAt accurately - Always provide the actual transaction timestamp, don’t rely on the default (current time)
Handle currency conversion gracefully - Be aware that currency conversion may fail; check for amountInUsd and exchangeRate in the response
Execute rules strategically - Use executeRules: false for bulk imports or when you want to defer risk assessment
Monitor risk scores - Set up alerts for transactions with high risk scores or flagged status
Implement error handling - Handle validation errors and retry transient failures with exponential backoff
Use payment details - Provide detailed payment information within originDetails.paymentDetails and destinationDetails.paymentDetails for better fraud detection and transaction context

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

Person

Company

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Endpoints