Transactions

POST /v2/transactions gives you a synchronous decision on a business event in your product — a registration, a login, a deposit, a withdrawal, a payment and, above all, a bonus claim. The main scenario is bonus abuse: one player claiming the same bonus campaign from several accounts.

We decide; you act. Tracio does not keep bonus balances, does not credit or debit anything and does not track wagering: your backend asks us before it grants the bonus, gets APPROVE, REVIEW or DECLINE, and enforces it itself. The decision is enforced from the first call — there is no observe-only mode.

Base URL: https://api.tracio.ai. The route lives under /v2, the first route of the snake_case version of the Data API: every key in the request, the response and the error body is snake_case. The /v1 routes described in data-api.md keep their camelCase shape.

Authorization and plan

The same secret key (tracio_sk_…) and the same Authorization: Bearer header as the rest of the Data API — see data-api.md, section "Keys". A call counts against the usual Data API per-second limit and daily quota of your plan; there is no separate meter.

The endpoint requires the Business plan or higher. A key on a lower plan gets HTTP 402:

{ "error": { "code": "upgrade_required",
             "message": "Transactions require the Business plan or higher",
             "request_id": "01J8F3..." } }

One exception: below Business the endpoint accepts an account_register or a deposit that carries an affiliate_id — an affiliate conversion, see affiliates.md. Such a call is not run through the bonus rules.

A key without Data API access at all (below Pro) is turned away earlier, by the shared authorization layer, with 402 upgrade_required in the v1 envelope — see Errors.

Request

curl -X POST https://api.tracio.ai/v2/transactions \
     -H "Authorization: Bearer $TRACIO_SECRET_KEY" \
     -H "Content-Type: application/json" \
     -d '{
           "action_type": "bonus",
           "transaction_id": "bns-81723",
           "user_id": "usr_8412",
           "request_id": "01J8F3ZK8Q0000000000000000",
           "bonus_campaign_id": "welcome-200",
           "transaction_amount": 50,
           "transaction_currency": "EUR",
           "custom_fields": { "affiliate": "aff-17" }
         }'

The body is at most 64 KiB. Unknown keys are rejected with 400 invalid_request — a typo in a field name fails loudly instead of being ignored. Every custom_fields value must be a string.

Binding the event to a visit

request_id is the main link to the visit: from it we take the device (visitor_id), the person behind the account and the visit's guidance (see data-api.md, section "Guidance"). The visit is looked up within the last 30 days, in the environment of your key.

session is an optional authenticity check. Pass the inline_token your frontend received (see inline-verdict.md), and we verify its signature and expiry. If request_id is absent, the token's requestId is used; if both are present, they must match. The token lives 2 minutes from the visit, so it fits an event that follows the page load immediately (a registration, a login); a deposit or a bonus claimed later in the session will fail the check — send only request_id for those.

Both fields are optional. Without a visit the decision is still made on what is available and is marked partial (see Response).

user_id must match linkedId

The rules find a player's other accounts through the identity graph, which is built from the linkedId your site passes to the SDK. user_id is matched against it byte for byte: case and spaces are significant (USR_8412, usr_8412 and usr_8412 are three different accounts). Send the same id in the same form in both places. The only normalization is the one linkedId gets too: ASCII control characters and invalid UTF-8 are dropped. A user_id with nothing printable in it is rejected with 400.

Response

200 OK:

{
  "id": "6f1c2d7e-3b4a-4c5d-9e8f-0a1b2c3d4e5f",
  "transaction_id": "bns-81723",
  "state": "REVIEW",
  "fraud_score": 60,
  "applied_rules": [
    { "id": "B01", "name": "same_campaign_same_person", "operation": "+", "score": 60 }
  ],
  "partial": true,
  "partial_sources": ["visit"],
  "recommendations": ["hold_bonus_until_review"],
  "evidence": [
    { "rule_id": "B01", "code": "same_campaign_same_person", "score": 60,
      "message": "Another user ID of the same person already took this campaign." }
  ],
  "calculation_time": 37,
  "idempotent_replay": false
}

recommendations

The action for your backend, derived from the effective state: the state an analyst or a label set on the transaction, if any, otherwise state. On a first call nobody has changed the transaction yet, so the effective state is state.

evidence

Human-readable reasons, built from applied_rules: at most 5 elements, sorted by score from high to low (equal scores — by rule_id). Each element:

For a rule not in this table, code is its rule_id in lower case and message is its name. A transaction outside the bonus flow has no applied rules, so its evidence is [].

How the decision is made

Bonus flow — a transaction with a non-empty bonus_campaign_id, or with action_type: "bonus". It goes through the bonus rules B01–B05 below; the scores of the rules that fired are summed into fraud_score, and the state is DECLINE at fraud_score ≥ 80, REVIEW at ≥ 50, otherwise APPROVE (default thresholds).

Everything else — the state comes from the guidance of the visit, for the scenario that matches the action:

deny → DECLINE, review or challenge → REVIEW, allow → APPROVE. No visit → APPROVE with partial: true and partial_sources: ["visit"]. These transactions have fraud_score: 0 and an empty applied_rules: the bonus rules are not run for them.

Every transaction is stored, partial and non-bonus ones included: stored deposits feed rule B04, and stored bonus claims are what the next call is counted against.

Bonus rules B01–B05

Default thresholds: REVIEW at fraud_score ≥ 50, DECLINE at ≥ 80.

Details:

• B04. "Total bonus used" is the sum of transaction_amount over the account's transactions with a non-empty bonus_campaign_id; "deposits" is the sum over its transactions with action_type: "deposit". Both include the current transaction and count only amounts in the currency of the current transaction. No deposits — the rule does not fire. A transaction without a currency does not evaluate B04 at all. For B04 to work, report deposits to this endpoint too.
• B01 needs a person for the account — taken from the visit, or else from the latest visit where this user_id was the linkedId. No person — B01 is skipped and person appears in partial_sources.
• B02 sees the rings as of their last recalculation, which runs every 6 hours.
• B03 and B05 need a visit (request_id).

Properties the defaults rely on: no single rule reaches DECLINE on its own (the maximum is +60), so a second signal is needed; an honest family on one device (two different persons, one bonus each) gets only B03 = 40 → APPROVE.

The defaults are expert estimates, not a calibration on your traffic. For the first weeks, check the applied_rules of REVIEW and DECLINE decisions in the dashboard and tune the settings.

Changing the rules

Dashboard → Transactions → Rule settings. Per workspace you can switch each rule on or off and change its score, its window (B01 and B04 in days, B03 in hours), the minimum number of accounts for B03, the ratio for B04, both B05 scores, and the REVIEW and DECLINE thresholds. The next call uses the new values. A workspace that never saved settings uses the defaults above.

Idempotency

transaction_id is unique within your workspace. Repeating a call with the same transaction_id:

• returns the stored decision with idempotent_replay: true — the rules are not evaluated again, nothing new is stored, and the session token is not checked again (so a retry after the token expired still gets its answer);
• answers 409 transaction_conflict if the repeat differs from the stored transaction in action_type, user_id, bonus_campaign_id, transaction_amount, transaction_currency or the affiliate fields (affiliate_id as you sent it; sub_id, click_id and affiliate_user_id of an attributed conversion). request_id, session and custom_fields are not compared.

calculation_time of a replay is the time of the replay itself. recommendations of a replay follow the current effective state: if an analyst or a label declined a transaction the rules approved, the replay keeps state: "APPROVE" and returns recommendations: ["withhold_bonus"].

If a call fails with 503, nothing was stored: retry with the same transaction_id.

A replay always returns the original decision in state. To read the state an analyst or a label set, use GET /v2/transactions/{transaction_id}; to be told when it changes, subscribe to the transaction_state_changed webhook.

GET /v2/transactions/{transaction_id}

Re-reads a stored decision together with its label and effective state. The same key, the same plan (Business+) and the same per-second limit and daily quota as POST /v2/transactions; a lower plan gets the same 402 upgrade_required, except for a transaction attributed to an affiliate, which is returned on every plan (see affiliates.md).

curl -H "Authorization: Bearer $TRACIO_SECRET_KEY" \
     https://api.tracio.ai/v2/transactions/bns-81723

transaction_id is your id, the one you sent to POST. Percent-encode it in the path if it contains /, %, a space or other reserved characters (bns%2F81723 for bns/81723); the lookup uses the decoded value.

200 OK:

{
  "id": "6f1c2d7e-3b4a-4c5d-9e8f-0a1b2c3d4e5f",
  "transaction_id": "bns-81723",
  "state": "REVIEW",
  "fraud_score": 60,
  "applied_rules": [
    { "id": "B01", "name": "same_campaign_same_person", "operation": "+", "score": 60 }
  ],
  "partial": true,
  "partial_sources": ["visit"],
  "effective_state": "DECLINE",
  "recommendations": ["withhold_bonus"],
  "evidence": [
    { "rule_id": "B01", "code": "same_campaign_same_person", "score": 60,
      "message": "Another user ID of the same person already took this campaign." }
  ],
  "label": "fraud_detection_bonus_abuse",
  "label_source": "dashboard",
  "label_at": "2026-10-15T10:04:00Z",
  "calculation_time": 2,
  "idempotent_replay": false
}

The keys of the POST response, with the same meaning, plus:

state stays the decision of the rules. idempotent_replay is always false: a GET stores nothing. Who set the label is not returned.

A transaction_id that does not exist in the workspace of your key gets 404 in the v2 envelope:

{ "error": { "code": "not_found",
             "message": "transaction not found",
             "request_id": "01J8F3..." } }

A transaction of another workspace looks exactly like a missing one.

To be told about a change instead of polling, use the transaction_state_changed webhook: its transaction block is this object without calculation_time and idempotent_replay.

Errors

Errors of this endpoint use the v2 envelope:

{ "error": { "code": "invalid_request",
             "message": "request validation failed",
             "request_id": "01J8F3...",
             "errors": [
               { "field": "action_type",
                 "message": "must be one of account_register, account_login, deposit, withdrawal, bonus, payment, account_update, other" },
               { "field": "transaction_currency",
                 "message": "is required when transaction_amount is set" }
             ] } }

errors is present only on validation failures and lists every invalid field at once. request_id here is the id of this API call (also sent as the X-Request-Id header) — quote it to support; it is not the visit's request_id.

Responses of the shared authorization layer are still in the v1 envelope until the whole API moves to v2: {"error":{"code","message","requestId"}}, with camelCase requestId and without errors. These are 401 unauthorized (missing, revoked or expired key), 402 upgrade_required for a key without Data API access (below Pro), 429 rate_limited with Retry-After, and 503 unavailable when the key store is unreachable. Their meaning is the one in data-api.md, section "Errors". Read the code from error.code: it has the same name in both envelopes.

Retry 429 and 503 with a growing pause; retrying the other 4xx is pointless — they mean the request itself needs fixing.

Field mapping from SEON

The request and response follow SEON's Fraud API, so an existing SEON integration maps field for field.

Request:

Response:

What this endpoint does not do

• It does not keep bonus balances, credit, debit or cancel anything — your backend does that on our decision.
• It does not look at wagering: there is no data on bets.
• It has no custom rule builder: the rules are the built-in B01–B05 with per-workspace settings.
• A replay does not return the state an analyst or a label set — read it with GET or receive it with the transaction_state_changed webhook.

Report the actual outcome of a transaction with transaction labels.