API

Ask to pay. Returns the decision, and the mandate and credential on allow or observe. Requires Idempotency-Key.

curl https://api.enruta.ai/v0/payment-requests \
  -H "Authorization: Bearer $ENRUTA_AGENT_KEY" \
  -H "Idempotency-Key: a3c9…" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agt_procurement_02",
    "payee": { "name": "Ream & Rule", "domain": "reamandrule.com" },
    "amount": { "value": "24.98", "currency": "USD" },
    "purpose": "2 packs of ballpoint pens for the office",
    "checkout": { "protocol": "ucp", "reference": "chk_01M2511XQ4N7B8T2R6H9K3W5MD" },
    "evidence": [{ "type": "checkout", "ref": "https://reamandrule.com/checkout-sessions/chk_01M2511XQ4N7B8T2R6H9K3W5MD", "digest": "sha256:4b1c…" }],
    "intent": { "text": "Order two packs of pens, keep it under $30", "slots": { "quantity": 2, "max_total": "30.00" } },
    "catalog_snapshot_hash": "sha256:0d3e…"
  }'

import { Enruta } from "@enruta/sdk";
const enruta = new Enruta(process.env.ENRUTA_AGENT_KEY!);

const r = await enruta.paymentRequests.create({
  agentId: "agt_procurement_02",
  payee: { name: "Ream & Rule", domain: "reamandrule.com" },
  amount: { value: "24.98", currency: "USD" },
  purpose: "2 packs of ballpoint pens for the office",
  checkout: { protocol: "ucp", reference: "chk_01M2511XQ4N7B8T2R6H9K3W5MD" },
  intent: { text: "Order two packs of pens, keep it under $30", slots: { quantity: 2, max_total: "30.00" } },
}, { idempotencyKey: "a3c9…" });

if (r.decision.result === "allow" || r.decision.result === "observe") pay(r.mandate!.credential);

201 Created
{
  "id": "preq_01M2511Z7H3K9Q2W5T8N4B6RXD",
  "state": "decided",
  "decision": { "result": "allow", "reasons": [], "policy": { "id": "pol_office_supplies", "version": 4 },
                "checks": [{ "name": "agent_state", "ok": true }, { "name": "consent", "ok": true, "detail": "cns_01M2F0…" }, { "name": "payee_allowlist", "ok": true }, …],
                "retryable": false, "retry_after": null },
  "risk": { "id": "rsk_01M2511ZB2…", "action": "authorized", "score": 0 },
  "mandate": { "id": "mnd_01M2512M8FQ7ZK4T1V9W3N6BXC", "amount": "24.98", "currency": "USD", "expires_at": "2026-09-10T17:57:08Z",
               "mode": "bounded_stepup", "refill_policy": "never", "finality_class": "reversible",
               "retry_policy": { "max_attempts": 3, "window_seconds": 86400, "same_amount_only": true }, "visibility_scope": null, "hidden_constraints_digest": null,
               "jws": "eyJhbGciOiJFUzI1NiIs…",
               "credential": { "type": "token", "handler_id": "enruta_card", "token": "ectok_…" } },
  "approval": null,
  "record_id": "rec_01M25129GZMJXTNQ47TMZRDGHN"
}

Body fields added since v0: intent { text?, slots? } (the 0.2 intent_text, constraints and intent_mapping are still accepted), catalog_snapshot_hash?, policy_snapshot_hash?, deviations?. The caller’s IP is captured from the request as agent_ip. On clarify the response carries state: awaiting_clarification, mandate: null and decision.questions[]; on step_up it carries mandate: null and approval { id, url, expires_at }; on observe it carries the mandate and decision.shadow_result. Every decision carries retryable and retry_after (retrying), and a mandate carries retry_policy, visibility_scope and hidden_constraints_digest (null when the policy sets none), never the values it keeps from the merchant. complete_checkout: true (UCP checkouts only) asks Enruta to execute the checkout itself and adds order and completion to the response. When the rail cannot issue a credential for an allowed payment, the response carries state: handed_off, mandate: null and handoff { rail, reason, message, next_step } instead, and with complete_checkout a failed completion whose error says the payment was handed off and why (see “When the rail cannot issue” below).

The request, its current decision (with retryable and retry_after), the approval and mandate state, order and completion when Enruta placed the order, outcome, handoff, and since this release risk, settlement, reversals[], reconciliation, disputes[] and fulfillment summaries. state is one of decided, awaiting_clarification, awaiting_approval, approved, handed_off, declined, expired, executed, completed. Poll this after a step_up (?wait=25 holds the request open until something changes), or subscribe to the webhook.

{ "continue_url": "https://shop.example/cart/c/…",
  "order": { "id": "gid://shopify/Order/…", "status": "completed", "permalink_url": "https://…", "total": { "amount": "699.95", "currency": "USD" } } }

For merchants that complete checkout only on their own page: the checkout was handed to a person at the merchant’s continue_url. Without order: the request moves to handed_off, the mandate to void, the budget reservation is kept. With order (on the first call or a later one): the order becomes the receipt (self_asserted), outcome.status becomes completed, and the record seals. Repeats are idempotent. A request the rail handed off (below) has no checkout and no order to report: the call answers 409.

{ "url": "https://data.example/v1/prices?symbol=ACME",
  "method": "GET",
  "headers": { "Accept": "application/json" } }

200 {
  "paid": true,
  "request_id": "preq_01M3E6…", "mandate_id": "mnd_01M3E6…", "rail": "x402", "authorization_id": "x402_01M3E7…",
  "status": 200,
  "headers": { "content-type": "application/json", "payment-response": "eyJzdWNjZXNzIjp0cnVl…" },
  "body": "{ \"symbol\": \"ACME\", \"price\": \"41.20\" }",
  "truncated": false,
  "receipt": { "success": true, "transaction": "0x5d1c…", "network": "eip155:8453" },
  "record_id": "rec_01M3E6…",
  "answered_in_ms": 812
}

Pays an HTTP resource that answers 402 Payment Required (x402 or MPP) with the mandate of an allowed payment request, and returns what the resource answered. Only the request’s own agent key: a developer key gets 403, another agent’s key 404. The body is strict: url, method (GET when absent, or POST, PUT, PATCH, DELETE), up to 50 headers (none that Enruta or the transport sets, such as Host, Content-Length, Payment-Signature or X-Payment) and body, a string of up to 256 KB that a GET never carries. The URL is https, on the payee’s domain, and exactly the request’s checkout.reference when the request named one.

The request must hold an issued mandate on an x402 or mpp rail, or an MPP mandate whose payment channel is open. Enruta calls the resource, pays its 402 inside the mandate (never more, and only to the payee) and answers 200 with paid, the resource’s status, a safe subset of its headers (content, caching, redirects and payment receipts), its body as text up to 256 KB (truncated when cut) and the receipt (the x402 PAYMENT-RESPONSE or the MPP Payment-Receipt). A paid resource seals the payment record, and the settlement record once its stage is final. When the rail refuses, the answer is paid: false with reason (amount_exceeds_mandate, merchant_mismatch, rail_declined, rail_timeout, …) and detail, and the mandate stays usable. 400 for a URL off the payee or other than the one the request named, or a malformed body; 409 when no mandate can pay: the approval or the clarification is still open, the payment was handed off or denied, the mandate was used or has expired, or its rail pays no HTTP resources. MCP pay_http_resource; CLI enruta pay-resource.

{ "answers": [{ "question_id": "q_max_total", "answer": "100.00" }], "answered_by": "user" }

Answers the questions of a clarify decision and decides the request again; returns the request. The request’s agent key or a developer key. answered_by is user unless the body says agent (intent and clarification).

The money split of the payment: the flows and each party’s view, every line marked actual, estimate or plan, with its source and date. Agent keys read their own payments; developer and auditor keys any.

Checks a merchant before paying and returns the result with its domain: status (verified, unverified or mismatch), each check, the seller organization and when. Agent, developer and auditor keys (trust model).

A fresh nonce for an agent_key proof.

{ agent_id, anchor: { type, party?, …evidence } } verifies an identity anchor and seals a kya_attestation record. The v1 body (registry, registry_ref, method, evidence) is still accepted. GET /v0/attestations lists attestations with their type, tier and status.

The agent’s { assurance, anchors }.

{ agent_id, payee, currency, per_occurrence_max, cumulative_max, amount_variance: { type, pct? }, schedule: { interval, anchor }, end_date?, consent_id?, purpose } creates a recurrence and seals its record. GET /v0/recurrences lists them.

One recurrence. PATCH the same path to pause, resume or end it; every change is sealed. GET /v0/recurrences/{id}/occurrences lists the payments made under it.

{ "record_id": "rec_01M25129GZMJXTNQ47TMZRDGHN",     // or request_id, or mandate_id
  "kind": "refund",                                   // void | cancel | refund | return | credit | price_adjustment | chargeback_credit
  "amount": { "value": "9.99", "currency": "USD" },  // default: the remaining reversible amount
  "reason_code": "customer_request",
  "refund_to": "original_form_of_payment" }             // or credit

201 { "reversal": { "id": "rev_01M2G8YV5R3T7W2Q9K4N8B6DXP", "stage": "settled", "status": "completed", "fund_change": true,
                    "mandate_effect": "refill_pending_settlement", "reversal_record_id": "rec_01M2G8Z0Q4W7T2K9N5B3D6H1XC", … },
      "decision": { "result": "allow", "checks": [{ "name": "original_amount", "ok": true }, { "name": "stage", "ok": true }, { "name": "finality", "ok": true }, { "name": "window", "ok": true }, { "name": "cancellable_until", "ok": true }] },
      "adjustments": { "ucp": { … }, "acp": { … }, "adyen": { … }, "shopify": { … } } }

A reversal is a decision (allow, step_up above the policy’s reversal.step_up_above, or deny), executed by stage: a void before authorization, a reversal of an uncaptured authorization, a refund after capture. Agent keys may reverse their own records; developer keys any. Field by field: Reversal.

Filter with record_id, status, from, to; paginated.

One reversal with its events[], decision, approval and the id of its sealed record.

The reversal rendered as a merchant-side adjustment for ucp, acp, adyen or shopify (Adjustments).

The settlement record of a payment: stage, amounts, finality_class, finality_at, rail references, fulfillment. Agent (own), developer and auditor keys.

Generates (or returns) the dispute packet for a sealed payment record: the packet, its signed JWS, the CE3.0 element checklist and the six exports. POST to the same path regenerates it. Developer and auditor keys.

The one-page representment PDF, application/pdf.

Dispute packets and their outcomes. Filter with state, from, to. Agent keys see their own records’ packets.

{ "outcome": "won", "note": "Issuer accepted the mandate and login id", "submitted_to": "stripe" }

Records the outcome (won, lost, withdrawn), seals a dispute_outcome record chained to the packet, patches dispute_afterlife in the original record’s bundle, and emits dispute.outcome_recorded.

Reconciliation lines for an ISO week; state filters by match_state. GET /v0/reconciliation/lines/{mandate_id} returns one line. Developer and auditor keys.

The weekly report: counts by match state, exceptions with suggested actions, coverage, root hash, state draft or signed, the signer and the sealed record ids.

Builds or rebuilds the draft for the period. The weekly job does this for the previous week every Monday at 01:00 UTC.

Signs the draft by link key over the API; a passkey signature is made in the console. Signing seals every line and then the report as linked records.

Creates a consent record for an agent; GET /v0/consents lists them and GET /v0/consents/{id} reads one. Developer keys.

{ "effective_at": "2026-10-01T00:00:00Z", "cascades_scheduled": true }

Revokes a consent; every field is optional. effective_at is now when absent; a later time schedules the revocation and the consent stays active until then; a time more than a minute in the past is 400. Without cascades_scheduled new mandates stop and those already issued stay valid until they expire. With cascades_scheduled: true what the agent has scheduled stops too: recurrences made under the consent end, its unused mandates are voided, its pending approvals expire, and when no other consent covers the agent its other recurrences pause and the agent is paused. institution_notified_at records when a consumer told their institution. Answers 200 with the consent, its revocation { revoked_at, by, effect, institution_notified_at, effective_at, cascades_scheduled, notified_institution_at, cascade }, record_id and revoke_record_id. Idempotent: a revoked consent comes back as it is, and a scheduled revocation stands until it takes effect or one effective now brings it forward. Developer keys (consent record).

Pauses an agent with a reason; every later request is denied with agent_paused and the pause is a sealed record. POST /v0/agents/{id}/resume lifts it. Developer keys; the console has the same buttons.

Filter with agent_id, from, to and, since this release, kind (payment, reversal, settlement_record, …). GET /v0/records/{id} serves payment and linked records alike; add /bundle for the bundle, /verify for a server-side verification report, /linked for the records chained to this one.

{ "from": "2026-09-01", "to": "2026-09-30", "principal_login_id": "halvern/dana.reyes@halvernrobotics.com", "kinds": "all", "consents": true }
→ 202 { "id": "exp_01M2H4…" }
GET /v0/exports/{id} → a signed download URL when ready

An export is a zip: one .json per record with its .bundle.json, linked/ for the linked records in range, consents/ for the sealed consent records, the daily checkpoints, the verifier, the schema and a README with the verify command. The three new fields are optional; an export without them is exactly the v0 export. See Compliance export.

No authentication, five per IP per hour. Creates a sandbox organization with an agent key, a developer key, the sample policy and a claim URL a person can open later (quickstart).

Delegates approval to a member or an e-mail address within a scope { max_amount, payees?, agents?, until }. GET /v0/approval-delegations lists them; DELETE /v0/approval-delegations/{id} revokes one (Signed policy).

slack_webhook_url (approval requests also post to Slack), psp_profile (the merchant’s PSP pricing, used by the money split) and sso. Developer keys or the console.

Starts the organization’s verification: a DNS TXT record enruta-verification=<token> for a company’s domain, or a Stripe Identity session for an individual (test mode today). A verified organization can back a legal_entity anchor.