Developer Documentation & API Contracts

RecoupIQ Developer Reference

Deterministic risk intelligence, transaction clearance with a 1-second decision deadline, and tamper-evident audit receipts for UK B2B platforms, payment processors, and financial institutions.

View Payment Gateways Solution Architecture•Mint Self-Serve Sandbox Key (riq_test_*)•Run 10-Merchant Loss Backtest

5.3M+

UK Commercial Entities

Active & historical corporate registry

29.3M

Officer & Director Records

Historical appointments & governance

100%

Charges & Debentures

Secured debt & creditor priority

Real-Time

Insolvency & Gazette Feeds

Court petitions & dissolution notices

Environments & Key Separation

All API calls use the canonical production host https://recoup-iq.tech. Environment isolation is determined automatically by your API key prefix:

Sandbox Mode (riq_test_*)Self-Serve / No Cost

Mint directly in /dashboard/api-keys on any free account. Simulates healthy companies (00000001), winding-up petitions (00000002), zero active directors / boardroom flight (00000003), and balance-sheet insolvency (00000004) with meta.sandbox: true.

Live Production (riq_live_*)1 s deadline / ES256 signed

Connects to the RecoupIQ clearance engine with automatic read-through across all 5.3M+ UK companies in our Azure Blob lakehouse. Decision receipts carry a SHA-256 hash and an ES256 signature from Azure Key Vault.

Transaction Check Quickstart (POST /api/v1/transaction-check)

Before releasing morning payout wires or extending trade credit, send an idempotent clearance check. The endpoint requires zero PAN/CVV data, operating solely on verified UK corporate registration numbers.

curl -X POST https://recoup-iq.tech/api/v1/transaction-check \
  -H "Authorization: Bearer riq_test_your_sandbox_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: wire_clearance_20260905_001" \
  -H "X-Request-Id: req_trace_987654" \
  -d '{
    "transactionId": "txn_payout_88219",
    "idempotencyKey": "wire_clearance_20260905_001",
    "eventType": "payout_release",
    "amountMinor": 12500000,
    "currency": "GBP",
    "direction": "outbound",
    "productType": "b2b_payout",
    "payer": {
      "role": "payer",
      "companyNumber": "00000001"
    },
    "payee": {
      "role": "payee",
      "companyNumber": "00000002"
    },
    "terms": {
      "creditDays": 0
    },
    "exposure": {
      "currentMinor": 0,
      "proposedMinor": 12500000,
      "currency": "GBP"
    }
  }'

Canonical Policy Results (decision.policyResult):

CLEAR_FOR_POLICY

Zero statutory or policy impediment (reviewRequired: false). Safe for immediate Faster Payments / BACS wire release.

REVIEW

Statutory insolvency event (PUBLIC_INSOLVENCY_EVENT), governance defect (ZERO_ACTIVE_DIRECTORS), or balance-sheet distress (BALANCE_SHEET_INSOLVENT). Hold wire or adjust rolling reserve.

UNKNOWN / DEGRADED

Incomplete party context or unavailable snapshot (reviewRequired: true fail-closed default).

Deterministic Sandbox Test Company Numbers (riq_test_*):

00000001

Clean UK company → CLEAR_FOR_POLICY

00000002

Winding-up petition → REVIEW (PUBLIC_INSOLVENCY_EVENT)

00000003

0 active directors → REVIEW (ZERO_ACTIVE_DIRECTORS)

00000004

Negative net assets → REVIEW (BALANCE_SHEET_INSOLVENT)

Canonical Endpoints

Method	Path	Required Scope	Description
POST	/api/v1/transaction-check	transaction-risk:check	Settlement clearance with a 1-second decision deadline, flagging High Court winding-up petitions & Insolvency Act 1986 §127 void payouts.
POST	/api/v1/transaction-outcomes	transaction-risk:outcome	Record transaction lifecycle outcomes (settled, chargeback, default, clawback).
GET	/api/v1/transaction-decisions	transaction-risk:decision:read	Retrieve prior signed decision receipts and cryptographic certificates using Idempotency-Key.
GET	/api/v1/transaction-keys	transaction-risk:keys:read	Retrieve the public Azure Key Vault verification keys for signed decision receipts.
POST	/api/v1/report	risk-assess:read	Full forensic report (verdict plus plain-English findings) for a UK company.
POST	/api/v1/risk-assess	risk-assess:read	Banded risk assessment with optional priced risk and reason codes.
POST	/api/v1/screen	screen:read	Sanctions, FCA Warning List, and disqualified-director screening.
POST	/api/v1/cross-border-counterparty	risk-assess:read	UK counterparty vetting for foreign creditors, with a regime explainer.
POST	/api/v1/entity-resolve	risk-assess:read	Resolve a trading name plus address to a Companies House number.
GET/POST/DELETE	/api/v1/company-monitoring	transaction-risk:monitoring:manage	Manage automated continuous company-risk monitoring and change alerts.

Machine-readable specification:/api/openapi.json (OpenAPI 3.1)

Interactive OpenAPI Explorer

RecoupIQ Developer Reference

Deterministic risk intelligence, transaction clearance with a 1-second decision deadline, and tamper-evident audit receipts for UK B2B platforms, payment processors, and financial institutions.

curl -X POST https://recoup-iq.tech/api/v1/transaction-check \ -H "Authorization: Bearer riq_test_your_sandbox_api_key" \ -H "Content-Type: application/json" \ -H "Idempotency-Key: wire_clearance_20260905_001" \ -H "X-Request-Id: req_trace_987654" \ -d '{ "transactionId": "txn_payout_88219", "idempotencyKey": "wire_clearance_20260905_001", "eventType": "payout_release", "amountMinor": 12500000, "currency": "GBP", "direction": "outbound", "productType": "b2b_payout", "payer": { "role": "payer", "companyNumber": "00000001" }, "payee": { "role": "payee", "companyNumber": "00000002" }, "terms": { "creditDays": 0 }, "exposure": { "currentMinor": 0, "proposedMinor": 12500000, "currency": "GBP" } }'

Canonical Endpoints

Method	Path	Required Scope	Description
POST	/api/v1/transaction-check	transaction-risk:check	Settlement clearance with a 1-second decision deadline, flagging High Court winding-up petitions & Insolvency Act 1986 §127 void payouts.
POST	/api/v1/transaction-outcomes	transaction-risk:outcome	Record transaction lifecycle outcomes (settled, chargeback, default, clawback).
GET	/api/v1/transaction-decisions	transaction-risk:decision:read	Retrieve prior signed decision receipts and cryptographic certificates using Idempotency-Key.
GET	/api/v1/transaction-keys	transaction-risk:keys:read	Retrieve the public Azure Key Vault verification keys for signed decision receipts.
POST	/api/v1/report	risk-assess:read	Full forensic report (verdict plus plain-English findings) for a UK company.
POST	/api/v1/risk-assess	risk-assess:read	Banded risk assessment with optional priced risk and reason codes.
POST	/api/v1/screen	screen:read	Sanctions, FCA Warning List, and disqualified-director screening.
POST	/api/v1/cross-border-counterparty	risk-assess:read	UK counterparty vetting for foreign creditors, with a regime explainer.
POST	/api/v1/entity-resolve	risk-assess:read	Resolve a trading name plus address to a Companies House number.
GET/POST/DELETE	/api/v1/company-monitoring	transaction-risk:monitoring:manage	Manage automated continuous company-risk monitoring and change alerts.