Inline Decisioning

How to use WatchTower when a source system needs an immediate risk decision before completing a transaction.

Immediate decision

Return an allow, review, block, or challenge outcome while the source transaction is still pending.

Audit-safe flow

Store references, idempotency keys, decision outcomes, and response timestamps for support and compliance review.

Operational follow-through

Review and block outcomes can create alerts, cases, notifications, and final analyst decisions.

The API response contract

The examples below use the canonical transaction endpoint. ALLOW means the configured evaluation permits continuation; REVIEW requires your review policy; BLOCK requires your blocking policy; CHALLENGE requires a supported step-up flow; CONTEXT_ONLY records context without a live payment decision. Your payment platform applies the outcome.

The core response includes transactionId, decision, riskScore, triggeredRules, and evaluatedAt. Optional challenge and behavioral fields depend on the evaluated transaction and enabled capabilities. Do not expect likelyFraud, confidenceScore, recommendedAction, evidenceSummary, or triggeredControls as guaranteed response fields.

The ALLOW example is illustrative. Sending the same values does not guarantee the same decision in an organization with different controls or history.

When to use inline decisioning

Use inline decisioning when the source system can pause the transaction long enough for WatchTower to screen it and return an immediate decision.

This mode is best for channels where a clear action is needed before completion, such as transfer initiation, wallet movement, high-risk beneficiary payments, bill payments, or other real-time payment flows.

Typical outcomes

allow the transaction to continue
hold or route the transaction for review
block or cancel the transaction before completion

Confirm channel support first

Inline decisioning only applies when the upstream channel supports synchronous risk checks. If a source system cannot wait for a decision, use monitoring or batch ingestion instead.

Request flow

The source system receives or creates a transaction request.
The source system sends the transaction context to WatchTower from a trusted backend service.
WatchTower authenticates the request, resolves the organization, and normalizes the payload.
Rules, behavioral signals, identity context, and watchlist checks run against the transaction.
WatchTower returns an immediate decision response.
The source system applies the decision and stores the response reference for reconciliation.

Decision response concepts

The response should be treated as the screening result for that specific transaction attempt. Store the transaction reference, idempotency key, decision, risk score, and response timestamp for later support and audit review.

Response fields to handle

transaction reference or upstream reference
decision, which can be allow, review, block, challenge, or context only
recommended action for the source system
risk score or confidence score
triggered controls and evidence summary where available
stable response identifier for support and reconciliation

Canonical request and response example

This request uses POST /api/v1/transactions. An adapter integration has a separate agreed source contract; do not send adapter-specific field names to the canonical endpoint.

Example inline screening request

{
  "id": "6ef1b19e-245a-42f7-bbf2-c91f0cbdde27",
  "amount": 25000,
  "currency": "NGN",
  "channel": "MOBILE",
  "transactionType": "DEBIT",
  "transactionCategory": "TRANSFER",
  "timestamp": "2026-03-24T14:43:46.020Z",
  "paymentReference": "TXN-2026-000145",
  "customerType": "INDIVIDUAL",
  "sender": {
    "name": "Ada Example",
    "providerCustomerId": "customer-001",
    "accountNumber": "0123456789",
    "bankCode": "001",
    "partyType": "BANK_ACCOUNT"
  },
  "receiver": {
    "name": "Bayo Example",
    "accountNumber": "0987654321",
    "bankCode": "214",
    "partyType": "BANK_ACCOUNT"
  },
  "metadata": {
    "narration": "Family support",
    "sourceSystem": "example-payment-platform"
  }
}

Example inline decision response

{
  "transactionId": "6ef1b19e-245a-42f7-bbf2-c91f0cbdde27",
  "decision": "ALLOW",
  "riskScore": 0,
  "triggeredRules": [],
  "evaluatedAt": "2026-03-24T14:43:46.020Z"
}

Retries and duplicate handling

Real-time transaction systems retry requests when networks are slow or responses are unclear. Inline integrations must therefore use stable transaction references and idempotency keys.

Retry expectations

reuse the same idempotency key for the same transaction attempt
do not generate a new reference for a retry of the same event
store the decision returned by WatchTower
treat duplicate responses as reconciliation events, not new transactions

Timeout and reconciliation planning

Every inline integration should define what the source system does when no response arrives before its own timeout. WatchTower can support follow-up status checks and downstream case workflows, but the source system still needs a safe timeout policy.

Plan before go-live

client-side timeout threshold
default source-system behavior when timeout occurs
status query or reconciliation process
how analyst resolution is reflected back into the source system
audit record for delayed or retried decisions

What happens after the response

The inline response is only the first part of the workflow. If WatchTower returns review or block, the same transaction can create an alert, generate a case, notify the assigned team, and preserve the decision trail for reporting.

If your integration is built to hold the transaction on your side while it is under review, WatchTower sends a signed follow-up callback once the analyst records a final release or cancel decision, so your system can act on it automatically instead of polling for status.

allow decisions can be stored for monitoring and reporting
review decisions can create analyst work queues and, where the integration holds the transaction, a follow-up callback
block decisions can create high-priority cases
case updates, notes, assignments, and final outcomes remain auditable

Full pattern

See "Held transactions and the review outcome" on the Decisions and Risk Outcomes page for the complete flow and callback payload.