Process a single transaction for fraud detection and risk scoring. Returns a risk score and recommendation per payment gate.

How it works

This endpoint is the single entry point for both creating and updating transactions. The same method is used for the initial submission and all subsequent data/status updates.

Transaction identity

A transaction is uniquely identified by companyId (from auth context) + externalId (from the request body). Calling the endpoint again with the same externalId within the same company updates the existing transaction rather than creating a new one.

Status state machine

Transaction status is governed by a forward-only state machine: NEW -> PENDING -> ACCEPT / DECLINE.

Transition rules:

• The PENDING step is optional: direct transitions NEW -> ACCEPT and NEW -> DECLINE are allowed.

Updating transaction data

When resubmitting with the same externalId (and a valid next status), most fields can be updated: amounts, card data, customer details, merchant info, address, cascade and gates, customData, browserData, etc.

Fields that are never updated (fixed at creation time):

• dateStart - transaction start date
• customerCompanyId - company-level customer binding
• customerSystemId - system-level customer identifier

Typical usage flow:

• Transaction arrives with status: NEW - the system creates a record and performs scoring.
• After the payment outcome is known, an update is sent with status: ACCEPT or status: DECLINE - the system updates the record, recalculates the score, and records the final result.

Gate-level statuses

Each gate in the cascade has its own status (NEW, ACCEPT, DECLINE) and its own state machine: NEW -> ACCEPT or NEW -> DECLINE. A gate that has already transitioned from NEW to a final status cannot be changed again.
If a gate has status: DECLINE, the declineBy field becomes required and must specify the decline reason (BANK or SYSTEM). Optionally, errorReason can be provided with a more specific PROCESSING_ERROR-type code.

Concurrent request handling

Parallel requests for the same transaction (companyId + externalId) are serialized via a Redis mutex. If the transaction is currently being processed, a subsequent request waits in the queue. If the lock cannot be acquired within the timeout, an error is returned.

Automatic entity creation

During processing the system automatically creates related entities if they do not yet exist: Merchant, MerchantAccount, Cascade, Bank, Gate. If cascade is omitted from the request body, a default cascade is used. If gateList is empty, a default gate (default_zero_gate) is added automatically.

Scoring

Risk score is calculated per gate individually. There is no single aggregate score for the transaction - the response contains an array of results per gate with a breakdown by score generator type (basic, main). Every call (including updates) triggers a full score recalculation.