Schemas
The reply envelope, purchase, next action, errors and every tool's exact input and output schema.
Every tool of contract envoy@2026-10 replies with the same envelope, over HTTP and inside MCP structuredContent. These definitions render the registry that also generates OpenAPI. Inputs are strict: unknown fields are rejected. Outputs may gain fields: ignore ones you do not recognize.
Reply envelope
| Field | Required | Type | Description and rules |
|---|---|---|---|
ok | Yes | boolean | False means this call changed nothing. |
contract | Yes | "envoy@2026-10" | Fixed revision for debugging and support; agents never branch on it. |
tool | Yes | string (the invoked tool) | Invoked tool. |
request_id | Yes | string | Request tracking ID. |
trace_id | Yes | string | Trace ID. |
server_time | Yes | string | Server time. format date-time |
replayed | Yes | boolean | Existing purchase or operation replayed. |
purchase | Yes | object or null | V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence. |
data | Yes | object or null | — |
next | Yes | object | — |
user_action | Yes | object or null | — |
origin | No | "client" | Only on a failure the client made locally with no server reply; request_id is then not a server ID. |
follow_ups | No | array of object | — |
error | Yes | object or null | — |
Purchase
| Field | Required | Type | Description and rules |
|---|---|---|---|
purchase_id | Yes | string | Purchase ID: pur_ followed by 32 lowercase hexadecimal digits. pattern ^pur_[a-f0-9]{32}$ |
service | Yes | "purchase" | Launch service. |
idempotency_key | Yes | string | One key per intent; retry with the same key. A new key is a new purchase. minLength 16; maxLength 64; 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_-]*$ |
revision | Yes | integer | Purchase revision. minimum 0 |
terminal | Yes | boolean | Whether the lifecycle state is terminal. |
state | Yes | "needs_details" | "needs_answer" | "waiting_for_user" | "processing" | "ready" | "verifying" | "completed" | "failed" | "cancelled" | "superseded" | Purchase lifecycle state. |
user_task | Yes | "approve" | "enter_otp" | "add_money" | "pay_link" | null | 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. |
reason_code | Yes | "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 | 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. |
status_text | Yes | string | One plain sentence explaining this state. Safe to show the user verbatim. minLength 1; maxLength 300 |
rail | Yes | "otu_card" | "operated_checkout" | "elixir_marketplace" | "gift_card" | null | 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. |
rail_reason | Yes | "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 | Why the rail was selected. Reserved, not sent today: RAIL_MERCHANT_REJECTS_RUPAY, RAIL_ISSUER_UNAVAILABLE, RAIL_OPERATED_CART_UNSUPPORTED, RAIL_INSUFFICIENT_BALANCE. |
checkout_by | Yes | "agent" | "envoy" | null | 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. |
merchant | Yes | object | — |
merchant.name | Yes | string | Merchant name. |
merchant.url | Yes | string | Merchant URL. format uri; pattern ^https:// |
amount | Yes | object | — |
amount.minor | Yes | integer | Amount in paise. minimum 0 |
amount.currency | Yes | "INR" | Indian rupees. |
amount.display | Yes | string | Human-readable amount, e.g. ₹1,299.00. |
description | Yes | string or null | Purchase description. |
details | Yes | object | — |
details.complete | Yes | boolean | Required details are present. |
details.missing | Yes | array of string | — |
question | Yes | object or null | The open question. Null in every state but needs_details and needs_answer. |
question.id | Yes | string | Pass as question to answer_purchase_question. A later question has a different id. minLength 1; maxLength 128 |
question.kind | Yes | "address" | "user_request" | "text" | "password" | "otp" | 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. |
question.prompt | Yes | string | Envoy's question in its own words. Show it to the user verbatim. minLength 1; maxLength 300 |
question.asked_at | Yes | string | When Envoy asked it. format date-time |
follow_up | Yes | object or null | Optional feedback request. Present only on a completed purchase; never blocks anything. |
follow_up.id | Yes | string | Pass as question to answer_purchase_question with type feedback. minLength 1; maxLength 128 |
follow_up.kind | Yes | "feedback" | feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5. |
follow_up.prompt | Yes | string | Envoy's request in its own words. Ask the user only if it fits the conversation. minLength 1; maxLength 300 |
approval | Yes | object | — |
approval.state | Yes | "pending" | "approved" | "denied" | "expired" | null | Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run. |
approval.method | Yes | "passkey" | "otp" | null | Consent method. |
approval.decide_by | Yes | string or null | Approval deadline. format date-time |
approval.approval_url | Yes | string or null | Always null. Approvals happen in the Envoy app; Envoy sends no link to agents. format uri; pattern ^https:// |
payment_ready | Yes | object | — |
payment_ready.available | Yes | boolean | The card or gift card is carried in get_purchase_status data.payment_details while ready. |
payment_ready.kind | Yes | "card" | "gift_card" | null | Payment detail kind: card on otu_card, gift_card on gift_card. |
payment_ready.expires_at | Yes | string or null | When spending access closes. Null means no known deadline, never expired. format date-time |
payment_ready.closed | No | boolean | Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund. |
money | Yes | object | — |
money.status | Yes | "not_started" | "unknown" | "debited" | "refund_pending" | "refunded" | "merchant_collects" | 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. |
money.paid | Yes | object or null | — |
money.merchant_order_ref | Yes | string or null | Merchant order reference. |
receipt | Yes | object or null | Receipt. Null unless the purchase is completed. Carries no links. |
receipt.merchant_order_ref | Yes | string or null | Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given. |
receipt.paid | Yes | object | — |
receipt.card | Yes | object or null | Card summary; null when no verified non-secret source exists. |
receipt.completed_at | Yes | string | When Envoy recorded the completion. format date-time |
chain | Yes | object | — |
chain.supersedes | Yes | string or null | Purchase ID: pur_ followed by 32 lowercase hexadecimal digits. pattern ^pur_[a-f0-9]{32}$ |
chain.superseded_by | Yes | string or null | Purchase ID: pur_ followed by 32 lowercase hexadecimal digits. pattern ^pur_[a-f0-9]{32}$ |
agent | Yes | object | — |
agent.agent_id | Yes | string | Stable host identity. |
agent.display_name | Yes | string | Display name. |
agent.verification | Yes | "cimd" | "origin" | "unverified" | Host verification level. |
created_at | Yes | string | Creation time. format date-time |
updated_at | Yes | string | Last change time. format date-time |
funding | No | object | 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. |
funding.url | Yes | string | The payment link. Give it to the user to open and pay; never open or pay it yourself. format uri; pattern ^https:// |
funding.amount | Yes | object | — |
funding.expires_at | Yes | string | When the link stops accepting payment; also approval.decide_by. format date-time |
Next
| Field | Required | Type | Description and rules |
|---|---|---|---|
action | Yes | "call_tool" | "checkout" | "fix_input" | "retry" | "continue" | "done" | "stop" | "reconnect" | "update_client" | What the agent does next. |
tool | Yes | "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 | Tool to call next. |
args | Yes | object or null | Pass verbatim as the arguments of next.tool. |
instruction | Yes | string | Instruction for the agent. Do not show it to the user. minLength 1; maxLength 600 |
after_seconds | Yes | integer or null | Seconds to wait before the next call. minimum 0 |
by | Yes | string or null | Stop waiting and tell the user after this time. format date-time |
User action
| Field | Required | Type | Description and rules |
|---|---|---|---|
task | Yes | "approve" | "enter_otp" | "add_money" | "resolve_active_purchase" | "pay_link" | What the user must do. |
url | Yes | string or null | 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:// |
by | Yes | string or null | Deadline for the user. format date-time |
message | Yes | string | Safe to show the user verbatim. minLength 1; maxLength 300 |
Error
| Field | Required | Type | Description and rules |
|---|---|---|---|
code | Yes | "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" | Contract error code. |
message | Yes | string | Safe to show the user. |
fields | Yes | array of object | maxItems 10 |
fields[].path | Yes | string | JSON pointer of the rejected field. maxLength 128 |
fields[].problem | Yes | string | What is wrong. maxLength 200 |
fields[].expected | Yes | string or null | What the value should be. maxLength 200 |
reason_code | Yes | "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 | 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. |
retryable | Yes | boolean | Whether a retry is allowed. |
retry_after_seconds | Yes | integer or null | Retry delay in seconds. minimum 0 |
Purchase states
| State | Terminal | Held read | Meaning |
|---|---|---|---|
needs_details | No | No | Envoy asks for a missing detail in purchase.question. Answer it with answer_purchase_question. |
needs_answer | No | No | Relay purchase.question to the user and send their answer with answer_purchase_question. |
waiting_for_user | No | Yes | User approves (for a gift card: pays on the approval screen), enters the operated consent OTP or adds money in the Envoy app, or pays a gift card's payment link. |
processing | No | Yes | Core is preparing the card or running checkout. |
ready | No | No | Fresh authorized card details, or a paid gift card's code, may be released. Pay, then report. |
verifying | No | Yes | Money is unsettled. Never pay again or restart this intent. |
completed | Yes | No | Completion follows money evidence, not an agent report. |
failed | Yes | No | Purchase failed; unknown money outcomes still require reconciliation. |
cancelled | Yes | No | Purchase cancelled. |
superseded | Yes | No | Purchase replaced by a linked purchase. |
Next actions
call_tool, checkout, fix_input, retry, continue, done, stop, reconnect, update_client.
Error codes
| Code | HTTP status | Meaning | What the agent does |
|---|---|---|---|
INVALID_INPUT | 400 | Fix the supplied input. | Fix every field listed in error.fields, then call the same tool once more. |
UNAUTHENTICATED | 401 | Reconnect through Central Auth. | Ask the user to reconnect Envoy, then retry this call. |
NOT_ALLOWED | 403 | The operation is not allowed. | This connection may not do that. Tell the user; do not retry. |
SERVICE_NOT_ENABLED | 403 | The service is not enabled. | This Envoy service is not enabled for the user. Tell the user; do not retry. |
NOT_FOUND | 404 | Purchase absent or owned by another user. | No purchase matches that reference. Check the purchase id from this task; do not start a new purchase to recover. |
IDEMPOTENCY_CONFLICT | 409 | The same key has different input. | Retry with the original inputs unchanged, or use a new idempotency_key only for a genuinely new purchase. |
ACTIVE_PURCHASE_EXISTS | 409 | An active purchase already exists. | Another purchase is in progress. Show the user the user_action message and stop this attempt. |
STATE_CONFLICT | 409 | The operation conflicts with the current state. | This conflicts with the current state. Tell the user; do not retry. |
NO_RAIL | 422 | No rail can serve this purchase; nothing was created. | Envoy cannot pay this purchase. Tell the user why using error.message; do not retry or split it. |
RATE_LIMITED | 429 | Wait before retrying. | Wait next.after_seconds, then retry the same call unchanged. |
UNAVAILABLE | 503 | The service is unavailable; follow retryable and next. | Wait next.after_seconds, then retry the same call unchanged; never pay elsewhere meanwhile. |
CLIENT_UPDATE_REQUIRED | 426 | Update the client. | This client is too old. Tell the user to update it. |
Reason codes
Rail: 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.
Purchase: 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.
get_account
Exact definition of get_account input
{
"type": "object",
"properties": {
"include": {
"type": "array",
"items": {
"type": "string",
"description": "Selected account section.",
"enum": [
"balance",
"limits",
"services",
"active_purchase",
"agent",
"profile",
"addresses",
"held_purchases"
]
},
"uniqueItems": true,
"default": [
"balance",
"services",
"active_purchase",
"held_purchases"
],
"description": "Sections to read. A single string is also accepted."
}
},
"required": [],
"additionalProperties": false
}Exact definition of get_account output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"get_account"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {
"account": {
"type": "object",
"properties": {
"currency": {
"type": [
"string",
"null"
],
"description": "Account currency."
},
"balance": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"held": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"spendable": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"held_purchases": {
"type": [
"object",
"null"
],
"properties": {
"available": {
"type": "boolean",
"description": "Whether Core supplied the open purchase money read."
},
"reason": {
"type": [
"string",
"null"
],
"description": "Read unavailable, including when the connected Core does not support this operation.",
"enum": [
"upstream_unavailable",
null
]
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"merchant": {
"type": [
"string",
"null"
],
"description": "Merchant name."
},
"amount": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"exact": {
"type": "boolean",
"description": "True when Core knows the exact held amount."
},
"state": {
"type": "string",
"description": "unknown means Core returned a state Envoy cannot interpret; its amount is withheld.",
"enum": [
"held",
"returning",
"unknown"
]
},
"since": {
"type": [
"string",
"null"
],
"description": "When this open money position began; null when Core omitted or returned an invalid timestamp.",
"format": "date-time"
}
},
"required": [
"purchase_id",
"merchant",
"amount",
"exact",
"state",
"since"
],
"additionalProperties": false
}
},
"total": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"truncated": {
"type": [
"boolean",
"null"
],
"description": "True when the list is incomplete because rows were omitted or skipped."
}
},
"required": [
"available",
"reason",
"items",
"total",
"truncated"
],
"additionalProperties": false,
"description": "Open agent purchase card money, separate from the account held figure."
},
"limits_reserved": {
"type": "string",
"description": "Limits are informational, not reserved or a promise of payment approval.",
"enum": [
"not_reserved"
]
},
"unavailable": {
"type": "array",
"items": {
"type": "string",
"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"
]
}
},
"profile": {
"type": "object",
"properties": {
"name": {
"type": [
"string",
"null"
],
"description": "Full name on the Envoy account."
},
"mobile": {
"type": [
"string",
"null"
],
"description": "Verified mobile number in E.164 form."
},
"email": {
"type": [
"string",
"null"
],
"description": "Email address on the Envoy account. Not verified."
}
},
"required": [
"name",
"mobile",
"email"
],
"additionalProperties": false,
"description": "Contact details for delivery and checkout forms. A null value has no source.",
"x-envoy-secret": true
},
"addresses": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Pass as address_id to start_purchase."
},
"label": {
"type": "string",
"description": "User label, e.g. Home. Empty when the user set none."
},
"is_default": {
"type": "boolean",
"description": "The user's default address."
},
"name": {
"type": [
"string",
"null"
],
"description": "Recipient name."
},
"phone": {
"type": [
"string",
"null"
],
"description": "Recipient phone, as the user saved it."
},
"line1": {
"type": "string",
"description": "First address line."
},
"line2": {
"type": [
"string",
"null"
],
"description": "Second address line."
},
"line3": {
"type": [
"string",
"null"
],
"description": "Third address line."
},
"city": {
"type": "string",
"description": "City."
},
"state": {
"type": "string",
"description": "State."
},
"pin_code": {
"type": "string",
"description": "PIN code."
},
"country": {
"type": [
"string",
"null"
],
"description": "Country."
},
"line": {
"type": "string",
"description": "Address on one line, for a single-field form."
}
},
"required": [
"id",
"label",
"is_default",
"name",
"phone",
"line1",
"line2",
"line3",
"city",
"state",
"pin_code",
"country",
"line"
],
"additionalProperties": false
},
"description": "Saved delivery addresses from the Envoy app, default first. Complete list: a partial list is reported unavailable.",
"x-envoy-secret": true
},
"limits": {
"type": "array",
"items": {
"type": "object",
"properties": {
"channel": {
"type": "string",
"description": "Channel."
},
"period": {
"type": "string",
"description": "Limit period.",
"enum": [
"day",
"transaction"
]
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
}
},
"required": [
"channel",
"period",
"amount"
],
"additionalProperties": false
}
},
"services": {
"type": "array",
"items": {
"type": "string",
"description": "Enabled service identifier from the registry.",
"enum": [
"purchase"
]
},
"uniqueItems": true
},
"active_purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
}
},
"required": [],
"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."
}
},
"required": [
"account"
],
"additionalProperties": false
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}list_transactions
Exact definition of list_transactions input
{
"type": "object",
"properties": {
"from": {
"type": "string",
"description": "Start date.",
"format": "date"
},
"to": {
"type": "string",
"description": "End date.",
"format": "date"
},
"limit": {
"type": "integer",
"description": "Maximum transactions.",
"minimum": 1,
"maximum": 50
},
"cursor": {
"type": "string",
"description": "Opaque pagination cursor bound to this connection, date range and page size.",
"minLength": 1,
"maxLength": 2048
}
},
"required": [],
"additionalProperties": false
}Exact definition of list_transactions output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"list_transactions"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {
"transactions": {
"type": "array",
"items": {
"type": "object",
"properties": {
"id": {
"type": "string",
"description": "Opaque statement line identifier, stable for this connection and client. It contains no card binding and grants no access.",
"minLength": 1,
"maxLength": 128
},
"occurred_at": {
"type": "string",
"description": "When it happened.",
"format": "date-time"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"direction": {
"type": "string",
"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"
]
},
"title": {
"type": "string",
"description": "What the user sees as the line's name: the merchant for a purchase.",
"minLength": 1,
"maxLength": 200
},
"subtitle": {
"type": [
"string",
"null"
],
"description": "The line's second row in the app. For an agent purchase, the agent's name.",
"maxLength": 200
},
"by_agent": {
"type": "boolean",
"description": "True when an agent made this purchase through Envoy."
},
"kind": {
"type": "string",
"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"
]
},
"status": {
"type": "string",
"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"
]
},
"card": {
"type": "string",
"description": "Which card it was on. elixir_card: the user's Elixir card, badged \"Elixir card\" in the app.",
"enum": [
"envoy",
"elixir_card",
"unknown"
]
}
},
"required": [
"id",
"occurred_at",
"amount",
"direction",
"title",
"subtitle",
"by_agent",
"kind",
"status",
"card"
],
"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."
}
},
"next_cursor": {
"type": [
"string",
"null"
],
"description": "Opaque next cursor."
}
},
"required": [
"transactions",
"next_cursor"
],
"additionalProperties": false
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}list_purchases
Exact definition of list_purchases input
{
"type": "object",
"properties": {
"limit": {
"type": "integer",
"description": "How many, newest first.",
"minimum": 1,
"maximum": 20,
"default": 10
}
},
"required": [],
"additionalProperties": false
}Exact definition of list_purchases output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"list_purchases"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {
"purchases": {
"type": "array",
"items": {
"type": "object",
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
}
},
"required": [
"purchase_id",
"state",
"merchant",
"amount",
"checkout_by",
"created_at"
],
"additionalProperties": false,
"description": "One purchase as Envoy last stored it. state may be behind Core: call get_purchase for the current state."
},
"maxItems": 20
},
"truncated": {
"type": "boolean",
"description": "True when the user has more purchases than were returned."
}
},
"required": [
"purchases",
"truncated"
],
"additionalProperties": false
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}start_purchase
Exact definition of start_purchase input
{
"type": "object",
"properties": {
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"merchant_url": {
"type": "string",
"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*)?$"
},
"merchant_logo": {
"type": "string",
"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*)?$"
},
"total": {
"type": "string",
"description": "Checkout total in INR, with delivery, tax and fees. Rupees, up to 2 decimals; number also accepted, \"₹\" and thousands commas are stripped.",
"pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$",
"maxLength": 20
},
"items": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Item name, including size, colour or variant.",
"minLength": 1,
"maxLength": 200
},
"quantity": {
"type": "integer",
"description": "Quantity; default 1. Numeric string also accepted.",
"minimum": 1,
"maximum": 99,
"default": 1
},
"url": {
"type": "string",
"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*)?$"
},
"image": {
"type": "string",
"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*)?$"
},
"product_id": {
"type": "string",
"description": "A search_products product's product_id, on every item or none.",
"pattern": "^ofr_[a-f0-9]{32}$"
},
"price": {
"type": "string",
"description": "Line price in rupees, quantity included."
}
},
"required": [
"name"
],
"additionalProperties": false
},
"minItems": 1,
"maxItems": 20,
"description": "What to buy, one entry per product. Only items being bought: no free gifts or ₹0 lines."
},
"user_request": {
"type": "string",
"description": "The user's own words for this purchase, including any notes.",
"minLength": 1,
"maxLength": 300
},
"address_id": {
"type": "string",
"description": "Saved address ID from get_account with include addresses. Preferred over address. Do not also send address.",
"minLength": 1,
"maxLength": 64
},
"address": {
"type": "string",
"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.",
"minLength": 1,
"maxLength": 500
},
"max_total": {
"type": "string",
"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.",
"pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$",
"maxLength": 20
},
"product_id": {
"type": "string",
"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}$"
},
"rail": {
"type": "string",
"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"
]
},
"order_title": {
"type": "string",
"description": "Display only, as shown, like price_lines and facts; Envoy drops what it cannot show. Order title."
},
"price_lines": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "item_total|delivery|taxes_fees|packaging|discount"
},
"amount": {
"type": "string",
"description": "Rupees, positive."
}
},
"required": [],
"additionalProperties": false
},
"description": "Bill lines adding up to total."
},
"facts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string",
"description": "deliver_to|arrives|sold_by|restaurant|check_in|check_out|cancellation|booked_for"
},
"value": {
"type": "string"
}
},
"required": [],
"additionalProperties": false
},
"description": "Order facts."
},
"retry_of": {
"type": "string",
"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.",
"minLength": 16,
"maxLength": 64,
"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_-]*)$"
}
},
"required": [
"idempotency_key",
"merchant_url",
"total",
"items",
"user_request"
],
"additionalProperties": false
}Exact definition of start_purchase output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"start_purchase"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {},
"required": [],
"additionalProperties": false,
"description": "No payload declared for this tool."
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}get_purchase_status
Exact definition of get_purchase_status input
{
"type": "object",
"properties": {
"purchase": {
"type": "string",
"description": "Purchase ID or original idempotency key.",
"minLength": 16,
"maxLength": 64,
"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_-]*)$"
},
"after_revision": {
"type": "integer",
"description": "Return early when the revision changes.",
"minimum": 0
},
"wait_seconds": {
"type": "integer",
"description": "With after_revision, the read holds up to `wait_seconds` (contract maximum 45 seconds, `HOLD_MAX_SECONDS`); the server may hold less; follow `next.args.wait_seconds`. Without after_revision the read returns at once.",
"minimum": 0,
"maximum": 45
}
},
"required": [],
"additionalProperties": false
}Exact definition of get_purchase_status output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"get_purchase_status"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {
"payment_details": {
"type": "object",
"properties": {
"kind": {
"type": "string",
"description": "card: the authorized one-time RuPay card, in card. gift_card: the paid gift card, in voucher.",
"enum": [
"card",
"gift_card"
]
},
"card": {
"type": "object",
"properties": {
"number": {
"type": "string",
"description": "Synthetic examples only."
},
"expiry_month": {
"type": "string",
"description": "Expiry month."
},
"expiry_year": {
"type": "string",
"description": "Expiry year."
},
"cvv": {
"type": "string",
"description": "Card verification value."
},
"network": {
"type": "string",
"description": "RuPay only.",
"enum": [
"rupay"
]
}
},
"required": [
"number",
"expiry_month",
"expiry_year",
"cvv",
"network"
],
"additionalProperties": false
},
"checkout_code": {
"type": "string",
"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."
},
"checkout_code_expires_at": {
"type": "string",
"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"
},
"amount_limit": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"checkout_attempt_id": {
"type": "string",
"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}$"
},
"expires_at": {
"type": "string",
"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"
},
"voucher": {
"type": "object",
"properties": {
"brand": {
"type": "string",
"description": "Gift card brand."
},
"code": {
"type": "string",
"description": "Gift card code. Redeem it at the merchant checkout."
},
"pin": {
"type": "string",
"description": "Gift card PIN, when the brand has one."
},
"value": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"redemption_url": {
"type": "string",
"description": "Where the merchant redeems it, when given.",
"format": "uri",
"pattern": "^https://"
},
"redemption_instructions": {
"type": "string",
"description": "How to redeem it, from the brand."
},
"valid_until": {
"type": [
"string",
"null"
],
"description": "When the code stops working. Null means no known expiry.",
"format": "date-time"
}
},
"required": [
"brand",
"code",
"value",
"redemption_instructions",
"valid_until"
],
"additionalProperties": false,
"description": "Present exactly when kind is gift_card. value equals purchase.amount."
}
},
"required": [
"kind",
"amount_limit"
],
"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.",
"x-envoy-secret": true
}
},
"required": [
"payment_details"
],
"additionalProperties": false
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}answer_purchase_question
Exact definition of answer_purchase_question input
{
"type": "object",
"properties": {
"type": {
"type": "string",
"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"
]
},
"answer": {
"type": "string",
"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.",
"minLength": 1,
"maxLength": 800,
"x-envoy-secret": true
},
"purchase": {
"type": "string",
"description": "Purchase ID or original idempotency key.",
"minLength": 16,
"maxLength": 64,
"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_-]*)$"
},
"question": {
"type": "string",
"description": "The id from purchase.question or purchase.follow_up. An earlier question cannot be answered.",
"minLength": 1,
"maxLength": 128
},
"rating": {
"type": "integer",
"description": "Rating from 1 to 5. Feedback only.",
"minimum": 1,
"maximum": 5
},
"idempotency_key": {
"type": "string",
"description": "One key per answer. Retry with the same key and the same answer; a reused key with a different answer is refused.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
}
},
"required": [
"type",
"answer",
"idempotency_key"
],
"additionalProperties": false
}Exact definition of answer_purchase_question output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"answer_purchase_question"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {
"receipt": {
"type": "object",
"properties": {
"feedback_id": {
"type": "string",
"description": "Feedback identifier."
},
"recorded_at": {
"type": "string",
"description": "Recorded time.",
"format": "date-time"
}
},
"required": [
"feedback_id",
"recorded_at"
],
"additionalProperties": false,
"description": "Feedback receipt: present when answer_purchase_question recorded feedback."
}
},
"required": [
"receipt"
],
"additionalProperties": false
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}submit_answer
Exact definition of submit_answer input
{
"type": "object",
"properties": {
"type": {
"type": "string",
"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"
]
},
"answer": {
"type": "string",
"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.",
"minLength": 1,
"maxLength": 800,
"x-envoy-secret": true
},
"purchase": {
"type": "string",
"description": "Purchase ID or original idempotency key.",
"minLength": 16,
"maxLength": 64,
"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_-]*)$"
},
"question": {
"type": "string",
"description": "The id from purchase.question or purchase.follow_up. An earlier question cannot be answered.",
"minLength": 1,
"maxLength": 128
},
"rating": {
"type": "integer",
"description": "Rating from 1 to 5. Feedback only.",
"minimum": 1,
"maximum": 5
},
"idempotency_key": {
"type": "string",
"description": "One key per answer. Retry with the same key and the same answer; a reused key with a different answer is refused.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
}
},
"required": [
"type",
"answer",
"idempotency_key"
],
"additionalProperties": false
}Exact definition of submit_answer output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"submit_answer"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {
"receipt": {
"type": "object",
"properties": {
"feedback_id": {
"type": "string",
"description": "Feedback identifier."
},
"recorded_at": {
"type": "string",
"description": "Recorded time.",
"format": "date-time"
}
},
"required": [
"feedback_id",
"recorded_at"
],
"additionalProperties": false,
"description": "Feedback receipt: present when answer_purchase_question recorded feedback."
}
},
"required": [
"receipt"
],
"additionalProperties": false
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}report_checkout_result
Exact definition of report_checkout_result input
{
"type": "object",
"properties": {
"purchase": {
"type": "string",
"description": "Purchase ID or original idempotency key.",
"minLength": 16,
"maxLength": 64,
"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_-]*)$"
},
"checkout_attempt_id": {
"type": "string",
"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}$"
},
"outcome": {
"type": "string",
"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"
]
},
"failure_reason": {
"type": "string",
"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"
]
},
"merchant_order_ref": {
"type": "string",
"description": "Merchant order reference, as the merchant showed it (at most 128 characters, no control characters).",
"minLength": 1,
"maxLength": 128,
"pattern": "^[^\\x00-\\x1F\\x7F-\\x9F]+$"
},
"amount_paid": {
"type": "string",
"description": "Amount the merchant charged. Rupees, up to 2 decimals; number also accepted, \"₹\" and thousands commas are stripped.",
"pattern": "^[0-9]+(?:\\.[0-9]{1,2})?$",
"maxLength": 20
}
},
"required": [
"purchase",
"outcome"
],
"additionalProperties": false
}Exact definition of report_checkout_result output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"report_checkout_result"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {},
"required": [],
"additionalProperties": false,
"description": "No payload declared for this tool."
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}report_checkout_step
Exact definition of report_checkout_step input
{
"type": "object",
"properties": {
"purchase": {
"type": "string",
"description": "Purchase ID or original idempotency key.",
"minLength": 16,
"maxLength": 64,
"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_-]*)$"
},
"step": {
"type": "string",
"description": "Step reached.",
"enum": [
"merchant_opened",
"cart_built",
"payment_page_reached",
"payment_applied",
"otp_requested",
"otp_submitted",
"order_submitted",
"blocked"
]
},
"checkout_attempt_id": {
"type": "string",
"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}$"
}
},
"required": [
"purchase",
"step"
],
"additionalProperties": false
}Exact definition of report_checkout_step output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"report_checkout_step"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {},
"required": [],
"additionalProperties": false,
"description": "No payload declared for this tool."
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}cancel_purchase
Exact definition of cancel_purchase input
{
"type": "object",
"properties": {
"purchase": {
"type": "string",
"description": "Purchase ID or original idempotency key.",
"minLength": 16,
"maxLength": 64,
"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_-]*)$"
},
"reason": {
"type": "string",
"description": "Cancellation reason."
}
},
"required": [
"purchase"
],
"additionalProperties": false
}Exact definition of cancel_purchase output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"cancel_purchase"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {},
"required": [],
"additionalProperties": false,
"description": "No payload declared for this tool."
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}list_gift_card_merchants
Exact definition of list_gift_card_merchants input
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Exact definition of list_gift_card_merchants output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"list_gift_card_merchants"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {
"merchants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name, taken from its domain.",
"minLength": 1,
"maxLength": 253
},
"domain": {
"type": "string",
"description": "Merchant website domain.",
"minLength": 1,
"maxLength": 253
},
"amounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"maxItems": 1000,
"description": "Gift card face values sold. Empty when amount_range is set."
},
"amount_range": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"max": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
}
},
"required": [
"min",
"max"
],
"additionalProperties": false,
"description": "Any whole rupee from min to max; null: listed amounts only."
},
"discount_percent": {
"type": [
"number",
"null"
],
"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.",
"minimum": 0,
"maximum": 100
},
"redeem_at": {
"type": [
"string",
"null"
],
"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
]
}
},
"required": [
"name",
"domain",
"amounts",
"amount_range",
"discount_percent",
"redeem_at"
],
"additionalProperties": false
},
"maxItems": 1000,
"description": "Merchants the user can buy a gift card for right now. Empty when gift cards are not available."
}
},
"required": [
"merchants"
],
"additionalProperties": false
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}get_merchants
Exact definition of get_merchants input
{
"type": "object",
"properties": {},
"required": [],
"additionalProperties": false
}Exact definition of get_merchants output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"get_merchants"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {
"merchants": {
"type": "array",
"items": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name, taken from its domain.",
"minLength": 1,
"maxLength": 253
},
"domain": {
"type": "string",
"description": "Merchant website domain.",
"minLength": 1,
"maxLength": 253
},
"amounts": {
"type": "array",
"items": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"maxItems": 1000,
"description": "Gift card face values sold. Empty when amount_range is set."
},
"amount_range": {
"type": [
"object",
"null"
],
"properties": {
"min": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"max": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
}
},
"required": [
"min",
"max"
],
"additionalProperties": false,
"description": "Any whole rupee from min to max; null: listed amounts only."
},
"discount_percent": {
"type": [
"number",
"null"
],
"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.",
"minimum": 0,
"maximum": 100
},
"redeem_at": {
"type": [
"string",
"null"
],
"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
]
}
},
"required": [
"name",
"domain",
"amounts",
"amount_range",
"discount_percent",
"redeem_at"
],
"additionalProperties": false
},
"maxItems": 1000,
"description": "Merchants the user can buy a gift card for right now. Empty when gift cards are not available."
}
},
"required": [
"merchants"
],
"additionalProperties": false
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}search_products
Exact definition of search_products input
{
"type": "object",
"properties": {
"query": {
"type": "string",
"description": "What the user wants, in their words.",
"minLength": 1,
"maxLength": 200
},
"quantity": {
"type": "integer",
"description": "How many; default 1.",
"minimum": 1,
"maximum": 99,
"default": 1
},
"address_id": {
"type": "string",
"description": "Saved address ID from get_account to deliver to; default: the default saved address.",
"minLength": 1,
"maxLength": 64
}
},
"required": [
"query"
],
"additionalProperties": false
}Exact definition of search_products output
{
"type": "object",
"properties": {
"ok": {
"type": "boolean",
"description": "False means this call changed nothing."
},
"contract": {
"type": "string",
"description": "Fixed revision for debugging and support; agents never branch on it.",
"enum": [
"envoy@2026-10"
]
},
"tool": {
"type": "string",
"description": "Invoked tool.",
"enum": [
"search_products"
]
},
"request_id": {
"type": "string",
"description": "Request tracking ID."
},
"trace_id": {
"type": "string",
"description": "Trace ID."
},
"server_time": {
"type": "string",
"description": "Server time.",
"format": "date-time"
},
"replayed": {
"type": "boolean",
"description": "Existing purchase or operation replayed."
},
"purchase": {
"type": [
"object",
"null"
],
"properties": {
"purchase_id": {
"type": "string",
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"service": {
"type": "string",
"description": "Launch service.",
"enum": [
"purchase"
]
},
"idempotency_key": {
"type": "string",
"description": "One key per intent; retry with the same key. A new key is a new purchase.",
"minLength": 16,
"maxLength": 64,
"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_-]*$"
},
"revision": {
"type": "integer",
"description": "Purchase revision.",
"minimum": 0
},
"terminal": {
"type": "boolean",
"description": "Whether the lifecycle state is terminal."
},
"state": {
"type": "string",
"description": "Purchase lifecycle state.",
"enum": [
"needs_details",
"needs_answer",
"waiting_for_user",
"processing",
"ready",
"verifying",
"completed",
"failed",
"cancelled",
"superseded"
]
},
"user_task": {
"type": [
"string",
"null"
],
"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
]
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"status_text": {
"type": "string",
"description": "One plain sentence explaining this state. Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"rail": {
"type": [
"string",
"null"
],
"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
]
},
"rail_reason": {
"type": [
"string",
"null"
],
"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
]
},
"checkout_by": {
"type": [
"string",
"null"
],
"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
]
},
"merchant": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "Merchant name."
},
"url": {
"type": "string",
"description": "Merchant URL.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"name",
"url"
],
"additionalProperties": false
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"description": {
"type": [
"string",
"null"
],
"description": "Purchase description."
},
"details": {
"type": "object",
"properties": {
"complete": {
"type": "boolean",
"description": "Required details are present."
},
"missing": {
"type": "array",
"items": {
"type": "string",
"description": "Missing field name."
}
}
},
"required": [
"complete",
"missing"
],
"additionalProperties": false
},
"question": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question. A later question has a different id.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"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"
]
},
"prompt": {
"type": "string",
"description": "Envoy's question in its own words. Show it to the user verbatim.",
"minLength": 1,
"maxLength": 300
},
"asked_at": {
"type": "string",
"description": "When Envoy asked it.",
"format": "date-time"
}
},
"required": [
"id",
"kind",
"prompt",
"asked_at"
],
"additionalProperties": false,
"description": "The open question. Null in every state but needs_details and needs_answer."
},
"follow_up": {
"type": [
"object",
"null"
],
"properties": {
"id": {
"type": "string",
"description": "Pass as question to answer_purchase_question with type feedback.",
"minLength": 1,
"maxLength": 128
},
"kind": {
"type": "string",
"description": "feedback: how the purchase went for the user, in their words, with an optional rating from 1 to 5.",
"enum": [
"feedback"
]
},
"prompt": {
"type": "string",
"description": "Envoy's request in its own words. Ask the user only if it fits the conversation.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"id",
"kind",
"prompt"
],
"additionalProperties": false,
"description": "Optional feedback request. Present only on a completed purchase; never blocks anything."
},
"approval": {
"type": "object",
"properties": {
"state": {
"type": [
"string",
"null"
],
"description": "Core authorization state, lowercased. Null when no authorization evidence is supplied; never inferred from an operated run.",
"enum": [
"pending",
"approved",
"denied",
"expired",
null
]
},
"method": {
"type": [
"string",
"null"
],
"description": "Consent method.",
"enum": [
"passkey",
"otp",
null
]
},
"decide_by": {
"type": [
"string",
"null"
],
"description": "Approval deadline.",
"format": "date-time"
},
"approval_url": {
"type": [
"string",
"null"
],
"description": "Always null. Approvals happen in the Envoy app; Envoy sends no link to agents.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"state",
"method",
"decide_by",
"approval_url"
],
"additionalProperties": false
},
"payment_ready": {
"type": "object",
"properties": {
"available": {
"type": "boolean",
"description": "The card or gift card is carried in get_purchase_status data.payment_details while ready."
},
"kind": {
"type": [
"string",
"null"
],
"description": "Payment detail kind: card on otu_card, gift_card on gift_card.",
"enum": [
"card",
"gift_card",
null
]
},
"expires_at": {
"type": [
"string",
"null"
],
"description": "When spending access closes. Null means no known deadline, never expired.",
"format": "date-time"
},
"closed": {
"type": "boolean",
"description": "Spending access is closed: no further card details are released. Does not prove the issuer blocked the card, non-payment or a refund."
}
},
"required": [
"available",
"kind",
"expires_at"
],
"additionalProperties": false
},
"money": {
"type": "object",
"properties": {
"status": {
"type": "string",
"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"
]
},
"paid": {
"type": [
"object",
"null"
],
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference."
}
},
"required": [
"status",
"paid",
"merchant_order_ref"
],
"additionalProperties": false
},
"receipt": {
"type": [
"object",
"null"
],
"properties": {
"merchant_order_ref": {
"type": [
"string",
"null"
],
"description": "Merchant order reference: from the paid report, or from Core for an Elixir or merchant-gateway order, when given."
},
"paid": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"card": {
"type": [
"object",
"null"
],
"properties": {
"network": {
"type": "string",
"description": "Card network.",
"enum": [
"rupay"
]
},
"last4": {
"type": "string",
"description": "Last four digits of the card number.",
"pattern": "^[0-9]{4}$"
}
},
"required": [
"network",
"last4"
],
"additionalProperties": false,
"description": "Card summary; null when no verified non-secret source exists."
},
"completed_at": {
"type": "string",
"description": "When Envoy recorded the completion.",
"format": "date-time"
}
},
"required": [
"merchant_order_ref",
"paid",
"card",
"completed_at"
],
"additionalProperties": false,
"description": "Receipt. Null unless the purchase is completed. Carries no links."
},
"chain": {
"type": "object",
"properties": {
"supersedes": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
},
"superseded_by": {
"type": [
"string",
"null"
],
"description": "Purchase ID: pur_ followed by 32 lowercase hexadecimal digits.",
"pattern": "^pur_[a-f0-9]{32}$"
}
},
"required": [
"supersedes",
"superseded_by"
],
"additionalProperties": false
},
"agent": {
"type": "object",
"properties": {
"agent_id": {
"type": "string",
"description": "Stable host identity."
},
"display_name": {
"type": "string",
"description": "Display name."
},
"verification": {
"type": "string",
"description": "Host verification level.",
"enum": [
"cimd",
"origin",
"unverified"
]
}
},
"required": [
"agent_id",
"display_name",
"verification"
],
"additionalProperties": false
},
"created_at": {
"type": "string",
"description": "Creation time.",
"format": "date-time"
},
"updated_at": {
"type": "string",
"description": "Last change time.",
"format": "date-time"
},
"funding": {
"type": "object",
"properties": {
"url": {
"type": "string",
"description": "The payment link. Give it to the user to open and pay; never open or pay it yourself.",
"format": "uri",
"pattern": "^https://"
},
"amount": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"expires_at": {
"type": "string",
"description": "When the link stops accepting payment; also approval.decide_by.",
"format": "date-time"
}
},
"required": [
"url",
"amount",
"expires_at"
],
"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."
}
},
"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"
],
"additionalProperties": false,
"description": "V2.1 snapshot. Envelope validation enforces state invariants; the adapter separately enforces ownership and authoritative money evidence."
},
"data": {
"type": [
"object",
"null"
],
"properties": {
"products": {
"type": "array",
"items": {
"type": "object",
"properties": {
"product_id": {
"type": "string",
"description": "This product's offer id. Never show it to the user.",
"pattern": "^ofr_[a-f0-9]{32}$"
},
"name": {
"type": "string",
"description": "Product name, as Elixir lists it.",
"minLength": 1,
"maxLength": 200
},
"brand": {
"type": [
"string",
"null"
],
"description": "Brand, when Elixir lists one.",
"minLength": 1,
"maxLength": 500
},
"image": {
"type": [
"string",
"null"
],
"description": "Product image.",
"format": "uri",
"pattern": "^https://"
},
"price": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"quantity": {
"type": "integer",
"description": "Quantity priced.",
"minimum": 1,
"maximum": 999
},
"total": {
"type": "object",
"properties": {
"minor": {
"type": "integer",
"description": "Amount in paise.",
"minimum": 0
},
"currency": {
"type": "string",
"description": "Indian rupees.",
"enum": [
"INR"
]
},
"display": {
"type": "string",
"description": "Human-readable amount, e.g. ₹1,299.00."
}
},
"required": [
"minor",
"currency",
"display"
],
"additionalProperties": false
},
"valid_until": {
"type": "string",
"description": "The price holds until this time; search again after it.",
"format": "date-time"
},
"merchant_url": {
"type": "string",
"description": "Elixir's store. Pass it to start_purchase as merchant_url.",
"format": "uri",
"pattern": "^https://"
}
},
"required": [
"product_id",
"name",
"brand",
"image",
"price",
"quantity",
"total",
"valid_until",
"merchant_url"
],
"additionalProperties": false
},
"maxItems": 5,
"description": "Products from Elixir's own marketplace, price for one and total for the quantity. Empty when Elixir has nothing to offer right now."
}
},
"required": [
"products"
],
"additionalProperties": false
},
"next": {
"type": "object",
"properties": {
"action": {
"type": "string",
"description": "What the agent does next.",
"enum": [
"call_tool",
"checkout",
"fix_input",
"retry",
"continue",
"done",
"stop",
"reconnect",
"update_client"
]
},
"tool": {
"type": [
"string",
"null"
],
"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
]
},
"args": {
"type": [
"object",
"null"
],
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"instruction": {
"type": "string",
"description": "Instruction for the agent. Do not show it to the user.",
"minLength": 1,
"maxLength": 600
},
"after_seconds": {
"type": [
"integer",
"null"
],
"description": "Seconds to wait before the next call.",
"minimum": 0
},
"by": {
"type": [
"string",
"null"
],
"description": "Stop waiting and tell the user after this time.",
"format": "date-time"
}
},
"required": [
"action",
"tool",
"args",
"instruction",
"after_seconds",
"by"
],
"additionalProperties": false
},
"user_action": {
"type": [
"object",
"null"
],
"properties": {
"task": {
"type": "string",
"description": "What the user must do.",
"enum": [
"approve",
"enter_otp",
"add_money",
"resolve_active_purchase",
"pay_link"
]
},
"url": {
"type": [
"string",
"null"
],
"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://"
},
"by": {
"type": [
"string",
"null"
],
"description": "Deadline for the user.",
"format": "date-time"
},
"message": {
"type": "string",
"description": "Safe to show the user verbatim.",
"minLength": 1,
"maxLength": 300
}
},
"required": [
"task",
"url",
"by",
"message"
],
"additionalProperties": false
},
"origin": {
"type": "string",
"description": "Only on a failure the client made locally with no server reply; request_id is then not a server ID.",
"enum": [
"client"
]
},
"follow_ups": {
"type": "array",
"items": {
"type": "object",
"properties": {
"tool": {
"type": "string",
"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"
]
},
"args": {
"type": "object",
"description": "Pass verbatim as the arguments of next.tool.",
"additionalProperties": true
},
"why": {
"type": "string",
"description": "Reason for follow-up."
}
},
"required": [
"tool",
"args",
"why"
],
"additionalProperties": false
}
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string",
"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"
]
},
"message": {
"type": "string",
"description": "Safe to show the user."
},
"fields": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string",
"description": "JSON pointer of the rejected field.",
"maxLength": 128
},
"problem": {
"type": "string",
"description": "What is wrong.",
"maxLength": 200
},
"expected": {
"type": [
"string",
"null"
],
"description": "What the value should be.",
"maxLength": 200
}
},
"required": [
"path",
"problem",
"expected"
],
"additionalProperties": false
},
"maxItems": 10
},
"reason_code": {
"type": [
"string",
"null"
],
"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
]
},
"retryable": {
"type": "boolean",
"description": "Whether a retry is allowed."
},
"retry_after_seconds": {
"type": [
"integer",
"null"
],
"description": "Retry delay in seconds.",
"minimum": 0
}
},
"required": [
"code",
"message",
"fields",
"reason_code",
"retryable",
"retry_after_seconds"
],
"additionalProperties": false
}
},
"required": [
"ok",
"contract",
"tool",
"request_id",
"trace_id",
"server_time",
"replayed",
"purchase",
"data",
"next",
"user_action",
"error"
],
"additionalProperties": false,
"description": "Portable structural schema. validateEnvelope additionally checks success, state, continuation and secret-location invariants; it does not confer disclosure authority."
}