Docs / Concepts

Mandate

LiveUpdated September 25, 2026

A mandate is the proof that a specific payment was authorized: by which policy, by which person if one was needed, for which exact request. It is immutable once signed; what moves is the ledger Enruta keeps for it.

Properties#

• Verified at issuance. All checks run when the mandate is created. The payment path only looks up and counts, so it adds under 10 ms inside a rail’s authorization window.
• Single use. A consumed state moves from issued to consumed, expired or void exactly once. One consent cannot pay twice.
• Bound to the request. The mandate carries the hash of the canonical request: payee, amount, currency, purpose, checkout reference. A different request needs a different mandate.
• Short lived. Default expiry 15 minutes; configurable per policy down to seconds.
• Idempotent. Every request carries an idempotency key. A retried tool call returns the same decision and the same mandate; it never mints a second one.

The signed claims#

The mandate is an ES256 compact JWS, header { alg, kid: "key_enruta_mandate_2026-09", typ: "enruta-mandate+jwt" }. It is the ap2.checkout_mandate a UCP merchant receives in complete_checkout; the merchant verifies it with the keys of Enruta’s platform profile.

The JWS carries what the merchant may see. Without a visibility_scope a mandate is issued as the table shows, and the ceilings (per_payment_cap, budget, the tolerated deviation, a recurrence’s caps) are not in it. With one, every constraint the scope keeps from the merchant leaves the JWS and is committed to by hidden_constraints_digest, and a ceiling the scope names under merchant joins the claims (per_payment_cap: { amount, currency }, budget: { amount, currency, window }).

Mode, refill policy, finality class, deviation#

Retry policy and what the merchant sees#

A policy with a $500 cap, a $1,000 monthly budget, retry_policy: { max_attempts: 3, window_seconds: 86400, same_amount_only: true } and visibility_scope: { merchant: ["retry_policy"], issuer_only: ["per_payment_cap", "budget", "policy"] } issues this mandate to the merchant:

{
  "iss": "https://enruta.ai", "sub": "org_halvern", "mandate_id": "mnd_01M3F2…", "agent": "agt_procurement_02", "binds": "sha256:9f1c…2e4a",
  "amount": "77.04", "currency": "USD", "payee": "reamandrule.com",
  "checkout": { "protocol": "ucp", "reference": "chk_01M3F1…" }, "checkout_hash": "sha256:…",
  "mode": "bounded_stepup", "refill_policy": "never", "finality_class": "reversible",
  "principal_login_id": "halvern/dana.reyes@halvernrobotics.com",
  "retry_policy": { "max_attempts": 3, "window_seconds": 86400, "same_amount_only": true },
  "hidden_constraints_digest": "sha256:5b0e…41a7",
  "iat": 1789048800, "exp": 1789049700
}

The policy reference, the cap and the budget are not in it. Their values, with a random salt, stay with the principal in the record’s bundle; the API’s mandate object (GET /v0/mandates/{id}) shows retry_policy, visibility_scope and hidden_constraints_digest, never the salt or the hidden values:

"artifacts": {
  "hidden_constraints": {
    "salt": "h3Xq…Zp0w",
    "constraints": {
      "policy": { "id": "pol_office_supplies", "version": 4 },
      "per_payment_cap": { "amount": "500.00", "currency": "USD" },
      "budget": { "amount": "1000.00", "currency": "USD", "window": "calendar_month" }
    }
  }
}
// hidden_constraints_digest = sha256 over the RFC 8785 form of { constraints, salt }

The merchant checks its charge against the amount, the payee and the checkout, which it always sees, and verifies the mandate as before: POST /v0/sellers/verify and the Accept middleware accept it. The sealed record’s mandate carries retry_policy, visibility_scope and hidden_constraints_digest. enruta-verify recomputes the digest from the bundle and checks that no hidden constraint also travels as a claim and that the record’s terms are the ones signed, so a changed cap fails the keys check (hidden constraints do not match the mandate’s hidden_constraints_digest); a bundle without the hidden values, as a merchant would hold it, is reported rather than failed. Constraints the policy does not set are not committed to, and a scope that keeps nothing the mandate carries adds no digest. What counts as a retry, and what retryable means on a decision: Decision.

The mandate account#

The mandate does not change after signing. Enruta keeps a ledger for it (mandate.ledger in the record, GET /v0/mandates/{id}), in decimal strings:

The budget in the policy follows the same events: a refilled amount is subtracted from what the window has spent, never below zero.

// the $24.98 purchase of 2026-09-10, then a $9.99 refund three days later, refill_policy on_settled_refund
issued        ceiling 24.98  reserved 24.98  authorized  0.00  captured  0.00  refilled 0.00  remaining 0.00
authorized    ceiling 24.98  reserved  0.00  authorized 24.98  captured  0.00  refilled 0.00  remaining 0.00
captured      ceiling 24.98  reserved  0.00  authorized  0.00  captured 24.98  refilled 0.00  remaining 0.00
refund 9.99   ceiling 24.98  reserved  0.00  authorized  0.00  captured 24.98  refilled 9.99  remaining 9.99
// the single-use mandate cannot be spent again; the $9.99 returns to the policy's monthly budget

The same words, “$1,000 a month”, mean four different things on four card issuers (some refill on refunds, some only on reversals, some cap clearing, some cap authorization). So the truth about a limit lives in the mandate account, and the rail’s limit is a fuse. When the two disagree, reconciliation raises RAIL_LIMIT_SEMANTICS_DIFF.

Human approval#

When a policy requires a person, the mandate is not issued until that person signs. The signature is a passkey assertion or an authenticated link, and it binds the request hash. A chat reaction or an e-mail reply is not an approval; the record would say so. A refund above reversal.step_up_above is approved the same way, bound to the reversal’s subject hash.

An approval never leaves a payment half done. If, after the person signs, the mandate cannot be issued because of a failure inside Enruta (the database, the key store, a rail connection missing its stored credentials), the approval is rolled back: it is pending again, the request waits for approval with no mandate, nothing is sealed, no approval.completed is sent and approval.rolled_back is logged, so the person can approve again once it is fixed. A rail that fails while issuing hands the payment to a person instead, and the approval stands.

People stay in charge while an approval waits. When the person approves, the agent’s pause and the consent the decision relied on are checked again. If the agent was paused, or the user revoked that consent, no mandate is issued: the approval expires, the request closes expired with agent_paused or consent_revoked (not retryable), the budget reservation is released, the record is sealed, approval.completed carries the reason, and the person is told “This payment can no longer be approved”.

Compiled into the rail#

Lifecycle#

requested ─▶ decided ─▶ issued ─▶ consumed ─▶ (settlement: captured ─▶ settled)
                 │            ├─▶ expired
                 │            └─▶ void (handed off, or cancelled by a reversal before authorization)
                 ├─▶ observe ─▶ issued …   (shadow mode)
                 ├─▶ step_up ─▶ approved ─▶ issued …
                 ├─▶ not issued: the rail hands the payment to a person (handed_off)
                 └─▶ denied

How a payment ends#

Three ways. The agent presents the mandate and the credential to the merchant itself (Claude Code, Codex, any host that may carry the credential). Enruta presents them for it (complete_checkout: true, for hosts that block the credential). Or the merchant does not accept the credential from an agent at all: merchants that complete checkout only on their own page. Then the agent hands the person the merchant’s continue_url and tells Enruta (hand_off_checkout, or POST /v0/payment-requests/{id}/handoff): the mandate is voided, the request moves to handed_off, and once the person has paid the agent reports the order. The record seals with that order as a self-asserted receipt and outcome completed; without one it seals 15 minutes after the hand-off in state handed_off.

A payment can also end before a mandate exists. When the policy allows it (or a person approves it) but the rail cannot issue a credential, the request moves to handed_off with mandate: null and a handoff that names the rail, its reason, its message and the next_step for a person: Link above its 500 USD limit, a read-only Bill.com connection, or a rail that fails while it issues (rail_unavailable, rail_error). Nothing was paid, the budget reservation is released, and the record seals at once with that outcome (Rails).