Skip to main content

Transactions

A transaction links runs across multiple gates into a single business workflow. For example, a loan application might pass through credit scoring, fraud detection, and compliance sign-off gates — all sharing the same transactionId.

How It Works​

When submitting a run, include a transactionId to associate it with a business transaction:

curl -X POST https://api.rynko.dev/api/flow/gates/credit-scoring/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": { "applicant_id": "A-001", "score": 720 },
    "transactionId": "LOAN-2026-0042",
    "transactionType": "loan_application"
  }'

Then submit to another gate with the same transactionId:

curl -X POST https://api.rynko.dev/api/flow/gates/fraud-check/runs \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": { "applicant_id": "A-001", "risk_score": 0.12 },
    "transactionId": "LOAN-2026-0042",
    "transactionType": "loan_application"
  }'

Transaction Fields​

FieldMax LengthDescription
transactionId255Your business transaction identifier. Same ID across gates links runs together.
transactionType100A label for the transaction category (e.g., loan_application, payment_review).
externalRef255Your own internal reference ID (case number, order ID). Indexed for fast lookups.

All three fields are optional. They are stored on the run and included in webhook deliveries.

Gate Default Transaction Type​

Gates can have a default transactionType that applies to all runs submitted without their own:

curl -X POST https://api.rynko.dev/api/flow/gates \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Credit Scoring Review",
    "schema": { ... },
    "transactionType": "loan_application"
  }'

When a run provides its own transactionType, it takes precedence over the gate default.

Querying Transactions​

Get All Runs for a Transaction​

GET /api/flow/transactions/:transactionId

Returns all runs across all gates with the given transactionId, ordered by submission time:

{
  "transactionId": "LOAN-2026-0042",
  "transactionType": "loan_application",
  "totalRuns": 3,
  "firstRunAt": "2026-04-04T10:23:01Z",
  "lastRunAt": "2026-04-04T10:23:06Z",
  "gatesInvolved": [
    { "name": "Credit Scoring", "slug": "credit-scoring" },
    { "name": "Fraud Check", "slug": "fraud-check" },
    { "name": "Compliance Sign-off", "slug": "compliance-sign-off" }
  ],
  "runs": [
    { "id": "...", "shortId": "frun_abc1", "status": "completed", "gate": { "name": "Credit Scoring" } },
    { "id": "...", "shortId": "frun_abc2", "status": "completed", "gate": { "name": "Fraud Check" } },
    { "id": "...", "shortId": "frun_abc3", "status": "pending_approval", "gate": { "name": "Compliance Sign-off" } }
  ]
}

Filter Runs by Transaction​

GET /api/flow/runs?transactionId=LOAN-2026-0042

Filter Runs by External Reference​

GET /api/flow/runs?externalRef=CASE-2026-1234

Transactions vs. Correction Chains​

FeatureTransactionsCorrection Chains
ScopeAcross gatesWithin a single gate
PurposeLink steps of a business workflowLink retry attempts for the same payload
IdentifiertransactionId (user-provided)correlationId (auto-generated)
LinkageExplicit — caller provides the same IDAutomatic — identity keys or parentRunId

Both can be used together: a loan application transaction might include a credit scoring run that was retried twice (a correction chain of 2 within the transaction).

Webhook Delivery​

Transaction fields are included in webhook payloads:

{
  "event": "flow.run.delivered",
  "run": {
    "id": "...",
    "shortId": "frun_abc123",
    "status": "completed",
    "transactionId": "LOAN-2026-0042",
    "transactionType": "loan_application",
    "externalRef": "CASE-2026-1234",
    "inputPayload": { ... },
    "metadata": { ... }
  },
  "gate": { "id": "...", "name": "Credit Scoring", "slug": "credit-scoring" },
  "timestamp": "2026-04-04T10:23:05Z"
}

Dashboard​

The webapp includes a Transactions page under the Flow section where you can:

  1. Search for a transaction by ID
  2. View a timeline of all runs across gates
  3. See the status of each run at a glance
  4. Click through to individual run details