{ "components": { "schemas": { "answer_purchase_questionInput": { "additionalProperties": false, "properties": { "answer": { "description": "What the user said, in their words: the reply to purchase.question, or feedback after purchase.follow_up. An otp question asks for the code the merchant sent the user to sign in: send it once, then never repeat or keep it. Never your own answer, and never a password, a payment or bank code, or a card detail.", "maxLength": 800, "minLength": 1, "type": "string", "x-envoy-secret": true }, "idempotency_key": { "description": "One key per answer. Retry with the same key and the same answer; a reused key with a different answer is refused.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "purchase": { "description": "Purchase ID or original idempotency key.", "maxLength": 64, "minLength": 16, "pattern": "^(?:pur_[a-f0-9]{32}|(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*)$", "type": "string" }, "question": { "description": "The id from purchase.question or purchase.follow_up. An earlier question cannot be answered.", "maxLength": 128, "minLength": 1, "type": "string" }, "rating": { "description": "Rating from 1 to 5. Feedback only.", "maximum": 5, "minimum": 1, "type": "integer" }, "type": { "description": "What you are sending. details: a missing detail Envoy asked for. answer: the user's reply to purchase.question. feedback: the user's view, after purchase.follow_up or at any time. Envoy matches it to the open question.", "enum": [ "details", "answer", "feedback" ], "type": "string" } }, "required": [ "type", "answer", "idempotency_key" ], "type": "object" }, "answer_purchase_questionOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "properties": { "receipt": { "additionalProperties": false, "description": "Feedback receipt: present when answer_purchase_question recorded feedback.", "properties": { "feedback_id": { "description": "Feedback identifier.", "type": "string" }, "recorded_at": { "description": "Recorded time.", "format": "date-time", "type": "string" } }, "required": [ "feedback_id", "recorded_at" ], "type": "object" } }, "required": [ "receipt" ], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "answer_purchase_question" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "cancel_purchaseInput": { "additionalProperties": false, "properties": { "purchase": { "description": "Purchase ID or original idempotency key.", "maxLength": 64, "minLength": 16, "pattern": "^(?:pur_[a-f0-9]{32}|(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*)$", "type": "string" }, "reason": { "description": "Cancellation reason.", "type": "string" } }, "required": [ "purchase" ], "type": "object" }, "cancel_purchaseOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "description": "No payload declared for this tool.", "properties": {}, "required": [], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "cancel_purchase" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "get_accountInput": { "additionalProperties": false, "properties": { "include": { "default": [ "balance", "services", "active_purchase", "held_purchases" ], "description": "Sections to read. A single string is also accepted.", "items": { "description": "Selected account section.", "enum": [ "balance", "limits", "services", "active_purchase", "agent", "profile", "addresses", "held_purchases" ], "type": "string" }, "type": "array", "uniqueItems": true } }, "required": [], "type": "object" }, "get_accountOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "properties": { "account": { "additionalProperties": false, "description": "Selected account sections. Balance and limit fields reuse the verified v1 read adapter; services lists registry identifiers. Absent sections were not requested.", "properties": { "active_purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "addresses": { "description": "Saved delivery addresses from the Envoy app, default first. Complete list: a partial list is reported unavailable.", "items": { "additionalProperties": false, "properties": { "city": { "description": "City.", "type": "string" }, "country": { "description": "Country.", "type": [ "string", "null" ] }, "id": { "description": "Pass as address_id to start_purchase.", "type": "string" }, "is_default": { "description": "The user's default address.", "type": "boolean" }, "label": { "description": "User label, e.g. Home. Empty when the user set none.", "type": "string" }, "line": { "description": "Address on one line, for a single-field form.", "type": "string" }, "line1": { "description": "First address line.", "type": "string" }, "line2": { "description": "Second address line.", "type": [ "string", "null" ] }, "line3": { "description": "Third address line.", "type": [ "string", "null" ] }, "name": { "description": "Recipient name.", "type": [ "string", "null" ] }, "phone": { "description": "Recipient phone, as the user saved it.", "type": [ "string", "null" ] }, "pin_code": { "description": "PIN code.", "type": "string" }, "state": { "description": "State.", "type": "string" } }, "required": [ "id", "label", "is_default", "name", "phone", "line1", "line2", "line3", "city", "state", "pin_code", "country", "line" ], "type": "object" }, "type": "array", "x-envoy-secret": true }, "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "balance": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "currency": { "description": "Account currency.", "type": [ "string", "null" ] }, "held": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "held_purchases": { "additionalProperties": false, "description": "Open agent purchase card money, separate from the account held figure.", "properties": { "available": { "description": "Whether Core supplied the open purchase money read.", "type": "boolean" }, "items": { "items": { "additionalProperties": false, "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "exact": { "description": "True when Core knows the exact held amount.", "type": "boolean" }, "merchant": { "description": "Merchant name.", "type": [ "string", "null" ] }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "since": { "description": "When this open money position began; null when Core omitted or returned an invalid timestamp.", "format": "date-time", "type": [ "string", "null" ] }, "state": { "description": "unknown means Core returned a state Envoy cannot interpret; its amount is withheld.", "enum": [ "held", "returning", "unknown" ], "type": "string" } }, "required": [ "purchase_id", "merchant", "amount", "exact", "state", "since" ], "type": "object" }, "type": "array" }, "reason": { "description": "Read unavailable, including when the connected Core does not support this operation.", "enum": [ "upstream_unavailable", null ], "type": [ "string", "null" ] }, "total": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "truncated": { "description": "True when the list is incomplete because rows were omitted or skipped.", "type": [ "boolean", "null" ] } }, "required": [ "available", "reason", "items", "total", "truncated" ], "type": [ "object", "null" ] }, "limits": { "items": { "additionalProperties": false, "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "channel": { "description": "Channel.", "type": "string" }, "period": { "description": "Limit period.", "enum": [ "day", "transaction" ], "type": "string" } }, "required": [ "channel", "period", "amount" ], "type": "object" }, "type": "array" }, "limits_reserved": { "description": "Limits are informational, not reserved or a promise of payment approval.", "enum": [ "not_reserved" ], "type": "string" }, "profile": { "additionalProperties": false, "description": "Contact details for delivery and checkout forms. A null value has no source.", "properties": { "email": { "description": "Email address on the Envoy account. Not verified.", "type": [ "string", "null" ] }, "mobile": { "description": "Verified mobile number in E.164 form.", "type": [ "string", "null" ] }, "name": { "description": "Full name on the Envoy account.", "type": [ "string", "null" ] } }, "required": [ "name", "mobile", "email" ], "type": "object", "x-envoy-secret": true }, "services": { "items": { "description": "Enabled service identifier from the registry.", "enum": [ "purchase" ], "type": "string" }, "type": "array", "uniqueItems": true }, "spendable": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "unavailable": { "items": { "description": "Requested value has no verified source; its section is omitted, never shown empty. An unavailable active_purchase does not mean no purchase is in progress.", "enum": [ "balance", "holds", "spendable", "currency", "limits", "profile", "addresses", "active_purchase" ], "type": "string" }, "type": "array" } }, "required": [], "type": "object" } }, "required": [ "account" ], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "get_account" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "get_merchantsInput": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "get_merchantsOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "properties": { "merchants": { "description": "Merchants the user can buy a gift card for right now. Empty when gift cards are not available.", "items": { "additionalProperties": false, "properties": { "amount_range": { "additionalProperties": false, "description": "Any whole rupee from min to max; null: listed amounts only.", "properties": { "max": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "min": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "min", "max" ], "type": [ "object", "null" ] }, "amounts": { "description": "Gift card face values sold. Empty when amount_range is set.", "items": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "maxItems": 1000, "type": "array" }, "discount_percent": { "description": "Indicative product discount maximum, 0 to 100, may be fractional (2.5); null means none reported. Say \"up to\". The actual purchase quote is authoritative; until available, payable is unknown. Do not infer price from payment method or card ownership.", "maximum": 100, "minimum": 0, "type": [ "number", "null" ] }, "domain": { "description": "Merchant website domain.", "maxLength": 253, "minLength": 1, "type": "string" }, "name": { "description": "Merchant name, taken from its domain.", "maxLength": 253, "minLength": 1, "type": "string" }, "redeem_at": { "description": "Where the gift card is used. account: add it to the user's account balance on the merchant site, then check out normally. checkout: enter it at the merchant's payment step. Null: not known yet.", "enum": [ "account", "checkout", null ], "type": [ "string", "null" ] } }, "required": [ "name", "domain", "amounts", "amount_range", "discount_percent", "redeem_at" ], "type": "object" }, "maxItems": 1000, "type": "array" } }, "required": [ "merchants" ], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "get_merchants" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "get_purchase_statusInput": { "additionalProperties": false, "properties": { "after_revision": { "description": "Return early when the revision changes.", "minimum": 0, "type": "integer" }, "purchase": { "description": "Purchase ID or original idempotency key.", "maxLength": 64, "minLength": 16, "pattern": "^(?:pur_[a-f0-9]{32}|(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*)$", "type": "string" }, "wait_seconds": { "default": 45, "description": "Hold at most 45 seconds; without after_revision return at once.", "maximum": 45, "minimum": 0, "type": "integer" } }, "required": [], "type": "object" }, "get_purchase_statusOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "properties": { "payment_details": { "additionalProperties": false, "description": "Secret. Release only while ready after authorization (a gift card: after its link was paid); never log or persist these values. card is present exactly when kind is card, voucher exactly when kind is gift_card.", "properties": { "amount_limit": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "card": { "additionalProperties": false, "properties": { "cvv": { "description": "Card verification value.", "type": "string" }, "expiry_month": { "description": "Expiry month.", "type": "string" }, "expiry_year": { "description": "Expiry year.", "type": "string" }, "network": { "description": "RuPay only.", "enum": [ "rupay" ], "type": "string" }, "number": { "description": "Synthetic examples only.", "type": "string" } }, "required": [ "number", "expiry_month", "expiry_year", "cvv", "network" ], "type": "object" }, "checkout_attempt_id": { "description": "The checkout attempt carried by this handout. Include this exact value in report_checkout_result; never substitute an attempt from a later read.", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" }, "checkout_code": { "description": "Optional checkout code, this card's bank OTP: when the bank page asks for a code or OTP, enter the checkout code there once, immediately. Repeated reads do not fund another card. When checkout_code_expires_at is present, read status again once the code expires.", "type": "string" }, "checkout_code_expires_at": { "description": "When this checkout code expires. Present only with a code whose validity is known. It is not when spending access closes, and not the expiry printed on the card.", "format": "date-time", "type": "string" }, "expires_at": { "description": "When spending access closes. Omitted when unknown; it is not the checkout code expiry or the expiry printed on the card.", "format": "date-time", "type": "string" }, "kind": { "description": "card: the authorized one-time RuPay card, in card. gift_card: the paid gift card, in voucher.", "enum": [ "card", "gift_card" ], "type": "string" }, "voucher": { "additionalProperties": false, "description": "Present exactly when kind is gift_card. value equals purchase.amount.", "properties": { "brand": { "description": "Gift card brand.", "type": "string" }, "code": { "description": "Gift card code. Redeem it at the merchant checkout.", "type": "string" }, "pin": { "description": "Gift card PIN, when the brand has one.", "type": "string" }, "redemption_instructions": { "description": "How to redeem it, from the brand.", "type": "string" }, "redemption_url": { "description": "Where the merchant redeems it, when given.", "format": "uri", "pattern": "^https://", "type": "string" }, "valid_until": { "description": "When the code stops working. Null means no known expiry.", "format": "date-time", "type": [ "string", "null" ] }, "value": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "brand", "code", "value", "redemption_instructions", "valid_until" ], "type": "object" } }, "required": [ "kind", "amount_limit" ], "type": "object", "x-envoy-secret": true } }, "required": [ "payment_details" ], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "get_purchase_status" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "give_back_gift_cardInput": { "additionalProperties": false, "properties": { "idempotency_key": { "description": "Retry with the same key.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "max_total": { "description": "Highest order total the user accepts. Rupees, up to 2 decimals; number also accepted, \"₹\" and thousands commas are stripped.", "maxLength": 20, "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "product": { "additionalProperties": false, "description": "What Envoy buys.", "properties": { "name": { "description": "Product name.", "maxLength": 200, "minLength": 1, "type": "string" }, "quantity": { "description": "How many.", "maximum": 10, "minimum": 1, "type": "integer" }, "variant": { "description": "Option, e.g. size.", "maxLength": 60, "minLength": 1, "type": "string" } }, "required": [ "name", "quantity" ], "type": "object" }, "purchase": { "description": "Purchase ID or original idempotency key.", "maxLength": 64, "minLength": 16, "pattern": "^(?:pur_[a-f0-9]{32}|(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*)$", "type": "string" } }, "required": [ "purchase", "product", "max_total", "idempotency_key" ], "type": "object" }, "give_back_gift_cardOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "description": "No payload declared for this tool.", "properties": {}, "required": [], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "give_back_gift_card" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "list_gift_card_merchantsInput": { "additionalProperties": false, "properties": {}, "required": [], "type": "object" }, "list_gift_card_merchantsOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "properties": { "merchants": { "description": "Merchants the user can buy a gift card for right now. Empty when gift cards are not available.", "items": { "additionalProperties": false, "properties": { "amount_range": { "additionalProperties": false, "description": "Any whole rupee from min to max; null: listed amounts only.", "properties": { "max": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "min": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "min", "max" ], "type": [ "object", "null" ] }, "amounts": { "description": "Gift card face values sold. Empty when amount_range is set.", "items": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "maxItems": 1000, "type": "array" }, "discount_percent": { "description": "Indicative product discount maximum, 0 to 100, may be fractional (2.5); null means none reported. Say \"up to\". The actual purchase quote is authoritative; until available, payable is unknown. Do not infer price from payment method or card ownership.", "maximum": 100, "minimum": 0, "type": [ "number", "null" ] }, "domain": { "description": "Merchant website domain.", "maxLength": 253, "minLength": 1, "type": "string" }, "name": { "description": "Merchant name, taken from its domain.", "maxLength": 253, "minLength": 1, "type": "string" }, "redeem_at": { "description": "Where the gift card is used. account: add it to the user's account balance on the merchant site, then check out normally. checkout: enter it at the merchant's payment step. Null: not known yet.", "enum": [ "account", "checkout", null ], "type": [ "string", "null" ] } }, "required": [ "name", "domain", "amounts", "amount_range", "discount_percent", "redeem_at" ], "type": "object" }, "maxItems": 1000, "type": "array" } }, "required": [ "merchants" ], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "list_gift_card_merchants" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "list_purchasesInput": { "additionalProperties": false, "properties": { "limit": { "default": 10, "description": "How many, newest first.", "maximum": 20, "minimum": 1, "type": "integer" } }, "required": [], "type": "object" }, "list_purchasesOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "properties": { "purchases": { "items": { "additionalProperties": false, "description": "One purchase as Envoy last stored it. state may be behind Core: call get_purchase for the current state.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" } }, "required": [ "purchase_id", "state", "merchant", "amount", "checkout_by", "created_at" ], "type": "object" }, "maxItems": 20, "type": "array" }, "truncated": { "description": "True when the user has more purchases than were returned.", "type": "boolean" } }, "required": [ "purchases", "truncated" ], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "list_purchases" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "list_transactionsInput": { "additionalProperties": false, "properties": { "cursor": { "description": "Opaque pagination cursor bound to this connection, date range and page size.", "maxLength": 2048, "minLength": 1, "type": "string" }, "from": { "description": "Start date.", "format": "date", "type": "string" }, "limit": { "description": "Maximum transactions.", "maximum": 50, "minimum": 1, "type": "integer" }, "to": { "description": "End date.", "format": "date", "type": "string" } }, "required": [], "type": "object" }, "list_transactionsOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "properties": { "next_cursor": { "description": "Opaque next cursor.", "type": [ "string", "null" ] }, "transactions": { "items": { "additionalProperties": false, "description": "One line of the user's Envoy transaction history, exactly as the app shows it. Describe it the way the app does.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "by_agent": { "description": "True when an agent made this purchase through Envoy.", "type": "boolean" }, "card": { "description": "Which card it was on. elixir_card: the user's Elixir card, badged \"Elixir card\" in the app.", "enum": [ "envoy", "elixir_card", "unknown" ], "type": "string" }, "direction": { "description": "debit: money left the account. credit: money came back or was added. none: no money moved, e.g. a declined payment.", "enum": [ "debit", "credit", "none" ], "type": "string" }, "id": { "description": "Opaque statement line identifier, stable for this connection and client. It contains no card binding and grants no access.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "What happened. other: a kind this version does not name.", "enum": [ "purchase", "reversal", "refund", "load", "withdraw", "fee", "decline", "card_issued", "card_funded", "card_closed", "adjustment", "other" ], "type": "string" }, "occurred_at": { "description": "When it happened.", "format": "date-time", "type": "string" }, "status": { "description": "completed: done. pending: still in progress (the app shows \"In progress\"). failed: did not complete (the app shows \"Didn't complete\").", "enum": [ "completed", "pending", "failed", "unknown" ], "type": "string" }, "subtitle": { "description": "The line's second row in the app. For an agent purchase, the agent's name.", "maxLength": 200, "type": [ "string", "null" ] }, "title": { "description": "What the user sees as the line's name: the merchant for a purchase.", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "id", "occurred_at", "amount", "direction", "title", "subtitle", "by_agent", "kind", "status", "card" ], "type": "object" }, "type": "array" } }, "required": [ "transactions", "next_cursor" ], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "list_transactions" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "report_checkout_resultInput": { "additionalProperties": false, "properties": { "amount_paid": { "description": "Amount the merchant charged. Rupees, up to 2 decimals; number also accepted, \"₹\" and thousands commas are stripped.", "maxLength": 20, "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "checkout_attempt_id": { "description": "Copy the checkout_attempt_id from the card handout used for this payment. Omit only for a legacy handout; never guess or replace it with a newer attempt.", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" }, "failure_reason": { "description": "Required when outcome is failed. card_not_accepted: the merchant would not take this card. card_declined: the card payment was declined. otp_failed: the bank code check failed. price_changed: the total changed at checkout. out_of_stock: an item was unavailable. site_error: the site failed during checkout. site_blocked: the site blocked the checkout or your browser. other: any other failure.", "enum": [ "card_not_accepted", "card_declined", "otp_failed", "price_changed", "out_of_stock", "site_error", "site_blocked", "other" ], "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference, as the merchant showed it (at most 128 characters, no control characters).", "maxLength": 128, "minLength": 1, "pattern": "^[^\\x00-\\x1F\\x7F-\\x9F]+$", "type": "string" }, "outcome": { "description": "Agent observation, not settlement evidence: report paid only when the merchant confirmed payment. If you cannot tell whether payment completed, report failed with failure_reason other.", "enum": [ "paid", "failed" ], "type": "string" }, "purchase": { "description": "Purchase ID or original idempotency key.", "maxLength": 64, "minLength": 16, "pattern": "^(?:pur_[a-f0-9]{32}|(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*)$", "type": "string" } }, "required": [ "purchase", "outcome" ], "type": "object" }, "report_checkout_resultOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "description": "No payload declared for this tool.", "properties": {}, "required": [], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "report_checkout_result" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "report_checkout_stepInput": { "additionalProperties": false, "properties": { "checkout_attempt_id": { "description": "From the handout, if any.", "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$", "type": "string" }, "purchase": { "description": "Purchase ID or original idempotency key.", "maxLength": 64, "minLength": 16, "pattern": "^(?:pur_[a-f0-9]{32}|(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*)$", "type": "string" }, "step": { "description": "Step reached.", "enum": [ "merchant_opened", "cart_built", "payment_page_reached", "payment_applied", "otp_requested", "otp_submitted", "order_submitted", "blocked" ], "type": "string" } }, "required": [ "purchase", "step" ], "type": "object" }, "report_checkout_stepOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "description": "No payload declared for this tool.", "properties": {}, "required": [], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "report_checkout_step" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "search_productsInput": { "additionalProperties": false, "properties": { "address_id": { "description": "Saved address ID from get_account to deliver to; default: the default saved address.", "maxLength": 64, "minLength": 1, "type": "string" }, "quantity": { "default": 1, "description": "How many; default 1.", "maximum": 99, "minimum": 1, "type": "integer" }, "query": { "description": "What the user wants, in their words.", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "query" ], "type": "object" }, "search_productsOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "properties": { "products": { "description": "Products from Elixir's own marketplace, price for one and total for the quantity. Empty when Elixir has nothing to offer right now.", "items": { "additionalProperties": false, "properties": { "brand": { "description": "Brand, when Elixir lists one.", "maxLength": 500, "minLength": 1, "type": [ "string", "null" ] }, "image": { "description": "Product image.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "merchant_url": { "description": "Elixir's store. Pass it to start_purchase as merchant_url.", "format": "uri", "pattern": "^https://", "type": "string" }, "name": { "description": "Product name, as Elixir lists it.", "maxLength": 200, "minLength": 1, "type": "string" }, "price": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "product_id": { "description": "This product's offer id. Never show it to the user.", "pattern": "^ofr_[a-f0-9]{32}$", "type": "string" }, "quantity": { "description": "Quantity priced.", "maximum": 999, "minimum": 1, "type": "integer" }, "total": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "valid_until": { "description": "The price holds until this time; search again after it.", "format": "date-time", "type": "string" } }, "required": [ "product_id", "name", "brand", "image", "price", "quantity", "total", "valid_until", "merchant_url" ], "type": "object" }, "maxItems": 5, "type": "array" } }, "required": [ "products" ], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "search_products" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "start_purchaseInput": { "additionalProperties": false, "properties": { "address": { "description": "Delivery address on one line, with recipient name, phone and 6-digit PIN code. Prefer address_id from get_account. Do not also send address_id.", "maxLength": 500, "minLength": 1, "type": "string" }, "address_id": { "description": "Saved address ID from get_account with include addresses. Preferred over address. Do not also send address.", "maxLength": 64, "minLength": 1, "type": "string" }, "facts": { "description": "Order facts.", "items": { "additionalProperties": false, "properties": { "code": { "description": "deliver_to|arrives|sold_by|restaurant|check_in|check_out|cancellation|booked_for", "type": "string" }, "value": { "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "items": { "description": "What to buy, one entry per product. Only items being bought: no free gifts or ₹0 lines.", "items": { "additionalProperties": false, "properties": { "image": { "description": "Direct URL of the product image shown on the cart or product page. Used only to show the user what they are approving. Starts with https://; a bare domain or http:// is upgraded to https://.", "pattern": "^(?:[Hh][Tt][Tt][Pp][Ss]?://)?[^\\s/?#:@]+\\.[^\\s/?#:@]+(?:[/?#]\\S*)?$", "type": "string" }, "name": { "description": "Item name, including size, colour or variant.", "maxLength": 200, "minLength": 1, "type": "string" }, "price": { "description": "Line price in rupees, quantity included.", "type": "string" }, "product_id": { "description": "A search_products product's product_id, on every item or none.", "pattern": "^ofr_[a-f0-9]{32}$", "type": "string" }, "quantity": { "default": 1, "description": "Quantity; default 1. Numeric string also accepted.", "maximum": 99, "minimum": 1, "type": "integer" }, "url": { "description": "Item page URL. Starts with https://; a bare domain or http:// is upgraded to https://.", "pattern": "^(?:[Hh][Tt][Tt][Pp][Ss]?://)?[^\\s/?#:@]+\\.[^\\s/?#:@]+(?:[/?#]\\S*)?$", "type": "string" } }, "required": [ "name" ], "type": "object" }, "maxItems": 20, "minItems": 1, "type": "array" }, "max_total": { "description": "Highest total the user accepts; defaults to total. The card's hard limit: set it above total if fees may still be added. Rupees, up to 2 decimals; number also accepted, \"₹\" and thousands commas are stripped.", "maxLength": 20, "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "merchant_logo": { "description": "Merchant logo or brand image URL, as shown on the page. Starts with https://; a bare domain or http:// is upgraded to https://.", "pattern": "^(?:[Hh][Tt][Tt][Pp][Ss]?://)?[^\\s/?#:@]+\\.[^\\s/?#:@]+(?:[/?#]\\S*)?$", "type": "string" }, "merchant_url": { "description": "Merchant checkout or product URL; the merchant name is taken from its domain. Starts with https://; a bare domain or http:// is upgraded to https://.", "pattern": "^(?:[Hh][Tt][Tt][Pp][Ss]?://)?[^\\s/?#:@]+\\.[^\\s/?#:@]+(?:[/?#]\\S*)?$", "type": "string" }, "order_title": { "description": "Display only, as shown, like price_lines and facts; Envoy drops what it cannot show. Order title.", "type": "string" }, "price_lines": { "description": "Bill lines adding up to total.", "items": { "additionalProperties": false, "properties": { "amount": { "description": "Rupees, positive.", "type": "string" }, "code": { "description": "item_total|delivery|taxes_fees|packaging|discount", "type": "string" } }, "required": [], "type": "object" }, "type": "array" }, "product_id": { "description": "For a product from search_products, pass its product_id, merchant_url and total exactly; Envoy buys it from Elixir and the user approves in the app.", "pattern": "^ofr_[a-f0-9]{32}$", "type": "string" }, "rail": { "description": "gift_card: buy a gift card of a merchant list_gift_card_merchants lists, for this total. operated_checkout: Envoy places the order itself or refuses; no card is released. Omit for a one-time card. Not with retry_of or product_id.", "enum": [ "gift_card", "operated_checkout" ], "type": "string" }, "retry_of": { "description": "Retry a card purchase you reported failed on Envoy's browser checkout: its purchase ID or original idempotency key. Same merchant site, items and total. Envoy finishes it with that card if it can still use it, otherwise as a new purchase on the user's own card. Envoy may also accept a purchase that failed because its card could not be issued.", "maxLength": 64, "minLength": 16, "pattern": "^(?:pur_[a-f0-9]{32}|(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*)$", "type": "string" }, "total": { "description": "Checkout total in INR, with delivery, tax and fees. Rupees, up to 2 decimals; number also accepted, \"₹\" and thousands commas are stripped.", "maxLength": 20, "pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$", "type": "string" }, "user_request": { "description": "The user's own words for this purchase, including any notes.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "idempotency_key", "merchant_url", "total", "items", "user_request" ], "type": "object" }, "start_purchaseOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "description": "No payload declared for this tool.", "properties": {}, "required": [], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "start_purchase" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" }, "submit_answerInput": { "additionalProperties": false, "properties": { "answer": { "description": "What the user said, in their words: the reply to purchase.question, or feedback after purchase.follow_up. An otp question asks for the code the merchant sent the user to sign in: send it once, then never repeat or keep it. Never your own answer, and never a password, a payment or bank code, or a card detail.", "maxLength": 800, "minLength": 1, "type": "string", "x-envoy-secret": true }, "idempotency_key": { "description": "One key per answer. Retry with the same key and the same answer; a reused key with a different answer is refused.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "purchase": { "description": "Purchase ID or original idempotency key.", "maxLength": 64, "minLength": 16, "pattern": "^(?:pur_[a-f0-9]{32}|(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*)$", "type": "string" }, "question": { "description": "The id from purchase.question or purchase.follow_up. An earlier question cannot be answered.", "maxLength": 128, "minLength": 1, "type": "string" }, "rating": { "description": "Rating from 1 to 5. Feedback only.", "maximum": 5, "minimum": 1, "type": "integer" }, "type": { "description": "What you are sending. details: a missing detail Envoy asked for. answer: the user's reply to purchase.question. feedback: the user's view, after purchase.follow_up or at any time. Envoy matches it to the open question.", "enum": [ "details", "answer", "feedback" ], "type": "string" } }, "required": [ "type", "answer", "idempotency_key" ], "type": "object" }, "submit_answerOutput": { "additionalProperties": false, "description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority.", "properties": { "contract": { "description": "Fixed revision for debugging and support; agents never branch on it.", "enum": [ "envoy@2026-10" ], "type": "string" }, "data": { "additionalProperties": false, "properties": { "receipt": { "additionalProperties": false, "description": "Feedback receipt: present when answer_purchase_question recorded feedback.", "properties": { "feedback_id": { "description": "Feedback identifier.", "type": "string" }, "recorded_at": { "description": "Recorded time.", "format": "date-time", "type": "string" } }, "required": [ "feedback_id", "recorded_at" ], "type": "object" } }, "required": [ "receipt" ], "type": [ "object", "null" ] }, "error": { "additionalProperties": false, "properties": { "code": { "description": "Contract error code.", "enum": [ "INVALID_INPUT", "UNAUTHENTICATED", "NOT_ALLOWED", "SERVICE_NOT_ENABLED", "NOT_FOUND", "IDEMPOTENCY_CONFLICT", "ACTIVE_PURCHASE_EXISTS", "STATE_CONFLICT", "NO_RAIL", "RATE_LIMITED", "UNAVAILABLE", "CLIENT_UPDATE_REQUIRED" ], "type": "string" }, "fields": { "items": { "additionalProperties": false, "properties": { "expected": { "description": "What the value should be.", "maxLength": 200, "type": [ "string", "null" ] }, "path": { "description": "JSON pointer of the rejected field.", "maxLength": 128, "type": "string" }, "problem": { "description": "What is wrong.", "maxLength": 200, "type": "string" } }, "required": [ "path", "problem", "expected" ], "type": "object" }, "maxItems": 10, "type": "array" }, "message": { "description": "Safe to show the user.", "type": "string" }, "reason_code": { "description": "Reason code. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED, RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "retry_after_seconds": { "description": "Retry delay in seconds.", "minimum": 0, "type": [ "integer", "null" ] }, "retryable": { "description": "Whether a retry is allowed.", "type": "boolean" } }, "required": [ "code", "message", "fields", "reason_code", "retryable", "retry_after_seconds" ], "type": [ "object", "null" ] }, "follow_ups": { "items": { "additionalProperties": false, "properties": { "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": "object" }, "tool": { "description": "Optional follow-up tool.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products" ], "type": "string" }, "why": { "description": "Reason for follow-up.", "type": "string" } }, "required": [ "tool", "args", "why" ], "type": "object" }, "type": "array" }, "next": { "additionalProperties": false, "properties": { "action": { "description": "What the agent does next.", "enum": [ "call_tool", "checkout", "fix_input", "retry", "continue", "done", "stop", "reconnect", "update_client" ], "type": "string" }, "after_seconds": { "description": "Seconds to wait before the next call.", "minimum": 0, "type": [ "integer", "null" ] }, "args": { "additionalProperties": true, "description": "Pass verbatim as the arguments of next.tool.", "type": [ "object", "null" ] }, "by": { "description": "Stop waiting and tell the user after this time.", "format": "date-time", "type": [ "string", "null" ] }, "instruction": { "description": "Instruction for the agent. Do not show it to the user.", "maxLength": 600, "minLength": 1, "type": "string" }, "tool": { "description": "Tool to call next.", "enum": [ "get_account", "list_transactions", "list_purchases", "start_purchase", "get_purchase_status", "answer_purchase_question", "submit_answer", "report_checkout_result", "report_checkout_step", "cancel_purchase", "give_back_gift_card", "list_gift_card_merchants", "get_merchants", "search_products", null ], "type": [ "string", "null" ] } }, "required": [ "action", "tool", "args", "instruction", "after_seconds", "by" ], "type": "object" }, "ok": { "description": "False means this call changed nothing.", "type": "boolean" }, "origin": { "description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.", "enum": [ "client" ], "type": "string" }, "purchase": { "additionalProperties": false, "description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence.", "properties": { "agent": { "additionalProperties": false, "properties": { "agent_id": { "description": "Stable host identity.", "type": "string" }, "display_name": { "description": "Display name.", "type": "string" }, "verification": { "description": "Host verification level.", "enum": [ "cimd", "origin", "unverified" ], "type": "string" } }, "required": [ "agent_id", "display_name", "verification" ], "type": "object" }, "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "approval": { "additionalProperties": false, "properties": { "approval_url": { "description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] }, "decide_by": { "description": "Approval deadline.", "format": "date-time", "type": [ "string", "null" ] }, "method": { "description": "Consent method.", "enum": [ "passkey", "otp", null ], "type": [ "string", "null" ] }, "state": { "description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.", "enum": [ "pending", "approved", "denied", "expired", null ], "type": [ "string", "null" ] } }, "required": [ "state", "method", "decide_by", "approval_url" ], "type": "object" }, "chain": { "additionalProperties": false, "properties": { "superseded_by": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] }, "supersedes": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": [ "string", "null" ] } }, "required": [ "supersedes", "superseded_by" ], "type": "object" }, "checkout_by": { "description": "Who completes the merchant checkout. agent: you pay with the released card. envoy: Envoy pays; never open the merchant checkout yourself. Null until a rail is selected.", "enum": [ "agent", "envoy", null ], "type": [ "string", "null" ] }, "created_at": { "description": "Creation time.", "format": "date-time", "type": "string" }, "description": { "description": "Purchase description.", "type": [ "string", "null" ] }, "details": { "additionalProperties": false, "properties": { "complete": { "description": "Required details are present.", "type": "boolean" }, "missing": { "items": { "description": "Missing field name.", "type": "string" }, "type": "array" } }, "required": [ "complete", "missing" ], "type": "object" }, "follow_up": { "additionalProperties": false, "description": "Optional feedback request. Present only on a completed purchase; never blocks anything.", "properties": { "id": { "description": "Pass as question to answer_purchase_question with type feedback.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.", "enum": [ "feedback" ], "type": "string" }, "prompt": { "description": "Envoy's request in its own words. Ask the user only if it fits the conversation.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt" ], "type": [ "object", "null" ] }, "funding": { "additionalProperties": false, "description": "Present only while user_task is pay_link. amount is what the user pays (the gift card's discounted price); purchase.amount is the gift card's value.", "properties": { "amount": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" }, "expires_at": { "description": "When the link stops accepting payment; also approval.decide_by.", "format": "date-time", "type": "string" }, "url": { "description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "url", "amount", "expires_at" ], "type": "object" }, "idempotency_key": { "description": "One key per intent; retry with the same key. A new key is a new purchase.", "maxLength": 64, "minLength": 16, "pattern": "^(?:[A-Za-oq-z0-9_-]|p[A-Za-tv-z0-9_-]|pu[A-Za-qs-z0-9_-]|pur[A-Za-z0-9-])[A-Za-z0-9_-]*$", "type": "string" }, "merchant": { "additionalProperties": false, "properties": { "name": { "description": "Merchant name.", "type": "string" }, "url": { "description": "Merchant URL.", "format": "uri", "pattern": "^https://", "type": "string" } }, "required": [ "name", "url" ], "type": "object" }, "money": { "additionalProperties": false, "properties": { "merchant_order_ref": { "description": "Merchant order reference.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": [ "object", "null" ] }, "status": { "description": "Money state, independent of merchant order state. merchant_collects: the merchant collects payment on delivery and nothing was charged to the Elixir card; then paid is the order total the merchant collects.", "enum": [ "not_started", "unknown", "debited", "refund_pending", "refunded", "merchant_collects" ], "type": "string" } }, "required": [ "status", "paid", "merchant_order_ref" ], "type": "object" }, "payment_ready": { "additionalProperties": false, "properties": { "available": { "description": "The card or gift card is carried in get_purchase_status data.payment_details while ready.", "type": "boolean" }, "closed": { "description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund.", "type": "boolean" }, "expires_at": { "description": "When spending access closes. Null means no known deadline, never expired.", "format": "date-time", "type": [ "string", "null" ] }, "kind": { "description": "Payment detail kind: card on otu_card, gift_card on gift_card.", "enum": [ "card", "gift_card", null ], "type": [ "string", "null" ] } }, "required": [ "available", "kind", "expires_at" ], "type": "object" }, "purchase_id": { "description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.", "pattern": "^pur_[a-f0-9]{32}$", "type": "string" }, "question": { "additionalProperties": false, "description": "The open question. Null in every state but needs_details and needs_answer.", "properties": { "asked_at": { "description": "When Envoy asked it.", "format": "date-time", "type": "string" }, "id": { "description": "Pass as question to answer_purchase_question. A later question has a different id.", "maxLength": 128, "minLength": 1, "type": "string" }, "kind": { "description": "address: the delivery address. user_request: what to buy, in the user's words. text: a decision only the user can make. otp: the code THIS MERCHANT just sent the user to sign in; the user types it, you send it once, then never repeat or keep it. password: reserved; Envoy never asks for a password through chat. A payment or bank code never appears here; the user enters it in the Envoy app.", "enum": [ "address", "user_request", "text", "password", "otp" ], "type": "string" }, "prompt": { "description": "Envoy's question in its own words. Show it to the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" } }, "required": [ "id", "kind", "prompt", "asked_at" ], "type": [ "object", "null" ] }, "rail": { "description": "Rail selected by Envoy. elixir_marketplace is sent only where Elixir inventory suggestions are enabled, and only once the user chose Elixir's offer. gift_card: the account has no Envoy card, so the user pays a link and you redeem a gift card worth purchase.amount.", "enum": [ "otu_card", "operated_checkout", "elixir_marketplace", "gift_card", null ], "type": [ "string", "null" ] }, "rail_reason": { "description": "Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE.", "enum": [ "RAIL_OTU_PREFERRED", "RAIL_AMOUNT_ABOVE_OTU_LIMIT", "RAIL_MERCHANT_REJECTS_RUPAY", "RAIL_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_CARD_NOT_ACCEPTED", "RAIL_FALLBACK_ISSUER_UNAVAILABLE", "RAIL_FALLBACK_SITE_BLOCKED", "RAIL_OPERATED_UNAVAILABLE", "RAIL_OPERATED_CART_UNSUPPORTED", "RAIL_AMOUNT_OUTSIDE_CARD_LIMITS", "RAIL_CARD_UNAVAILABLE", "RAIL_INSUFFICIENT_BALANCE", "RAIL_HOST_OPERATED_ONLY", "RAIL_ELIXIR_INVENTORY", "RAIL_MERCHANT_GATEWAY", "RAIL_GIFT_CARD_CARDLESS", "RAIL_CARD_REQUIRED", null ], "type": [ "string", "null" ] }, "reason_code": { "description": "Why the purchase is in this state. On verifying after report_checkout_result: null after paid, the failure's code after failed. Reserved, not sent today: POLICY_ADMISSION_UNAVAILABLE, POLICY_FRAUD_DECLINED, POLICY_AGENT_LIMIT, USER_OTP_EXPIRED, ORDER_CONNECTION_REVOKED.", "enum": [ "POLICY_DENIED", "POLICY_AMOUNT_LIMIT", "POLICY_ADMISSION_UNAVAILABLE", "USER_DECLINED", "USER_APPROVAL_EXPIRED", "USER_OTP_EXPIRED", "USER_CANCELLED", "USER_FUNDS_NOT_ADDED", "ORDER_CANCELLED_BY_AGENT", "ORDER_CARD_NOT_ACCEPTED", "ORDER_CARD_DECLINED", "ORDER_OTP_FAILED", "ORDER_PRICE_CHANGED", "ORDER_OUT_OF_STOCK", "ORDER_CHECKOUT_FAILED", "ORDER_CHECKOUT_BLOCKED", "ORDER_CARD_EXPIRED_UNUSED", "ORDER_ISSUER_UNAVAILABLE", "ORDER_CARD_REQUIRED", "ORDER_INTEGRATION_ERROR", "ORDER_OUTCOME_UNKNOWN", "ORDER_CONNECTION_REVOKED", "POLICY_FRAUD_DECLINED", "POLICY_AGENT_LIMIT", "POLICY_ACTIVE_PURCHASE_EXISTS", null ], "type": [ "string", "null" ] }, "receipt": { "additionalProperties": false, "description": "Receipt. Null unless the purchase is completed. Carries no links.", "properties": { "card": { "additionalProperties": false, "description": "Card summary; null when no verified non-secret source exists.", "properties": { "last4": { "description": "Last four digits of the card number.", "pattern": "^[0-9]{4}$", "type": "string" }, "network": { "description": "Card network.", "enum": [ "rupay" ], "type": "string" } }, "required": [ "network", "last4" ], "type": [ "object", "null" ] }, "completed_at": { "description": "When Envoy recorded the completion.", "format": "date-time", "type": "string" }, "merchant_order_ref": { "description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given.", "type": [ "string", "null" ] }, "paid": { "additionalProperties": false, "properties": { "currency": { "description": "Indian rupees.", "enum": [ "INR" ], "type": "string" }, "display": { "description": "Human-readable amount, e.g. ₹1,299.00.", "type": "string" }, "minor": { "description": "Amount in paise.", "minimum": 0, "type": "integer" } }, "required": [ "minor", "currency", "display" ], "type": "object" } }, "required": [ "merchant_order_ref", "paid", "card", "completed_at" ], "type": [ "object", "null" ] }, "revision": { "description": "Purchase revision.", "minimum": 0, "type": "integer" }, "service": { "description": "Launch service.", "enum": [ "purchase" ], "type": "string" }, "state": { "description": "Purchase lifecycle state.", "enum": [ "needs_details", "needs_answer", "waiting_for_user", "processing", "ready", "verifying", "completed", "failed", "cancelled", "superseded" ], "type": "string" }, "status_text": { "description": "One plain sentence explaining this state. Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "terminal": { "description": "Whether the lifecycle state is terminal.", "type": "boolean" }, "updated_at": { "description": "Last change time.", "format": "date-time", "type": "string" }, "user_task": { "description": "User task. pay_link: the user pays the gift card's payment link (purchase.funding) themselves; every other task is in the Envoy app. approve on a gift card: the user pays for it in the Envoy app; there is no link.", "enum": [ "approve", "enter_otp", "add_money", "pay_link", null ], "type": [ "string", "null" ] } }, "required": [ "purchase_id", "service", "idempotency_key", "revision", "terminal", "state", "user_task", "reason_code", "status_text", "rail", "rail_reason", "checkout_by", "merchant", "amount", "description", "details", "question", "follow_up", "approval", "payment_ready", "money", "receipt", "chain", "agent", "created_at", "updated_at" ], "type": [ "object", "null" ] }, "replayed": { "description": "Existing purchase or operation replayed.", "type": "boolean" }, "request_id": { "description": "Request tracking ID.", "type": "string" }, "server_time": { "description": "Server time.", "format": "date-time", "type": "string" }, "tool": { "description": "Invoked tool.", "enum": [ "submit_answer" ], "type": "string" }, "trace_id": { "description": "Trace ID.", "type": "string" }, "user_action": { "additionalProperties": false, "properties": { "by": { "description": "Deadline for the user.", "format": "date-time", "type": [ "string", "null" ] }, "message": { "description": "Safe to show the user verbatim.", "maxLength": 300, "minLength": 1, "type": "string" }, "task": { "description": "What the user must do.", "enum": [ "approve", "enter_otp", "add_money", "resolve_active_purchase", "pay_link" ], "type": "string" }, "url": { "description": "Null except on pay_link, where it is the gift card's payment link (purchase.funding.url) for the user to open. Every other task happens in the Envoy app, which the message says.", "format": "uri", "pattern": "^https://", "type": [ "string", "null" ] } }, "required": [ "task", "url", "by", "message" ], "type": [ "object", "null" ] } }, "required": [ "ok", "contract", "tool", "request_id", "trace_id", "server_time", "replayed", "purchase", "data", "next", "user_action", "error" ], "type": "object" } }, "securitySchemes": { "centralBearer": { "description": "Central Auth bearer with agent scope.", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Envoy tools are served at /tools and /mcp. Envoy decides for each purchase whether the agent pays with a one-time card or Envoy checks out itself; purchase.checkout_by carries the decision.", "title": "Envoy tool API", "version": "envoy@2026-10" }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "openapi": "3.1.0", "paths": { "/disconnect": { "post": { "description": "Fences local access and attempts Central revocation. Retained expired credentials can retry with a fresh proof. Purchase cancellation is not implemented by this port.", "operationId": "disconnect", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "disconnected": { "const": true }, "local_access": { "const": "blocked" }, "remote_revocation": { "const": "confirmed" } }, "required": [ "disconnected", "local_access", "remote_revocation" ], "type": "object" } } }, "description": "Remote revocation confirmed." }, "202": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "disconnected": { "const": false }, "local_access": { "const": "blocked" }, "remote_revocation": { "const": "pending" } }, "required": [ "disconnected", "local_access", "remote_revocation" ], "type": "object" } } }, "description": "Local access blocked; remote revocation pending. Retry disconnect." }, "401": { "content": { "application/json": { "schema": { "properties": { "checked_at": { "format": "date-time", "type": "string" }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry": { "type": "string" } }, "required": [ "code", "message", "retry" ], "type": "object" }, "ok": { "const": false }, "request_id": { "type": "string" } }, "required": [ "ok", "request_id", "checked_at", "error" ], "type": "object" } } }, "description": "Protocol failure." }, "403": { "content": { "application/json": { "schema": { "properties": { "checked_at": { "format": "date-time", "type": "string" }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry": { "type": "string" } }, "required": [ "code", "message", "retry" ], "type": "object" }, "ok": { "const": false }, "request_id": { "type": "string" } }, "required": [ "ok", "request_id", "checked_at", "error" ], "type": "object" } } }, "description": "Protocol failure." }, "500": { "content": { "application/json": { "schema": { "properties": { "checked_at": { "format": "date-time", "type": "string" }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry": { "type": "string" } }, "required": [ "code", "message", "retry" ], "type": "object" }, "ok": { "const": false }, "request_id": { "type": "string" } }, "required": [ "ok", "request_id", "checked_at", "error" ], "type": "object" } } }, "description": "Protocol failure." }, "503": { "content": { "application/json": { "schema": { "properties": { "checked_at": { "format": "date-time", "type": "string" }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry": { "type": "string" } }, "required": [ "code", "message", "retry" ], "type": "object" }, "ok": { "const": false }, "request_id": { "type": "string" } }, "required": [ "ok", "request_id", "checked_at", "error" ], "type": "object" } } }, "description": "Protocol failure." } } } }, "/installation/challenge": { "post": { "operationId": "installation_challenge", "requestBody": { "content": { "application/json": { "schema": { "additionalProperties": false, "properties": { "body_digest": { "pattern": "^[A-Za-z0-9_-]{43}$", "type": "string" }, "credential_type": { "const": "access", "default": "access" }, "method": { "const": "POST" }, "path": { "enum": [ "/disconnect", "/tools/get_account", "/tools/list_transactions", "/tools/list_purchases", "/tools/start_purchase", "/tools/get_purchase_status", "/tools/answer_purchase_question", "/tools/submit_answer", "/tools/report_checkout_result", "/tools/report_checkout_step", "/tools/cancel_purchase", "/tools/give_back_gift_card", "/tools/list_gift_card_merchants", "/tools/get_merchants", "/tools/search_products" ], "type": "string" } }, "required": [ "path", "method", "body_digest" ], "type": "object" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "additionalProperties": false, "properties": { "key_bound": { "const": false } }, "required": [ "key_bound" ], "type": "object" }, { "additionalProperties": false, "properties": { "expires_in": { "const": 60 }, "key_bound": { "const": true }, "key_id": { "type": "string" }, "message": { "type": "string" }, "nonce": { "type": "string" } }, "required": [ "key_bound", "key_id", "nonce", "message", "expires_in" ], "type": "object" } ] } } }, "description": "Installation challenge or unbound bearer result." }, "400": { "content": { "application/json": { "schema": { "properties": { "checked_at": { "format": "date-time", "type": "string" }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry": { "type": "string" } }, "required": [ "code", "message", "retry" ], "type": "object" }, "ok": { "const": false }, "request_id": { "type": "string" } }, "required": [ "ok", "request_id", "checked_at", "error" ], "type": "object" } } }, "description": "Protocol failure; no tool executes." }, "401": { "content": { "application/json": { "schema": { "properties": { "checked_at": { "format": "date-time", "type": "string" }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry": { "type": "string" } }, "required": [ "code", "message", "retry" ], "type": "object" }, "ok": { "const": false }, "request_id": { "type": "string" } }, "required": [ "ok", "request_id", "checked_at", "error" ], "type": "object" } } }, "description": "Protocol failure; no tool executes." }, "403": { "content": { "application/json": { "schema": { "properties": { "checked_at": { "format": "date-time", "type": "string" }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry": { "type": "string" } }, "required": [ "code", "message", "retry" ], "type": "object" }, "ok": { "const": false }, "request_id": { "type": "string" } }, "required": [ "ok", "request_id", "checked_at", "error" ], "type": "object" } } }, "description": "Protocol failure; no tool executes." }, "429": { "content": { "application/json": { "schema": { "properties": { "checked_at": { "format": "date-time", "type": "string" }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry": { "type": "string" } }, "required": [ "code", "message", "retry" ], "type": "object" }, "ok": { "const": false }, "request_id": { "type": "string" } }, "required": [ "ok", "request_id", "checked_at", "error" ], "type": "object" } } }, "description": "Protocol failure; no tool executes." }, "500": { "content": { "application/json": { "schema": { "properties": { "checked_at": { "format": "date-time", "type": "string" }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry": { "type": "string" } }, "required": [ "code", "message", "retry" ], "type": "object" }, "ok": { "const": false }, "request_id": { "type": "string" } }, "required": [ "ok", "request_id", "checked_at", "error" ], "type": "object" } } }, "description": "Protocol failure; no tool executes." }, "503": { "content": { "application/json": { "schema": { "properties": { "checked_at": { "format": "date-time", "type": "string" }, "error": { "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "retry": { "type": "string" } }, "required": [ "code", "message", "retry" ], "type": "object" }, "ok": { "const": false }, "request_id": { "type": "string" } }, "required": [ "ok", "request_id", "checked_at", "error" ], "type": "object" } } }, "description": "Protocol failure; no tool executes." } } } }, "/openapi.json": { "get": { "operationId": "get_openapi", "responses": { "200": { "content": { "application/json": { "schema": { "type": "object" } } }, "description": "This generated OpenAPI document." } }, "security": [] } }, "/tools": { "get": { "operationId": "list_tools", "responses": { "200": { "content": { "application/json": { "schema": { "properties": { "tools": { "items": { "required": [ "name", "description", "inputSchema", "outputSchema", "annotations" ], "type": "object" }, "type": "array" } }, "required": [ "tools" ], "type": "object" } } }, "description": "Tool catalogue served by this instance." } }, "security": [] } }, "/tools/answer_purchase_question": { "post": { "description": "Use this when a purchase is waiting on the user (needs_details or needs_answer): send their reply to purchase.question, or feedback after purchase.follow_up, or at any time. Pass the question id and a type. Show the prompt verbatim and wait; never answer for the user. On kind otp it is the code the merchant sent the user to sign in: send it once, then never repeat or keep it. Never send a password, a payment or bank code, or a card detail. Supply a new idempotency_key for each new answer. Retry with the same key and answer. Then keep reading get_purchase_status.", "operationId": "answer_purchase_question", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_purchase_questionInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_purchase_questionOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_purchase_questionOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_purchase_questionOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_purchase_questionOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_purchase_questionOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_purchase_questionOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_purchase_questionOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_purchase_questionOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_purchase_questionOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_purchase_questionOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/answer_purchase_questionOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": false, "title": "Answer a purchase question" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [] } }, "/tools/cancel_purchase": { "post": { "description": "Before any checkout report, request a stop when the user changes their mind or the merchant total differs. Envoy refuses cancel_purchase after any report_checkout_result and explains that the purchase must reconcile. Cancellation is not proof of a refund or card blocking; follow the returned purchase and next action.", "operationId": "cancel_purchase", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_purchaseInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_purchaseOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_purchaseOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_purchaseOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_purchaseOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_purchaseOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_purchaseOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_purchaseOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_purchaseOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_purchaseOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_purchaseOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/cancel_purchaseOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": true, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": false, "title": "Cancel a purchase" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [] } }, "/tools/get_account": { "post": { "description": "Read account sections at task start or when the purchase reference is lost. Defaults to balance, services, active_purchase and held_purchases (money in open agent purchases, separate from held by the bank). Add profile for the user's name, verified mobile and email, or addresses for saved delivery addresses to fill checkout forms. Never returns card details.", "operationId": "get_account", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_accountInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_accountOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_accountOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_accountOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_accountOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_accountOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_accountOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_accountOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_accountOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_accountOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_accountOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_accountOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true, "title": "Read account" }, "x-envoy-personal-paths": [ "data.account.profile", "data.account.addresses" ], "x-envoy-secret-paths": [] } }, "/tools/get_merchants": { "post": { "description": "Deprecated name of list_gift_card_merchants; same input and result. Prefer list_gift_card_merchants.", "operationId": "get_merchants", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_merchantsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_merchantsOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_merchantsOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_merchantsOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_merchantsOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_merchantsOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_merchantsOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_merchantsOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_merchantsOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_merchantsOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_merchantsOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_merchantsOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true, "title": "List gift-card merchants (old name)" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [] } }, "/tools/get_purchase_status": { "post": { "description": "Omit purchase for the active/latest one; pass after_revision to hold up to 45 seconds, then call again at once; without it, the reply is immediate. For agent checkout, ready carries the card: pay once and report. No card follows a report or disconnect. After a failed report, follow recovery: start_purchase with retry_of only when offered, or a new ready handout after reconciliation. When checkout_by is envoy, no card is released: Envoy checks out. Relay purchase.question.prompt; submit the user's answer. Stop after four unchanged holds or when told.", "operationId": "get_purchase_status", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_purchase_statusInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_purchase_statusOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_purchase_statusOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_purchase_statusOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_purchase_statusOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_purchase_statusOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_purchase_statusOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_purchase_statusOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_purchase_statusOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_purchase_statusOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_purchase_statusOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/get_purchase_statusOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true, "title": "Check purchase status" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [ "data.payment_details" ] } }, "/tools/give_back_gift_card": { "post": { "description": "Give back a gift_card purchase whose code you cannot use, with the product: Envoy checks out with it. Until it reads ready again, never use the code, pay or report. Follow get_purchase_status; the user enters any merchant sign-in code in the Envoy app, never in chat.", "operationId": "give_back_gift_card", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/give_back_gift_cardInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/give_back_gift_cardOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/give_back_gift_cardOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/give_back_gift_cardOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/give_back_gift_cardOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/give_back_gift_cardOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/give_back_gift_cardOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/give_back_gift_cardOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/give_back_gift_cardOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/give_back_gift_cardOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/give_back_gift_cardOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/give_back_gift_cardOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": true, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": false, "title": "Give back a gift card" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [] } }, "/tools/list_gift_card_merchants": { "post": { "description": "List merchants selling gift cards. Only a listed merchant can be bought; Envoy picks from amounts or amount_range for the cart total. discount_percent is an indicative product maximum; null means none reported. Say \"up to\". The actual purchase quote is authoritative; until available, payable is unknown. redeem_at says where the gift card is used: account — add it to the user's account balance on the merchant site, then check out normally; checkout — enter it at the merchant's payment step; null — not known yet. To buy, call start_purchase with rail \"gift_card\".", "operationId": "list_gift_card_merchants", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_gift_card_merchantsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_gift_card_merchantsOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_gift_card_merchantsOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_gift_card_merchantsOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_gift_card_merchantsOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_gift_card_merchantsOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_gift_card_merchantsOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_gift_card_merchantsOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_gift_card_merchantsOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_gift_card_merchantsOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_gift_card_merchantsOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_gift_card_merchantsOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true, "title": "List gift-card merchants" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [] } }, "/tools/list_purchases": { "post": { "description": "Use this when the user asks about a purchase and you lack its purchase_id: purchases made through you, newest first. States may be out of date: check one with get_purchase_status before telling the user.", "operationId": "list_purchases", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_purchasesInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_purchasesOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_purchasesOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_purchasesOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_purchasesOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_purchasesOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_purchasesOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_purchasesOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_purchasesOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_purchasesOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_purchasesOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_purchasesOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true, "title": "List purchases" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [] } }, "/tools/list_transactions": { "post": { "description": "Read the user's transaction history exactly as the Envoy app shows it, newest first, with an opaque pagination cursor. from must not be later than to.", "operationId": "list_transactions", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_transactionsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_transactionsOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_transactionsOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_transactionsOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_transactionsOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_transactionsOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_transactionsOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_transactionsOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_transactionsOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_transactionsOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_transactionsOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_transactionsOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true, "title": "List transactions" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [] } }, "/tools/report_checkout_result": { "post": { "description": "Only when checkout_by is agent: report paid only on merchant confirmation; if completion is unclear, report failed with failure_reason other. For other failures, choose the closest failure_reason. Include the exact checkout_attempt_id from the handout when supplied. A report is an observation, not settlement; Envoy refuses cancel_purchase afterward. Retry after failed only once money is settled and the prior card is terminal, and only with a new ready handout or accepted start_purchase retry_of. First report wins. Never pay while verifying.", "operationId": "report_checkout_result", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_resultInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_resultOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_resultOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_resultOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_resultOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_resultOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_resultOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_resultOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_resultOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_resultOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_resultOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_resultOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": true, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": false, "title": "Report checkout result" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [] } }, "/tools/report_checkout_step": { "post": { "description": "Call at each step of your own checkout (checkout_by agent): the user watches it live in the Envoy app. Moves no money, returns no card. Repeats are harmless.", "operationId": "report_checkout_step", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_stepInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_stepOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_stepOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_stepOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_stepOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_stepOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_stepOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_stepOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_stepOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_stepOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_stepOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/report_checkout_stepOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": false, "title": "Report a checkout step" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [] } }, "/tools/search_products": { "post": { "description": "Search Elixir's marketplace when the user wants a product and names no merchant, or asks for Elixir or Envoy. Show each with its price. To buy one or several, call start_purchase once with items [{name, quantity, product_id}], total = the sum of their total.display (e.g. \"₹998.00\") and their merchant_url. 1mg products may add a handling fee; if Envoy answers with a different total, ask the user and resend with it. Moves no money.", "operationId": "search_products", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_productsInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_productsOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_productsOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_productsOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_productsOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_productsOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_productsOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_productsOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_productsOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_productsOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_productsOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/search_productsOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": true, "title": "Search Elixir marketplace" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [] } }, "/tools/start_purchase": { "post": { "description": "Start a purchase when the user asks to pay with Envoy or has chosen Envoy as the default for this checkout. Never ask for card details. Retry with the same key; a new key is a new purchase. Send the full cart exactly as the user asked, the delivery address, each item's image and the merchant_logo: the user sees them on the approval screen. Only items bought; no gifts. Never split a cart or lower a total. Envoy decides who checks out: read checkout_by in each reply. agent: you get a one-time card. envoy: Envoy checks out; never open the payment step. Envoy never shares a browser live-view link.", "operationId": "start_purchase", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_purchaseInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_purchaseOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_purchaseOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_purchaseOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_purchaseOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_purchaseOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_purchaseOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_purchaseOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_purchaseOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_purchaseOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_purchaseOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/start_purchaseOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": true, "idempotentHint": true, "openWorldHint": true, "readOnlyHint": false, "title": "Start a purchase" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [] } }, "/tools/submit_answer": { "post": { "description": "Deprecated name of answer_purchase_question; same input and result. Prefer answer_purchase_question.", "operationId": "submit_answer", "parameters": [ { "description": "Required when the grant has a bound installation key. Sign the exact server challenge, method, external URL and raw body.", "in": "header", "name": "Envoy-Installation-Proof", "required": false, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submit_answerInput" } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submit_answerOutput" } } }, "description": "Success or business outcome." }, "400": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submit_answerOutput" } } }, "description": "INVALID_INPUT: Fix the supplied input." }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submit_answerOutput" } } }, "description": "UNAUTHENTICATED: Reconnect through Central Auth." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submit_answerOutput" } } }, "description": "NOT_ALLOWED: The operation is not allowed.; SERVICE_NOT_ENABLED: The service is not enabled." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submit_answerOutput" } } }, "description": "NOT_FOUND: Purchase absent or owned by another user." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submit_answerOutput" } } }, "description": "ACTIVE_PURCHASE_EXISTS: An active purchase already exists.; IDEMPOTENCY_CONFLICT: The same key has different input.; STATE_CONFLICT: The operation conflicts with the current state." }, "413": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submit_answerOutput" } } }, "description": "INVALID_INPUT: the request body exceeds 64 KB (error.fields path \"/\"). The only status that differs from the registry mapping." }, "422": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submit_answerOutput" } } }, "description": "NO_RAIL: No rail can serve this purchase; nothing was created." }, "426": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submit_answerOutput" } } }, "description": "CLIENT_UPDATE_REQUIRED: Update the client." }, "429": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submit_answerOutput" } } }, "description": "RATE_LIMITED: Wait before retrying." }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/submit_answerOutput" } } }, "description": "UNAVAILABLE: The service is unavailable; follow retryable and next." } }, "x-envoy-annotations": { "destructiveHint": false, "idempotentHint": true, "openWorldHint": false, "readOnlyHint": false, "title": "Answer Envoy (old name)" }, "x-envoy-personal-paths": [], "x-envoy-secret-paths": [] } } }, "security": [ { "centralBearer": [] } ], "servers": [ { "description": "Envoy API base URL", "url": "https://api.envoy.money" } ], "x-envoy-contract": { "availability": "Served at /tools and /mcp by every Envoy instance; contract 1 is retired and no longer served. Envoy decides for each purchase who checks out: the agent with a one-time card (checkout_by agent) or Envoy itself (checkout_by envoy)", "contract": "envoy@2026-10", "evidence": "Served at /tools and /mcp by every Envoy instance. Examples use synthetic data.", "publicPaths": { "browserTool": "/api/browser/tools/{tool}", "disconnect": "/disconnect", "installationChallenge": "/installation/challenge", "mcp": "/mcp", "openapi": "/openapi.json", "tool": "/tools/{tool}", "tools": "/tools" }, "revision": "envoy@2026-10" }, "x-envoy-unavailable-tools": [] }