start_purchase

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

Start a purchase when the user asks to pay with Envoy or has chosen Envoy as the default for this checkout. Never ask for card details. Retry with the same key; a new key is a new purchase. Send the full cart exactly as the user asked, the delivery address, each item's image and the merchant_logo: the user sees them on the approval screen. Only items bought; no gifts. Never split a cart or lower a total. Envoy decides who checks out: read checkout_by in each reply. agent: you get a one-time card. envoy: Envoy checks out; never open the payment step. Envoy never shares a browser live-view link.

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": "start_purchase",
    "arguments": {
      "idempotency_key": "synthetic-intent-0001",
      "merchant_url": "https://shop.example.test",
      "merchant_logo": "https://shop.example.test/logo.png",
      "total": "2499.00",
      "items": [
        {
          "name": "Headphones",
          "image": "https://shop.example.test/headphones.jpg"
        }
      ],
      "user_request": "Buy the headphones"
    }
  }
}

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.

Synthetic result

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

What to do: Tell the user the message below once; they can't see tool results. They need to do it within about 15 minutes. Call get_purchase_status with the next args from the data below: it waits for as long as the server holds for a change. Follow the returned next action until the situation changes or Envoy says to stop. get_purchase_status moves on by itself as soon as the user finishes in the Envoy app; the user doesn't need to tell you. Envoy will give you a one-time card to enter at checkout. The total the user approves, ₹2,499.00, is a hard cap: the card can't be charged more. If the merchant total is higher, don't pay.

Approve this purchase in the Envoy app. (₹2,499.00 at "Example Store") Your assistant carries on by itself once you approve.

{
  "situation": "waiting_for_user",
  "money": "not_charged",
  "purchase_id": "pur_5b1e9c7a3f2d5a8e9c0b1d2e3f4a5b6c",
  "checkout_by": "agent",
  "next": {
    "tool": "get_purchase_status",
    "args": {
      "purchase": "pur_5b1e9c7a3f2d5a8e9c0b1d2e3f4a5b6c",
      "after_revision": 1,
      "wait_seconds": 45
    }
  }
}

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