Create Transaction

Overview

Creates a new transaction. With executeRules: true (default), the rules engine runs and the response includes rulesResult and rulesExecutionSummary.

Endpoint

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

Authentication

Requires a valid API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Request Body

Required Fields

externalId

string

required

Your unique identifier for this transaction in your system

type

string

required

Type of transaction. Options:

PAYMENT - Payment transaction
TRANSFER - Money transfer
WITHDRAWAL - Cash withdrawal
DEPOSIT - Cash or check deposit
REFUND - Refund transaction
CHARGEBACK - Chargeback
REVERSAL - Transaction reversal
FEE - Service fee
ADJUSTMENT - Balance adjustment
OTHER - Other transaction type

amount

number

required

Transaction amount (must be zero or positive)

currency

string

required

Currency code (3-4 characters, e.g., “USD”, “EUR”, “BRL”)

Optional Fields

status

string

default:"CREATED"

Transaction status. Options:

CREATED - Transaction created (default)
PROCESSING - Being processed
SUSPENDED - Suspended for review
SENT - Successfully sent
EXPIRED - Transaction expired
DECLINED - Declined/rejected
REFUNDED - Refunded
SUCCESSFUL - Completed successfully

paymentMethod

string

Payment method used. Options:

CARD - Credit/debit card
ACH - ACH transfer
PIX - Brazilian PIX
TED - Brazilian TED
BOLETO - Brazilian Boleto
WALLET - Digital wallet
SWIFT - SWIFT transfer
IBAN - IBAN transfer
CBU - Argentine CBU
CVU - Argentine CVU
DEBIN - Argentine DEBIN
GENERIC_BANK_ACCOUNT - Generic bank account
MPESA - M-Pesa
UPI - UPI (India)
CHECK - Check payment
ECHECK - Electronic check
QR_CODE - QR code payment
ONLINE_PAYMENT - Online payment
WITHDRAWAL_ORDER - Withdrawal order

description

string

Transaction description or notes

Origin Entity Fields

originEntityId

string

UUID of the origin entity (sender) in gu1 system

originExternalId

string

Your external ID for the origin entity

originName

string

Name of the origin entity

originCountry

string

ISO 2-letter country code of origin (e.g., “US”, “BR”, “AR”)

originDetails

object

Detailed information about the origin (sender/device). These fields match the API schema; you can also send additional custom fields and they will be stored.Schema fields (all optional):Device/Technical:

deviceId (string) - Unique 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 country code
city (string), region (string), latitude (number), longitude (number), timezone (string)

Account:

accountNumber (string), accountType (enum: ‘checking’, ‘savings’, ‘business’, ‘personal’), bankCode (string), bankName (string)

Security flags:

isVpn (boolean), isTor (boolean), isProxy (boolean), governmentAccount (boolean)

paymentDetails (optional): Nested object with payment-level data (card, PIX, bank, etc.). Not enforced — you can send any keys. See Payment Details Schema for suggested structures by payment method (card, PIX, CBU/CVU, SPEI, PSE, DEBIN, crypto, wallet, cash, check, etc.). Extra and custom fields are allowed.Unknown origin (no entity): When the origin party is not an entity in gu1 (you don’t send originEntityId or originExternalId), you can still improve network graph visualization by sending identifying data in originDetails or originDetails.paymentDetails: taxId (e.g. CPF/CNPJ, digits only) and/or accountNumber (and optionally bankCode). These are optional and for internal use only: we group “pseudo” nodes in the graph by the same taxId or account so the same unknown party appears as one node. Not required — only use when you want better graph flow when one side of the transaction is unknown.

Destination Entity Fields

destinationEntityId

string

UUID of the destination entity (recipient) in gu1 system

destinationExternalId

string

Your external ID for the destination entity

destinationName

string

Name of the destination entity

destinationCountry

string

ISO 2-letter country code of destination (e.g., “US”, “BR”, “AR”)

destinationDetails

object

Detailed information about the destination (merchant/receiver). These fields match the API schema; you can also send additional custom fields and they will be stored.Schema fields (all optional):Merchant:

mcc (string) - Merchant Category Code (4 digits)
mccDescription (string), merchantId (string), merchantName (string), merchantType (string)

Device/Technical:

deviceId (string), deviceType (enum: ‘pos’, ‘online’, ‘mobile’, ‘atm’), ipAddress (string)

Geolocation:

country (string, ISO 2), city (string), region (string)

Account:

accountNumber (string), accountType (enum: ‘checking’, ‘savings’, ‘business’, ‘merchant’), bankCode (string), bankName (string)

Risk flags:

cryptoExchange (boolean), highRisk (boolean), privateSector (boolean)

paymentDetails (optional): Nested object with payment-level data (merchant account, card, PIX, etc.). Not enforced — you can send any keys. See Payment Details Schema for suggested structures by payment method. Extra and custom fields are allowed.Unknown destination (no entity): When the destination party is not an entity in gu1 (you don’t send destinationEntityId or destinationExternalId), you can still improve network graph visualization by sending taxId and/or accountNumber (and optionally bankCode) in destinationDetails or destinationDetails.paymentDetails. Optional; used internally to show “pseudo” nodes in the graph grouped by the same identifier. Not required — only when you want better graph flow when one side is unknown.

Location Details

locationDetails

object

Physical location information for the transaction. Useful for fraud detection and geographic analysis.Address Information:

country (string) - ISO 2-letter country code
countryName (string) - Full country name
city (string) - City name
region (string) - State/Province
address (string) - Full address
street (string) - Street name
streetNumber (string) - Street number
postalCode (string) - Postal/ZIP code
neighborhood (string) - Neighborhood/district

Coordinates (for map visualization):

latitude (number) - GPS latitude (-90 to 90)
longitude (number) - GPS longitude (-180 to 180)

Additional Info:

timezone (string) - Timezone identifier
placeId (string) - Google Places ID or similar

Device Details

deviceDetails

object

Detailed device information for fraud detection and device fingerprinting.Device Identification:

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

Platform and OS:

platform (enum) - Platform: ‘android’, ‘ios’, ‘web’, ‘desktop’, ‘mobile’, ‘tablet’, ‘pos’, ‘atm’
osName (string) - OS name (e.g., ‘Android’, ‘iOS’, ‘Windows’, ‘macOS’)
osVersion (string) - OS version

Device Info:

manufacturer (string) - Device manufacturer
model (string) - Device model
brand (string) - Device brand
deviceName (string) - Device name/nickname

Browser Info (for web platform):

browser (string) - Browser name
browserVersion (string) - Browser version
userAgent (string) - Full user agent string

Security Flags:

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

Network Info:

ipAddress (string) - IP address (validated format)
isVpn (boolean) - Connection via VPN
isTor (boolean) - Connection via Tor network
isProxy (boolean) - Connection via proxy

Device Fingerprint:

deviceFingerprint (string) - Unique device fingerprint hash

Additional Details:

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

Channel

channel

string

Channel through which the transaction originated (max 50 characters).Common values:

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
chatbot - Chatbot interface
third_party - Third-party integration

Reason

reason

string

Optional reason for the transaction outcome (e.g. decline, failure, limit exceeded). Send any value from the transaction_reason_type enum. If omitted, the system uses WITHOUT_REASON. Not required — existing integrations remain valid.Full list: See Transaction Reason Enum for all 60+ allowed values.

Metadata

metadata

object

Additional metadata for the transaction. Optional fields:Tags:

tags (object) - Key-value pairs for categorization (values can be string, number, or boolean)

Transaction Context:

purpose (string) - Purpose of the transaction
frequency (string) - Transaction frequency
contract_number (string) - Associated contract number

Compliance:

enhanced_due_diligence (boolean) - EDD flag
block_reason (string) - Reason for blocking
compliance_alert (boolean) - Compliance alert flag

Custom fields are allowed via passthrough behavior.

Response

transaction

object

The created transaction object. Includes:

id - gu1’s internal transaction ID
externalId - Your external ID
organizationId - Your organization ID
type - Transaction type
amount - Transaction amount (string)
currency - Currency code
status - Transaction status
riskScore - Calculated risk score 0-100 (string)
flagged - Whether transaction is flagged
channel - Channel information
reason - Outcome reason (e.g. WITHOUT_REASON, INSUFFICIENT_FUNDS)
originDetails / destinationDetails - Origin/destination details
locationDetails - Location data
deviceDetails - Device information
processingTimeMs, processedAt, transactedAt, createdAt, updatedAt - Timestamps

rulesResult

object

Only present when executeRules was true. Result of rules execution:

success (boolean) - Whether rules executed successfully
executed (boolean) - Whether the engine ran
result (object, optional) - Full rules engine result (riskScore, decision, alerts, etc.)
rulesExecutionSummary (object) - Detailed summary; see below. Also duplicated at root for convenience.
rulesTriggered (number) - Number of rules that were triggered
executionTimeMs (number) - Execution time in milliseconds
auditId (string, optional) - Risk matrix audit ID
isNewAudit (boolean, optional) - Whether a new audit was created

rulesExecutionSummary

object

Only present when executeRules is true and the rules engine ran. Same object as rulesResult.rulesExecutionSummary. Omitted when executeRules is false.

rulesHit (array) - Rules whose conditions were met. Each item: name, description, score, priority, category, status, conditions, actions.
rulesNoHit (array) - Rules evaluated but conditions not met. Same structure as rulesHit.
actionsExecuted (object, optional) - Aggregated executed actions: alerts (with ruleId, ruleExternalId, investigationId), suggestion, status, assignedUser, customKeys. Omitted when empty.
totalScore (number) - Sum of score of all rules that hit (excluding shadow).
scoreResult (object) - rawScore, normalizedScore (0–100), label (name, range, minScore, maxScore).
riskMatrixName (string) - Name of the risk matrix executed.
executionTimeMs (number) - Rules engine execution time in milliseconds.
trigger (string) - Event that triggered the evaluation (e.g. manual_evaluation, entity_created, created).
matchedRulesCount (number) - Number of rules that matched. See Rules Execution Summary for the full structure and a complete example.

Examples

Basic Transaction

curl -X POST http://api.gu1.ai/transactions \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "externalId": "txn_12345",
    "type": "PAYMENT",
    "amount": 150.50,
    "currency": "USD",
    "originExternalId": "customer_001",
    "destinationExternalId": "merchant_456",
    "description": "Online purchase"
  }'

Response Example

{
  "transaction": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "txn_67890",
    "organizationId": "8e2f89ab-c216-4eb4-90eb-ca5d44499aaa",
    "type": "TRANSFER",
    "status": "CREATED",
    "amount": "1000.00",
    "currency": "BRL",
    "amountInUsd": "1000.00",
    "paymentMethod": "PIX",
    "riskScore": "15",
    "flagged": false,
    "channel": "mobile_app",
    "reason": "WITHOUT_REASON",
    "originDetails": {},
    "destinationDetails": {},
    "locationDetails": {},
    "deviceDetails": {},
    "processingTimeMs": "120",
    "processedAt": "2024-10-03T14:30:00.000Z",
    "transactedAt": "2024-10-03T14:30:00.000Z",
    "createdAt": "2024-10-03T14:30:00.000Z",
    "updatedAt": "2024-10-03T14:30:00.000Z"
  },
  "rulesResult": {
    "success": true,
    "executed": true,
    "rulesTriggered": 1,
    "executionTimeMs": 162,
    "auditId": "52fa709f-88fe-473a-bc58-6efb5b0307f4",
    "isNewAudit": true,
    "rulesExecutionSummary": {
      "rulesHit": [],
      "rulesNoHit": [],
      "actionsExecuted": {},
      "totalScore": 15
    }
  },
  "rulesExecutionSummary": {
    "rulesHit": [],
    "rulesNoHit": [],
    "actionsExecuted": {},
    "totalScore": 15
  }
}

(For batch create, see Create Batch; that endpoint returns an array of transactions.)

Error Responses

400 Bad Request - Invalid Data

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": [
      "Amount must be zero or a positive number",
      "Currency must be at least 3 characters"
    ]
  }
}

400 Bad Request - Invalid IP Address

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid deviceDetails structure",
    "details": {
      "path": ["deviceDetails", "ipAddress"],
      "message": "Invalid IP address format"
    }
  }
}

409 Conflict - Duplicate Transaction

{
  "success": false,
  "error": {
    "code": "DUPLICATE_TRANSACTION",
    "message": "Transaction with this external_id already exists",
    "details": {
      "field": "external_id",
      "value": "txn_12345"
    }
  }
}

429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "code": "RATE_LIMIT_EXCEEDED",
  "retryAfter": 3600
}

Next Steps

Create Batch Transactions - Bulk transaction creation
Change transaction status - Change status
Transaction Monitoring - Learn about fraud detection

Getting Started

Use Cases

Webhooks

Person

Company

Transactions

Devices

Events

Know Your Customer (KYC)

Transactions

Payment Methods

Rules

Risk Matrix

Alerts

Investigations

Data Ingestion

Documents

Enrichment

Integrations

Interactive Tutorials

​Overview

​Endpoint

​Authentication

​Request Body

​Required Fields

​Optional Fields

​Origin Entity Fields

​Destination Entity Fields

​Location Details

​Device Details

​Channel

​Reason

​Metadata

​Response

​Examples

​Basic Transaction

​Response Example

​Error Responses

​400 Bad Request - Invalid Data

​400 Bad Request - Invalid IP Address

​409 Conflict - Duplicate Transaction

​429 Too Many Requests

​Next Steps

Overview

Endpoint

Authentication

Request Body

Required Fields

Optional Fields

Origin Entity Fields

Destination Entity Fields

Location Details

Device Details

Channel

Reason

Metadata

Response

Examples

Basic Transaction

Response Example

Error Responses

400 Bad Request - Invalid Data

400 Bad Request - Invalid IP Address

409 Conflict - Duplicate Transaction

429 Too Many Requests

Next Steps