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.
• A final status (ACCEPT or DECLINE) cannot be changed: ACCEPT -> DECLINE and DECLINE -> ACCEPT are rejected with 400.
• Re-sending the same final status (ACCEPT -> ACCEPT, DECLINE -> DECLINE) is treated as a retry of a call whose response was lost: it returns 200 with the response of the first final call (for up to 24 hours; later, the scores stored per gate) and changes nothing. Other fields of the retried body are ignored.

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 processed one at a time. 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, except a retry of the same final status, which returns the first final response.