get_purchase_status

MCP tool get_purchase_status, called with tools/call on https://api.envoy.money/mcp (Streamable HTTP).

Omit purchase for the active/latest one; pass after_revision and the read holds up to wait_seconds (contract maximum 45 seconds, HOLD_MAX_SECONDS); the server may hold less; follow next.args.wait_seconds; call again as soon as it returns. Without after_revision the reply is immediate. For agent checkout, ready carries the card: pay once and report. No card follows a report or disconnect. After a failed report, follow recovery: start_purchase with retry_of only when offered, or a new ready handout after reconciliation. When checkout_by is envoy, no card is released: Envoy checks out. Relay purchase.question.prompt; submit the user's answer. Stop after four unchanged holds or when told.

The text content is a plain-English briefing, then one line of JSON with the slim agent data. structuredContent holds that same slim data. isError is true when the call failed and changed nothing. Diagnostics for support are in _meta["money.envoy/support"]; they are not for the model. Tool annotations describe effects; they do not grant permission. The HTTP API returns the full envelope: see the API reference page.

Input

Unknown fields are rejected. The exact input schema is on the schemas page.

Synthetic request

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_purchase_status",
    "arguments": {
      "purchase": "synthetic-intent-0001"
    }
  }
}

Hold

With after_revision, a read in a waiting state holds up to wait_seconds (contract maximum 45 seconds, HOLD_MAX_SECONDS); the server may hold less. Never assume a fixed hold length: pass next.args exactly as returned, and stop waiting at next.by. Without after_revision the read returns at once.

Success data

The text content opens with a briefing: one to three sentences for the user, then What to do: for the agent. Tell the user the first part in your own words and do what What to do says. One JSON line follows with these fields. Pass next.args unchanged to next.tool. Never show the JSON line, ids or codes to the user. Outputs may gain fields, so ignore ones you do not recognize.

The secret path is card. It carries one-time card details while the purchase is ready; never log, store or show them. Examples use synthetic values only.

Synthetic result

Example synthetic-completed-receipt (synthetic data, the MCP text content; JSON is formatted here for reading but arrives on one line):

The purchase of ₹2,499.00 at "Example Store" is complete. Order reference "SYNTHETIC-ORDER-0001" (from the merchant).

What to do: Tell the user it's done, with the order reference, then carry on with their task. If it fits the conversation, you may ask how it went and send their words with answer_purchase_question using the follow_up args below. This is optional.

{
  "situation": "done",
  "money": "charged",
  "purchase_id": "pur_5b1e9c7a3f2d5a8e9c0b1d2e3f4a5b6c",
  "checkout_by": "agent",
  "follow_up": {
    "tool": "answer_purchase_question",
    "args": {
      "purchase": "pur_5b1e9c7a3f2d5a8e9c0b1d2e3f4a5b6c",
      "question": "feedback-pur_5b1e9c7a3f2d5a8e9c0b1d2e3f4a5b6c",
      "type": "feedback"
    }
  }
}

Errors

A failure sets isError to true and changes nothing. The briefing says what happened and what to do; retry and fix in the JSON line say whether and how to retry. Branch on those, not on a code: these common codes appear only in _meta["money.envoy/support"], for support. See all error codes for the complete contract list.

Downloads

OpenAPI · MCP catalog · Synthetic examples · Schemas