Create Transaction

curl --request POST \
  --url http://api.gu1.ai/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalId": "<string>",
  "type": "<string>",
  "amount": 123,
  "currency": "<string>",
  "status": "<string>",
  "paymentMethod": "<string>",
  "description": "<string>",
  "category": "<string>",
  "transactedAt": "<string>",
  "executeRules": true,
  "validateExistingEntity": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "originEntityId": "<string>",
  "originExternalId": "<string>",
  "originTaxId": "<string>",
  "originName": "<string>",
  "originCountry": "<string>",
  "originDetails": {},
  "destinationEntityId": "<string>",
  "destinationExternalId": "<string>",
  "destinationTaxId": "<string>",
  "destinationName": "<string>",
  "destinationCountry": "<string>",
  "destinationDetails": {},
  "locationDetails": {},
  "deviceDetails": {},
  "channel": "<string>",
  "reason": "<string>",
  "timeZone": "<string>",
  "metadata": {}
}
'

{
  "transaction": {},
  "rulesExecutionSummary": {}
}

POST

transactions

Create Transaction

curl --request POST \
  --url http://api.gu1.ai/transactions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "externalId": "<string>",
  "type": "<string>",
  "amount": 123,
  "currency": "<string>",
  "status": "<string>",
  "paymentMethod": "<string>",
  "description": "<string>",
  "category": "<string>",
  "transactedAt": "<string>",
  "executeRules": true,
  "validateExistingEntity": true,
  "riskMatrixId": [
    "<string>"
  ],
  "riskMatrixIds": [
    "<string>"
  ],
  "originEntityId": "<string>",
  "originExternalId": "<string>",
  "originTaxId": "<string>",
  "originName": "<string>",
  "originCountry": "<string>",
  "originDetails": {},
  "destinationEntityId": "<string>",
  "destinationExternalId": "<string>",
  "destinationTaxId": "<string>",
  "destinationName": "<string>",
  "destinationCountry": "<string>",
  "destinationDetails": {},
  "locationDetails": {},
  "deviceDetails": {},
  "channel": "<string>",
  "reason": "<string>",
  "timeZone": "<string>",
  "metadata": {}
}
'

{
  "transaction": {},
  "rulesExecutionSummary": {}
}

Overview

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

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

Risk matrices (optional)

riskMatrixId

string | string[]

Legacy-compatible: one UUID or an array of UUIDs of risk matrices owned by your organization. When non-empty, only rules assigned to those matrices run for this transaction (no mixing with “loose” trigger-only rules). Omit both riskMatrixId and riskMatrixIds to keep the historical trigger-based behavior.

riskMatrixIds

string[]

Preferred for multiple matrices: ordered UUID list. Takes precedence over riskMatrixId when provided and non-empty.

Origin Entity Fields

How the origin is linked in gu1 (tried in order; stop at first success):

Direct ID — if you send originEntityId, the transaction is tied to that entity (must exist in your org).
External ID — if you did not send originEntityId but you send originExternalId and a person/company exists with the same externalId, the row is auto-linked to that entity.
Tax / document ID (third fallback) — if the transaction is still not linked, but you send root originTaxId, the API looks up a person/company whose taxId in gu1 matches after normalization (only letters and digits, ignoring punctuation, spaces, and case for comparison).

If step 2 or 3 succeeds, the API sets originEntityId and, when you did not provide them, enriches originName and originCountry from the matched entity.If the tax/external value does not match any entity, the transaction is still created; the fields you sent are stored, but there is no entity link.
(For graph visualization only, you can also send a tax in originDetails — that path does not auto-link; use originTaxId at the root when you want a real link by document.)

originEntityId

string

UUID of the origin entity (sender) in gu1 system

originExternalId

string

Your external ID for the origin entity

originTaxId

string

Tax or national document ID of the origin counterparty (e.g. CPF, CNPJ, CUIT), at the root of the transaction. Used only as the third way to find and link a person/company, after originEntityId and originExternalId. The value is compared to each entity’s taxId using a normalized form (alphanumeric only). If a match is found, originEntityId is set and name/country can be filled. Max length: 50 characters. Optional.

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

destinationTaxId

string

Tax or document ID of the destination counterparty at the root of the request. Third linking fallback: used only if destinationEntityId and destinationExternalId did not resolve. Same matching rules as originTaxId. When a match is found, destinationEntityId is set and name/country can be enriched. Max: 50 characters. Optional.

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.

Time zone

timeZone

string

Optional IANA time zone for transaction-local time context (e.g. alongside transactedAt). Send a value from transaction_time_zone. If omitted, stored as null (default for existing rows).Full list: See Transaction Time Zone Enum.

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)
timeZone - IANA time zone (string | null)
originDetails / destinationDetails - Origin/destination details
locationDetails - Location data
deviceDetails - Device information
processingTimeMs, processedAt, transactedAt, createdAt, updatedAt - Timestamps

rulesExecutionSummary

object

Only present when executeRules is true and the rules engine ran. 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"
  },
  "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

Get transaction - Fetch by ID or external ID
Create Batch Transactions - Bulk transaction creation
Change transaction status - Change status
Transaction Monitoring - Learn about fraud detection

Company Provider Codes Get Transaction

⌘I

Documentation Index

​Overview

​Endpoint

​Authentication

​Request Body

​Required Fields

​Optional Fields

​Risk matrices (optional)

​Origin Entity Fields

​Destination Entity Fields

​Location Details

​Device Details

​Channel

​Reason

​Time zone

​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

Risk matrices (optional)

Origin Entity Fields

Destination Entity Fields

Location Details

Device Details

Channel

Reason

Time zone

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