Agentic Payment Reconciliation State Machine
Reconcile AI agent payments across authorization, submission, provider acceptance, uncertainty, settlement, failure, return and reversal without duplicates.
Agentic payment reconciliation connects the authorized request to what the provider later reports. It must preserve uncertainty, late acceptance, settlement, return and reversal as distinct states. A model statement such as "payment completed" is not a provider outcome.
Agentic Payments covers the authorization path before dispatch. This state machine begins when the adapter sends the request and the answer may be late, duplicated or missing.
Keep three state families
authorization: PROPOSED -> DENIED | APPROVAL_REQUIRED | AUTHORIZED
execution: AUTHORIZED -> SUBMITTED -> ACCEPTED | REJECTED | UNCERTAIN
outcome: ACCEPTED -> SETTLED | FAILED | RETURNED | REVERSED
Do not rewrite UNCERTAIN to FAILED because a timeout elapsed. Append the later observation with its source and time.
type PaymentObservation = {
transactionId: string;
state: string;
observedAt: string;
effectiveAt?: string;
source: 'adapter' | 'provider_webhook' | 'provider_query' | 'ledger';
externalReference?: string;
payloadDigest: string;
};
Reconcile deterministically
The reconciler queries by original provider idempotency key or external reference. It verifies webhook origin, deduplicates events and applies permitted transitions. An impossible regression or mismatched amount opens an exception rather than silently changing state.
| Current | Observation | Action |
|---|---|---|
| submitted | provider accepted | append accepted |
| uncertain | provider settled | append accepted and settled |
| accepted | provider rejected with conflicting ID | open mismatch case |
| settled | provider reversed | append reversal |
| rejected | retry request | require explicit new decision or documented provider rule |
Test recovery
Simulate response loss after provider acceptance, duplicated webhooks, events arriving out of order, clock skew, provider reference reuse, partial database failure and a reversal days later. The test should prove one business transaction, a monotonic evidence chain and visible unresolved cases.
Operate the exception queue
Every uncertain or conflicting transition needs an owner, next query time and maximum age. Group cases by provider and failure cause so a systemic outage does not become thousands of unrelated agent tasks. The agent can collect evidence and prepare a recommendation; a deterministic worker should apply state transitions.
Reconciliation must compare protected fields, not only external reference. Confirm amount, currency, destination or account, buyer entity and provider profile where the rail exposes them. A reference collision or wrong-tenant event should open a security case.
Do not let late webhooks overwrite a stronger source without a transition rule. A provider webhook and ledger query can disagree temporarily. Preserve both observations, rank their authority for each state and schedule another check.
Measure uncertain-case age, duplicate-event rate, impossible transitions and manual correction. Any manual correction needs the previous state, reason, operator identity and source evidence so the audit trail remains intelligible.
OpenTelemetry's logs model can carry trace and structured event correlation. Use a separate domain schema for payment semantics. AP2's specification provides protocol context for mandates and payment records.
See payment idempotency and the AI agent audit trail. The Intelliger agentic commerce platform is the live product destination.
Provider behavior varies. Validate transition rules against the selected rail and complete payments, accounting and legal review before production. OATI remains a developer preview.
Reconciliation design questions
How often should uncertain payments be queried?
Use provider limits, expected processing time and transaction risk. Start with bounded retries and backoff, then escalate at a maximum age. A high-value payment may need earlier human attention. Preserve every query observation without turning repeated absence into a definitive rejection.
Which event wins when sources disagree?
Define source authority per state. A provider query may outrank an unverified webhook for acceptance. The accounting ledger may own booked settlement. Preserve both records and open an exception when a transition conflicts. Do not use arrival order as truth.
How are duplicate webhooks handled?
Deduplicate by provider event identifier and payload digest within tenant and provider scope. Processing must be idempotent. Record duplicates for monitoring without appending the same business transition repeatedly. Test out-of-order delivery and retries after consumer crash.
Can the agent repair state?
The agent may collect evidence and propose a resolution. A deterministic reconciler or verified human should apply state changes under policy. Free-form model output must not mark a payment settled, reverse a ledger entry or release held budget without authoritative evidence.
When may held authority be released?
Release according to a terminal state and rail-specific procedure. A definitive pre-dispatch failure differs from an uncertain provider submission. If the state remains unresolved, an accountable operator may decide under documented policy, with the risk and evidence preserved.
How is reconciliation performance measured?
Track age by state, p95 time to resolution, impossible transitions, duplicate events, mismatched protected fields and manual corrections. Split provider outages from internal failures. Verify that every correction has an operator, reason and evidence reference.
Reconciliation also needs a close-of-period rule. An uncertain payment cannot remain invisible because it is not technically settled or failed. Finance should see its amount, currency, buyer entity, provider, age and possible accounting impact. Define who decides accrual, hold or disclosure treatment and keep that decision separate from the technical state.
Test a late reversal after the internal workflow has marked the invoice paid and released its budget reservation. The new provider observation should append a reversal, reopen the relevant finance process and preserve the earlier accepted and settled states. It must not overwrite history or rely on the agent to remember which downstream records need correction.
Write the transition rules as executable tests owned by payments engineering and finance operations together. Engineering knows which provider events can arrive and finance knows which state changes affect invoices, cash and controls. Neither team should infer the other's meaning from a generic status field. Keep provider-native codes in evidence, but translate them into a documented internal state only through the reconciler.
For each terminal state, document which reservations, approvals and downstream records may change. Settlement may consume budget and close an invoice. Reversal may reopen both. Rejection before dispatch may release authority immediately. Encoding those consequences beside the transition prevents a later worker from treating every terminal label as operationally equivalent.