Compliance Decision API

One API call. A defensible compliance decision.

POST a transaction to /v1/decide before money moves. Get back CLEAR, FLAGGED, HELD_FOR_REVIEW, or BLOCKED — with the customer risk state, every rule that fired, the required actions for your system, and a reference to the immutable evidence. Synchronous. Under 50ms P99.

Book a demo →See what feeds the decision
<50msP99 response latency
4 statesCLEAR · FLAGGED · HELD_FOR_REVIEW · BLOCKED
100%Decisions evidenced
The API

Request in. Decision out. Evidence stored.

Send the transaction context. Receive a structured decision your system can act on immediately. Every call is logged to the append-only evidence store — whether the decision was CLEAR, FLAGGED, HELD_FOR_REVIEW, or BLOCKED.

POST /v1/decide — live decision
Request
<span class="ak">POST</span> /v1/decide HTTP/1.1
Host: api.getfintegrity.com
Content-Type: application/json
Authorization: Bearer <token>

{
  <span class="ak">"amount"</span>: <span class="an">450000</span>,
  <span class="ak">"currency"</span>: <span class="as">"NGN"</span>,
  <span class="ak">"type"</span>: <span class="as">"transfer"</span>,
  <span class="ak">"customerId"</span>: <span class="as">"cust_b72f14"</span>,
  <span class="ak">"counterpartyId"</span>: <span class="as">"cpty_9a31"</span>,
  <span class="ak">"channel"</span>: <span class="as">"mobile"</span>,
  <span class="ak">"idempotencyKey"</span>: <span class="as">"pay_20260521_001"</span>
}
Response · 14ms
HTTP/1.1 200 OK
X-Fintegrity-Latency: 14ms

{
  "decision": "HELD_FOR_REVIEW",
  "requiredActions": [
    "HOLD_FOR_REVIEW"
  ],
  "reasons": [
    "VELOCITY_24H_EXCEEDED",
    "PROFILE_ANOMALY"
  ],
  "customerRiskState": "UNDER_REVIEW",
  "evidenceRef": "evd_b91f4a72c...",
  "decidedAt": "2026-05-21T09:14:03Z",
  "latencyMs": 14
}
Response anatomy

Every field tells your system exactly what to do

A Fintegrity decision response isn't just a verdict. It's a complete instruction set for your payment handler — with the evidence already filed.

  • →

    decision

    CLEAR, FLAGGED, HELD_FOR_REVIEW, or BLOCKED. Always one of these four. No ambiguity.

  • →

    requiredActions

    What your system should do: PROCEED, HOLD_FOR_REVIEW, or DECLINE_AND_REVERSE. Maps directly to your payment rail commands.

  • →

    reasons

    Which rules fired or patterns matched. Array of typed reason codes, not free text.

  • →

    customerRiskState

    The customer's risk state after this decision: ACTIVE, UNDER_REVIEW, or BLOCKED.

  • →

    evidenceRef

    A pointer to the immutable evidence record for this decision. Survives forever. Present it to a regulator by reference.

  • →

    latencyMs

    How long Fintegrity took to decide. Your SLA auditing, not ours.

How the decision is made

A composite decision from multiple inputs

01

Customer state first

A BLOCKED customer gets an immediate BLOCKED decision. No rules run. This prevents compliance bypass via new devices or accounts.

02

Transaction context evaluated

Amount, type, channel, counterparty, and timing are all passed to the rule engine.

03

Rule library fires

Your configured rules — velocity, thresholds, structuring, new-account, profile — all evaluate in parallel.

04

Screening consulted

If transaction screening is configured, your sanctions/PEP provider is queried and the result is factored in.

05

Most restrictive wins

The most severe input wins: BLOCKED beats HELD_FOR_REVIEW, which beats FLAGGED, which beats CLEAR. If any input returns BLOCKED, the decision is BLOCKED.

Customer risk lifecycle

One authoritative risk state per customer

Every customer has exactly one risk state at any point in time. State transitions are enforced, audited, and reflected immediately in every subsequent decision call.

ACTIVE

Normal operating state

Customer is in good standing. Transactions proceed through the full rule evaluation. Monitoring continues in the background. The majority of customers are in this state.

UNDER_REVIEW

Flagged for closer monitoring

A pattern or case has flagged this customer for elevated scrutiny. High-risk transactions may be held for manual review. A case is open and under investigation. State resolves back to ACTIVE on clearance or forward to BLOCKED on escalation.

BLOCKED

All transactions declined

Every transaction for this customer returns a BLOCKED decision before any rules run. Account is frozen pending investigation resolution. State is set by a compliance case disposition or by a rule that reaches a hard-block threshold.

Integration

Designed for pre-authorisation hooks

Call /v1/decideat the point in your payment handler where you would normally execute the debit or credit. Act on the decision. Your rails execute — or don't — based on Fintegrity's response.

  • ✓

    RESTful JSON

    Standard HTTP + JSON. No proprietary SDKs required. Works with any stack that can make an HTTP request.

  • ✓

    Synchronous

    The decision is in the response body. No webhooks required for the primary flow. Sub-50ms P99 means no user-visible latency.

  • ✓

    Idempotent

    Pass an idempotencyKey to guarantee exactly-once decision processing, even across retries.

  • ✓

    Webhooks for async events

    Customer state changes, case updates, and FLAGGED or HELD_FOR_REVIEW resolutions can optionally be pushed to your endpoint.

See a live decision in your context

We'll demonstrate a decision call using transaction patterns from your business model — with real rules, real states, and real evidence.

Book a demo →Explore the Developer API