Reversal

LiveUpdated September 14, 2026

Agents and Sellers. Written for people who build agents, the hosts they run in, and the people and companies the agents pay for and merchants that receive agent orders.

A reversal is never an edit. Every void, cancellation, refund, return, credit or price adjustment is a new record with chain.relation: reversal_of, decided against the same policy as the payment, and its effect on the mandate account is a field, not a guess.

Fields

Three ways in

1. The agent or the principal asks. request_reversal in MCP, POST /v0/reversals in REST, enruta reversals create in the CLI, or the “Request a refund” form on the payment page in the console.
2. The merchant reports. A UCP order webhook order_updated with adjustments[], the seller’s own call to POST /v0/sellers/adjustments or POST /v0/sellers/reversals (Adjustments), or a refund webhook from the merchant’s PSP connection. The reversal carries initiator: merchant and the merchant’s signature when it signed the order.
3. The rail reports. A Stripe Issuing issuing_transaction.created of type refund completes the pending reversal it matches, or creates one with initiator: rail, kind: refund, reason_code: other; issuing_authorization.updated with status reversed completes a void.

A reversal is a decision

evaluateReversal() runs before anything moves, every check reported in decision.checks[]:

Any failure denies, and the denial is sealed at once (status: denied, outcome: null). When the policy sets reversal.step_up_above and the initiator is not the merchant, an amount above it steps up: an approval bound to the reversal’s subject hash, signed by passkey or link, the page reading “Refund $9.99 to reamandrule.com”. Otherwise allow.

What it does to the mandate account

On completion the mandate account gains refilled += amount and the policy budget gets the amount back, never below zero. A single-use mandate cannot be spent again; the refill matters to the budget.

Execution by stage

The record

On completion (or denial) Enruta seals a linked record: kind: reversal, chain: { relation: "reversal_of", of: <payment record>, of_hash }, subject = the reversal with its events[], decision, approval when any, outcome: { status: refunded | voided | cancelled, amount, currency, posted_at }. When the adjustment came signed from the merchant, the bundle carries artifacts.subject_signature and the merchant key and strength.subject is third_party_signed; when a rail event completed it, artifacts.rail_event. The original record’s bytes never change.

// the $24.98 order of 2026-09-10, refunded $9.99 by the merchant three days later
{
  "id": "rev_01M2G8YV5R3T7W2Q9K4N8B6DXP",
  "record_id": "rec_01M25129GZMJXTNQ47TMZRDGHN",
  "mandate_id": "mnd_01M2512M8FQ7ZK4T1V9W3N6BXC",
  "kind": "refund", "stage": "settled",
  "amount": { "value": "9.99", "currency": "USD" },
  "initiator": "merchant", "initiator_ref": "reamandrule.com",
  "reason_code": "customer_request",
  "protocol_ref": { "protocol": "ucp", "order_id": "ord_01M2512SM3V3A9R4EBJM8RRRV5", "adjustment_id": "adj_01M2G8Y2K5T8W3Q6N9B1D4H7XR" },
  "rail_ref": { "rail": "stripe_issuing", "authorization_id": "iauth_1S7Kq2…", "transaction_id": "ipi_1S7Rn4…" },
  "mandate_effect": "none",                      // the policy's refill_policy is never
  "finality_class": "reversible",
  "status": "completed", "fund_change": true,
  "refund_to": "original_form_of_payment",
  "occurred_at": "2026-09-13T15:03:40Z", "settled_at": "2026-09-13T15:04:02Z",
  "events": [
    { "type": "enruta:reverse:requested", "at": "2026-09-13T15:03:41Z", "by": "merchant" },
    { "type": "enruta:reverse:rail-completed", "at": "2026-09-13T15:04:02Z", "ref": "ipi_1S7Rn4…" }
  ],
  "decision": { "result": "allow", "reasons": [], "checks": [{ "name": "original_amount", "ok": true }, { "name": "stage", "ok": true }, { "name": "finality", "ok": true }, { "name": "window", "ok": true }, { "name": "cancellable_until", "ok": true }] },
  "reversal_record_id": "rec_01M2G8Z0Q4W7T2K9N5B3D6H1XC",
  "dedupe_key": "ord_01M2512SM3V3A9R4EBJM8RRRV5:adj_01M2G8Y2K5T8W3Q6N9B1D4H7XR"
}

Interfaces

A rule for agents, written into the skill: a reversal is a decision; report it, and never retry a denied reversal with another amount.