Skip to main content

Settlement and Evidence: From Approval to the Bank

Authorization is not settlement. A payout can be approved and never sent, sent and returned, or captured for a different amount than was authorized (tips, currency conversion, a changed invoice). This page covers the part of Auditail that follows a payment after guard() said yes:

QuestionFeature
Did every authorized payment settle, for the amount we authorized?Settlement checks
Did money move that nothing authorized?Ledger and bank statement import
Can a controller or auditor see it in one place?Signed reconciliation report
Can one cap cover card spend and wires together?Shared limits
Can we prove a specific person approved this exact payment?Approver signatures
A customer disputes a payment months later. What do we show?Decision bundles
How do we know the log wasn't rewritten, even by Auditail?Independent timestamps

Settlement checks​

Add settlement to an action in your policy:

"create_payout": {
"requireApproval": [{ "field": "amount", "op": ">", "value": 10000 }],
"settlement": {
"expectWithin": "3d",
"currencyField": "currency",
"tolerance": 0.01,
"onMissing": "freeze_agent",
"onMismatch": "alert"
}
}

From then on, every authorized create_payout (allowed by policy, or approved by a human) gets a settlement expectation: the amount and currency that were authorized, and a deadline.

FieldMeaning
expectWithinHow long a trusted outcome may take, from 5m to 90d.
from"authorized" (default): the clock starts at authorization. "redeemed": it starts when the receipt is redeemed, so only executed payments are tracked.
amountField, currencyFieldWhere the payload holds them. Default amount; no currency check unless currencyField is set.
toleranceAllowed absolute difference between authorized and settled amount. Default 0.
onMissing, onMismatch"alert" (default): a webhook alert and an event in the log. "freeze_agent": also freeze the agent until an approver investigates.

An expectation ends in one of these states:

  • settled: a trusted outcome reported it settled, within the tolerance.
  • mismatch: it settled for a different amount or currency. Event reconciliation.mismatch.
  • failed: the payment failed or was voided. The budget is given back to your limits.
  • reversed: it was returned or refunded.
  • overdue: no trusted outcome by the deadline. Event reconciliation.overdue. A late report still resolves it, and the report shows it as late.

Only trusted outcomes count. An agent can't close its own expectation by reporting "settled". Trusted outcomes come from:

  • an approver token (POST /v1/outcomes, for example from your settlement job),
  • a signed payment-provider event (below),
  • an imported bank or ledger line (below).

GET /v1/settlements?status=overdue lists expectations by state.

Payment providers report outcomes for you​

ProviderEventOutcome
Stripe Issuingissuing_transaction.created (capture or refund)settled or refunded, with the captured amount, matched to the authorization Auditail decided
Airwallexpayout.transfer.paid, payout.transfer.failedsettled (with the transfer amount) or failed
Modern Treasurycompleted, failed, returnedsettled (with the amount), failed or reversed

For Stripe, transaction events come from a regular webhook endpoint, which has its own signing secret: add it as a second stripe_issuing connection. A capture larger than the authorization (a tip, a currency conversion) shows up as a mismatch, with the difference.

Import bank or ledger lines​

Upload lines from a bank statement or an ERP export, with an approver token:

curl -X POST https://api.auditail.io/v1/reconciliation/lines -H "Authorization: Bearer $AUDITAIL_APPROVER_TOKEN" -H "Content-Type: application/json" \
-d '{"source":"bank_statement","lines":[
{"externalTxId":"BANK-101","amount":4200,"currency":"EUR","bookedAt":"2026-11-17","auditId":"dec_..."},
{"externalTxId":"BANK-202","amount":980,"currency":"EUR","bookedAt":"2026-11-17"}]}'

Each line is matched to an authorization by auditId or receipt when you have it, or by externalTxId when an earlier outcome reported that reference. A matched line is recorded as a trusted "settled" outcome and reconciled like any other. A line that matches nothing is money that moved without an Auditail authorization: it's listed, recorded as reconciliation.unauthorized and sent as an alert. Importing the same line twice does nothing (duplicates). Up to 1,000 lines per request.

This works with any bank or ERP that can export a statement. There are no built-in NetSuite or QuickBooks connectors yet; a scheduled export plus this endpoint does the same job.

The reconciliation report​

GET /v1/report/reconciliation?from=&to= (default: the last 30 days) returns a report signed by Auditail:

{
"format": "auditail-reconciliation-report-v1",
"summary": { "authorized": 412, "executed": 409, "settled": 401, "settledLate": 3, "mismatched": 2, "failedOrVoided": 4,
"reversed": 1, "overdue": 1, "openNotYetDue": 3, "unauthorizedLedgerLines": 1, "authorizedAmount": 1830400, "settledAmount": 1826950 },
"exceptions": [{ "subject": "dec_...", "kind": "mismatch", "authorized": { "amount": 300, "currency": "EUR" }, "settled": { "amount": 330, "currency": "EUR" } }],
"unauthorizedLedgerLines": [{ "source": "bank_statement", "externalTxId": "BANK-999", "amount": 4800, "currency": "EUR" }],
"integrity": { "chain": { "ok": true }, "checkpoint": "atc1...." },
"signature": "ats1...."
}

It's the three-way match: authorized (policy or human), executed (receipt redeemed), settled (trusted outcome), plus the exceptions a controller needs to look at. Verify it offline with npx -p auditail-sdk auditail-verify report.json. Amounts are compared in the units your policy and outcomes use; Auditail doesn't convert currencies.


Shared limits: one cap across rails​

A card program can't see your wires, and your bank can't see your card spend. Put a limit across several actions at the top of the policy:

"sharedLimits": [
{ "name": "daily-spend", "actions": ["card_payment", "create_payout"], "window": "24h", "sum": "amount", "max": 50000, "onExceed": "require_approval",
"when": [{ "field": "currency", "op": "==", "value": "USD" }] }
]

A shared limit works like an action's own limits (sum or count, groupBy, when, onExceed), counted across all the listed actions. The actions must use the same field and unit for the amount; Stripe Issuing payloads use major units (amount), like a typical payout payload. getCapabilities() shows shared limits with shared: true, and trusted failed outcomes give the budget back, as for any limit.


Approver signatures​

An approver token proves someone with that token clicked "approve". An approver signature proves the holder of a specific key approved this exact payload, and Auditail can't produce one.

In the dashboard: open Approval signing key and click Create a signing key on this device. The browser generates an Ed25519 key that can't be exported, keeps it in this browser's storage, and registers the public key. From then on, every approve or deny from that browser is signed. Needs a current browser (Chrome, Edge, Firefox, Safari).

From your own service (an approver deciding through the API):

import { generateApproverKey, importApproverKey, signApproval } from 'auditail-sdk';

const key = await generateApproverKey(); // once: store key.privateKeyJwk in your secret store
// register key.publicKey: POST /v1/approver-keys { "publicKey": "..." } with your approver token -> { id: "apk_..." }

const approval = await (await fetch(`${API}/v1/approvals/${id}`, { headers: { authorization: `Bearer ${APPROVER_TOKEN}` } })).json();
const signature = await signApproval({ account: 'key_...', approvalId: id, decision: 'approve', payload: approval.payload,
keyId: 'apk_...', privateKey: await importApproverKey(savedJwk) });
await fetch(`${API}/v1/approvals/${id}/decision`, { method: 'POST', headers: { authorization: `Bearer ${APPROVER_TOKEN}`, 'content-type': 'application/json' },
body: JSON.stringify({ decision: 'approve', signature }) });

The signed statement is the ASCII string auditail-approval:v1:<account>:<approval id>:<approve|deny>:<sha256 of the canonical payload JSON>:<signedAt>. Any Ed25519 library can produce it (Python: cryptography). The payload hash is computed by the signer from the payload they reviewed, not taken from the server.

  • Require it per action with "requireSignedApproval": true. Unsigned approvals of that action get 422 signature_required; denials don't need a signature.
  • Signatures go into the approval's events in the hash-chained log, the approval receipt carries asig (how many approvers signed), and decision bundles include them with the key registrations.
  • Key registration and revocation are recorded in the log (approver.key_registered, approver.key_revoked). Each approver can have up to 5 active keys and can revoke only their own: POST /v1/approver-keys/{id}/revoke.

Limits, plainly. Auditail binds a key to the approver token that registered it. A key registered by someone who had stolen that token would sign as that approver, so review the key list (GET /v1/approver-keys) and the registration events. The browser key lives in that browser profile; clearing site data removes it, and you'd create a new one.


Decision bundles: one file per payment​

GET /v1/evidence/{auditId} (a decision id dec_... or approval id apr_...) returns everything about one authorization in one signed file:

  • the payload, the outcome, and the exact receipt that authorized it,
  • the policy version in force: its full text, its hash, and its policy.updated event in the log,
  • the agent session, and whether it had read untrusted content (with the session.tainted events),
  • the human approval: who, when, comments, and each approver's own signature with their key registration,
  • receipt redemption, outcomes, the settlement check and matched ledger lines,
  • the contiguous stretch of the hash chain that links all of these, a signed checkpoint for its end and, when available, an independent RFC 3161 timestamp covering it.

Verify it offline:

npx -p auditail-sdk auditail-verify auditail-evidence-apr_....json --write-timestamp token.der
# ok signed by Auditail and unchanged since it was generated
# ok 41 log event(s) recompute and link to a signed checkpoint (#5120)
# ok receipt (human approval) matches the payload, policy v12, session conv-881 (had read untrusted data)
# ok policy v12 text matches its hash and the log
# ok Priya signed "approve" for this exact payload with their own key
# ok independent RFC 3161 timestamp from http://timestamp.digicert.com at 2026-11-17T12:25:33Z covers the log up to #5120; ...
openssl ts -verify -digest <imprint> -in token.der -token_in -CAfile <DigiCert chain>

Use it for a chargeback or vendor dispute, a customer complaint, or an auditor's sample. If the related events are more than 5,000 log entries apart, the bundle says so and you verify their position with a full export.


Independent timestamps (RFC 3161)​

Signed checkpoints prove what Auditail said about your log. A timestamp from an independent authority proves the log head existed at a given time, signed by someone other than Auditail. A rewrite after that time can't be hidden, even by us, and even from someone who never saved a checkpoint.

  • Every hour, for each account whose log changed, Auditail asks a public timestamp authority (by default DigiCert's free RFC 3161 service) to sign the SHA-256 of auditail-checkpoint:v1:<account>:<seq>:<event hash>. Only that hash is sent.
  • GET /v1/timestamps lists them. Evidence exports and decision bundles include the ones they cover, and auditail-verify checks each token carries the right imprint for that event.
  • Check the authority's signature with standard tools, not ours: openssl ts -verify -digest <imprint> -in token.der -token_in -CAfile <chain>. We tested this with DigiCert's service and OpenSSL 3.
  • Dedicated deployments can use another RFC 3161 authority.
  • Keep a copy. Like a checkpoint, a timestamp only protects you if a copy exists outside Auditail: timestamp authorities sign but don't publish what they signed. Exports and decision bundles carry the tokens, so archiving your periodic exports is enough.

Compliance mappings in the examiner report​

The examiner report now also answers "Did what was authorized match what settled?" (in additionalQuestions; the four regulator questions are unchanged) and includes controlMappings: where its evidence is relevant to SOC 2 (CC6.1, CC6.3, CC7.2, CC7.3/7.4, CC8.1), SOX IT general and disbursement controls, and the EU AI Act's record-keeping and human-oversight articles (12, 14, 26(6)) for systems that are high-risk.

These are pointers for your auditor, not claims of compliance. Whether a control is designed and operating effectively is for your institution and its auditors to judge.


Endpoints​

EndpointCredential
GET /v1/settlements?status=Approver or full-access key
POST /v1/reconciliation/linesApprover
GET /v1/report/reconciliation?from=&to=Approver or full-access key
GET /v1/evidence/{auditId}Approver or full-access key
GET /v1/timestamps?limit=Approver or full-access key
POST /v1/approver-keys, POST /v1/approver-keys/{id}/revokeApprover
GET /v1/approver-keysApprover or full-access key