Glossary
One definition for each Envoy term, purchase state, situation and money value, plus the support reference.
Look up a term here. Each term has one meaning. Terms marked REST only appear on the HTTP API, not in MCP replies.
Support revision: envoy@2026-10. Last updated: 1 November 2026.
Terms
Purchase
One buying intent that Envoy tracks from start to finish. Its identifier is purchase_id. Do not call it a payment, an order or a card request. A purchase uses at most one one-time card. When Envoy checks out itself, the agent receives no card details.
One-time card
A RuPay card that Envoy issues for one purchase, after the user approves it, with an amount limit. The agent pays once with it. The funding limits the value. Envoy does not promise a merchant lock, true single use or immediate blocking by the issuer. In code, the rail value is otu_card (REST only). Do not call it a virtual card. It holds only the approved amount, from the user's Envoy balance, and it is not the user's own card. Like every Envoy card, it is a prepaid payment instrument (PPI) issued by LivQuik Technology (India) Private Limited, an RBI-authorised PPI issuer. See Envoy's terms.
Card limit
The amount range for one one-time card: ₹10 to ₹10,000. A purchase uses at most one card. A total below ₹10 fails, and nothing is created. Envoy can check out a larger total itself.
Gift card
A merchant voucher used for an eligible purchase. The user follows the returned approval or payment task in the Envoy app, or pays a returned link. purchase.amount is its face value; purchase.funding.amount is the returned link price. The app task alone does not identify the funding source. Envoy may complete merchant checkout itself. An authorized ready handout can release the voucher code and PIN. Keep them secret. See Buy and follow a gift card.
Payment link
The URL in a gift-card pay_link task. Give it to the user once. The user opens and pays it themselves. The agent never opens or pays it. The link has its own amount and server-provided expiry.
Idempotency key
The idempotency_key you choose for one intent: 16 to 64 characters, and it must not start with pur_. Use one key per intent. Retrying with the same key returns the same purchase. A new key starts a new purchase.
Approval
The user's passkey approval of one purchase in the Envoy app. Card and ordinary Envoy checkout need approval. A gift-card link instead asks the user to pay the link themselves. A connection is not approval. The agent cannot approve. Spend Rules (automatic payments within rules the user sets) are coming soon and are not available yet.
checkout_by
The field that says who pays at the merchant. agent means the agent uses this purchase's card or paid gift-card voucher once when ready. envoy means Envoy checks out itself and releases no card. null means Envoy has not decided. Do not guess. Envoy sets it for each purchase and can change it from agent to envoy.
Connection
The OAuth link between an agent host and the user's Envoy account. It lets the agent read and request. It never lets the agent spend alone. See How Envoy works.
Envoy wallet
The marketing name for the Envoy account balance. It is a prepaid balance, held by LivQuik Technology (India) Private Limited, an RBI-authorised PPI issuer, in an escrow account. Envoy provides the technology and does not hold the money. Balance-funded purchases use it. A gift-card link and an operated retry can use separate funding as the returned task explains.
Host
The app that runs the agent, such as Claude, ChatGPT, Grok or Instinct. See Connect your assistant.
Envoy app
The app where the user approves purchases when asked, adds money and completes KYC. When Envoy checks out itself and the bank asks for a code, the user enters that bank OTP in the app. Not every purchase needs one.
KYC
Identity verification. It has two levels, min-KYC and full-KYC. The user completes it only in the Envoy app. See KYC and eligibility.
Transaction
An account entry returned by list_transactions. A transaction is not a purchase.
Question
The open purchase.question while the state is needs_details or needs_answer. It has an id, a kind and a prompt. Show the user the prompt word for word, then send the user's reply with submit_answer. Kind otp asks for a merchant or Instinct vault sign-in code, as the exact prompt states. Envoy never asks for a password through chat. A payment or bank code is never a question: on agent checkout the card's checkout_code is its bank OTP, and on Envoy checkout the user enters any bank OTP in the Envoy app.
Follow-up
The optional purchase.follow_up on a completed purchase. It asks for feedback. It is not a state, and the purchase stays completed. Answer it with submit_answer and type feedback, or skip it.
Replies
Situation
The situation field in an MCP reply. It says where the purchase stands. Values are in Situations.
Next
The next field in a reply. It tells the agent what to do now. Pass next.args unchanged to next.tool. Over MCP, next is {tool, args, wait_seconds}. Over HTTP, it also has an action (REST only; see Next actions).
Support reference
The short code EV-XXXXXX (support_ref) in a reply. Quote it to support at envoy.money/support. Support uses it to find the request. Give it to the user only when they ask for help.
Situations
MCP replies carry one situation.
| Situation | Means |
|---|---|
needs_details | Envoy needs more purchase details. |
needs_answer | Envoy asks the user a question. Send the reply with submit_answer. |
waiting_for_user | The user completes the returned app task, or pays a gift-card payment link themselves. |
working | Envoy is preparing payment, checking out, or directing you to a linked replacement. Follow next. |
ready | This purchase's card or paid gift-card voucher can be used as instructed. |
confirming | Money may have moved and is not settled. |
done | The purchase is complete. Read money and the briefing separately; payment may be collected on delivery. |
stopped | The purchase is over. |
needs_support | Envoy cannot tell what happened. |
See Replies and next steps for what the agent does in each.
Money
MCP replies carry one money value.
| Value | Means |
|---|---|
not_charged | No money moved. |
set_aside | Money is committed to the purchase's card or gift card; merchant payment is not yet confirmed. |
charged | Money was taken. |
refunding | A refund has started. |
refunded | The money came back. |
unknown | Envoy cannot tell yet. Do not pay again. |
Retry
The retry field says what to do after an error or a stopped purchase.
| Value | Means |
|---|---|
same_call | Wait, then repeat the same call. |
after_fix | Fix the fields in fix, then call again. |
check_status_first | Call get_purchase_status first. |
new_purchase | This purchase is over. Start a new one if the user still wants it. |
no | Do not retry. |
Purchase states (REST only)
The HTTP API returns purchase.state. MCP replies show a situation instead.
| State | Means |
|---|---|
needs_details | Envoy needs more details. |
needs_answer | Envoy needs an answer from the user. |
waiting_for_user | The user has an app task or a gift-card payment link to pay. |
processing | Envoy is preparing payment or running checkout. |
ready | The card or paid gift-card voucher is ready. Follow the authorized handout once. |
verifying | Money is not settled yet. |
completed | The purchase is complete. The money status separately says whether payment was charged or the merchant collects on delivery. |
failed | The purchase failed. |
cancelled | The purchase was cancelled. |
superseded | A linked purchase replaced this one. |
See the state table in the reference.
Next actions
REST only. The next.action field takes one of these values: call_tool, checkout, fix_input, retry, continue, done, stop, reconnect, update_client. See Errors and reason codes.
Error and reason codes
REST only. error.code and reason_code appear in the HTTP envelope. MCP agents do not see them. See Errors and reason codes.