Shared-account spend controls

The reservation ledger records gateway exposure. It is not a wallet and does not collect or transfer customer funds.

Before admitting purchases, staff configure a positive daily provider-cost cap, a positive per-transaction maximum no greater than that cap, and positive rolling one-minute and one-hour admission counts. The account also needs a positive low-balance threshold and staff email recipients. Unset values never mean unlimited. All vendor tokens share the same controls.

used allowance = gross completed provider cost attributed to today
               + every outstanding reservation, including older days

The calendar day is Africa/Johannesburg. PostgreSQL connections store timestamps in UTC. Reservations survive midnight, worker restarts and timeouts. Verified cancellations, rejections and declines release outstanding reservations. A reversal retains gross completed spending for its attributed day.

Velocity counts newly admitted purchases. Exact replays add nothing; subsequent failures do not remove admissions. API read throttles are separate from purchase velocity, allowing status polling while purchase limits are exhausted.

Pause actions

Operations → Pause all purchases and Vendors → Pause vendor purchases require a reason and write an audit entry with actor, timestamp, previous/new state and affected counts. A pause rejects new admissions, cancels queued requests that have not been dispatched, and prevents subsequent confirmation of an unconfirmed purchase. Known unconfirmed provider holds are cancelled when possible.

The committed dispatch claim is the boundary: an already dispatched HTTP request may finish after the pause. Its reservation and original identity remain tracked. Uncertain cancellation is never displayed as cancelled. Reads, reconciliation, callbacks and fulfilment retrieval remain available.

Resume is an explicit administrator action. Cancelled queued requests never restart. Reducing a limit takes effect at admission and again when existing queued or unconfirmed work is claimed.

Balance monitoring

The provider's available and holding balances are polled each minute, with the successful read timestamp. Below-threshold incidents create persistent dashboard notifications for configured recipients with staff accounts and email for every configured address. Incidents deduplicate, remind at most hourly and notify on recovery.

A failed read retains the last value as stale. Five minutes without a successful read creates a separate monitoring incident. Recovery closes it. The threshold does not automatically pause purchases; administrators retain the shared-account kill switch.

External monitoring must check the scheduler and workers themselves: a stopped process cannot send its own stale-reading alert. Use dtone:readiness, operations heartbeats and process supervision.

Confirmation and reconciliation limits

Never-dispatched requests expire at the original quote expiry plus DTONE_CONFIRMATION_GRACE_SECONDS, default 60 seconds. If reconciliation later finds a CREATED transaction after that deadline, the gateway cancels it instead of confirming. Uncertain cancellation keeps the reservation. A late verified completion is still recorded.

Only documented DT One create rejection codes release a reservation immediately. Duplicate external references, unknown error codes, malformed responses, timeouts and server errors remain uncertain. Confirmation and cancellation HTTP errors never prove the existing transaction cannot debit. Administrators can resolve a review transaction only with a provider evidence reference, reason and explicit no-further-debit attestation. The action rejects recent dispatch claims and records its audit and vendor event atomically. Elapsed time or an empty lookup is not evidence.

The exact quoted selling charge is retained. A lower provider cost is accepted when benefit and spend checks pass. Increases up to DTONE_COST_TOLERANCE, default 0.01 in provider account currency, are accepted only if the actual converted cost is still covered by the charge and the vendor's limits permit it. The tolerance never increases a financial limit. Staff-only provider_cost_checked events record quoted and actual costs, delta, tolerance and acceptance for provider mismatch measurement.

Ordinary completed-transaction polling stops after DTONE_REVERSAL_WATCH_DAYS, default 14 days. Unresolved work is scheduled first. Valid callback hints can request verification beyond this window. Gross completed spending remains unchanged by reversals.

Catalogue and exchange rates

Imports stage provider facts in chunks before a short atomic publication. Reads use the last published run until all staging succeeds. Local names, visibility and product identities survive missing products and reappearance. DTONE_CATALOGUE_MIN_RETAINED_RATIO, default 0.8, blocks imports that lose more than 20% of the available catalogue. Review a rejected shrink before changing that guard.

Operations publishes one immutable account-wide exchange-rate version, with actor and reason. New quotes across all vendors use it; expired rates block new foreign-currency quotes. Pricing drafts contain only markup or margin rules. Legacy vendor rates are ignored for new quotes and must be replaced by a staff-published account rate. Old quotes keep their recorded rate and version. Historical spread uses each transaction's recorded conversion; records from older vendor-specific rates are not restated.