VERDOCK

Outcome checks and reconciliation

After every action Verdock reads the provider record on its own and compares it with what the policy expected. UNKNOWN is read and reconciled, never repeated.

On this page

A payment gateway decides if an action can run. It does not prove what the action did. Verdock reads the real record after the action and compares it with what it expected.

The four states#

StateMeaningRetry
VERIFIEDEvery compared field matches.Done. Never repeat.
MISMATCHAt least one compared field differs. Raised to a person.Only under a retry rule of safe.
UNKNOWNThere is no observed record, or a compared field is missing. It is not known whether the action happened.Never. Read and reconcile.
PENDINGThe provider reports a status that is still in progress.Never. Wait for a final status.

may_retry(state, retry) is True only for MISMATCH under a safe rule. An UNKNOWN operation becomes VERIFIED in the outcome log only with an observed record that compares VERIFIED against the stored expectation.

A lost response#

The provider executes and the response is lost. The action is UNKNOWN and held, the retry is refused, another payout keeps moving, and a ledger read settles it. A naive agent pays twice. Verdock pays once.

Terminal
verdock demo --scene unknown

Compare in code#

Python
from verdock.outcome import OutcomeLog, compare

log = OutcomeLog("outcomes.sqlite3")
expected = {"amount_minor": 1500, "currency": "USD"}
log.expect("order-77-payout", expected, expected.keys())
state = compare(expected, observed_record, expected.keys())
log.record("order-77-payout", state, observed_record)

compare(expected, observed, fields, status_field=None, pending_values=()) returns the state. An observed value of None gives UNKNOWN. When status_field is given and the observed value is in pending_values, the result is PENDING. The comparison is type strict: 1 and True are different values.

Reconcile#

reconcile finds the provider record without the lost id, reads it back and compares it. UNKNOWN becomes VERIFIED only when that record compares VERIFIED. If nothing is found the state stays UNKNOWN. It never creates anything. The adapters expose it as reconcile(request_key). See the Stripe adapter.