report_checkout_result

Only when checkout_by is agent: report paid only on merchant confirmation; if completion is unclear, report failed with failure_reason other.

POST https://api.envoy.money/tools/report_checkout_result

Only when checkout_by is agent: report paid only on merchant confirmation; if completion is unclear, report failed with failure_reason other. For other failures, choose the closest failure_reason. Include the exact checkout_attempt_id from the handout when supplied. A report is an observation, not settlement; Envoy refuses cancel_purchase afterward. Retry after failed only once money is settled and the prior card is terminal, and only with a new ready handout or accepted start_purchase retry_of. First report wins. Never pay while verifying.

Title	Service	Read only	Destructive	Idempotent	External sites
Report checkout result	purchase	false	true	true	false

Send a Central Auth bearer with agent scope. A key-bound connection also sends Envoy-Installation-Proof over this exact request. JSON bodies are limited to 64 KB; a larger body returns HTTP 413 with INVALID_INPUT.

Input

Field	Required	Type	Description and rules
`purchase`	Yes	`string`	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`	No	`string`	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`	Yes	`"paid" \| "failed"`	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.
`failure_reason`	No	`"card_not_accepted" \| "card_declined" \| "otp_failed" \| "price_changed" \| "out_of_stock" \| "site_error" \| "site_blocked" \| "other"`	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.
`merchant_order_ref`	No	`string`	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`	No	`string`	Amount the merchant charged. Rupees, up to 2 decimals; number also accepted, "₹" and thousands commas are stripped. maxLength 20; pattern `^[0-9]+(?:\.[0-9]{1,2})?$`

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

Synthetic request

{
  "purchase": "synthetic-intent-0001",
  "outcome": "failed",
  "failure_reason": "other"
}

Success data

Every reply uses the shared envelope: ok, the purchase, next, user_action and error. Follow next; outputs may gain fields, so ignore ones you do not recognize.

This tool declares no data payload: a success returns the purchase in purchase and what to do next in next.

Synthetic result

Example synthetic-unauthenticated (synthetic data):

{
  "ok": false,
  "contract": "envoy@2026-10",
  "tool": "report_checkout_result",
  "request_id": "req_synthetic",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736",
  "server_time": "2026-09-29T12:00:00Z",
  "replayed": false,
  "purchase": null,
  "data": null,
  "next": {
    "action": "reconnect",
    "tool": null,
    "args": null,
    "instruction": "Ask the user to reconnect Envoy, then retry this call.",
    "after_seconds": null,
    "by": null
  },
  "user_action": null,
  "follow_ups": [],
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Reconnect to Envoy.",
    "fields": [],
    "reason_code": null,
    "retryable": false,
    "retry_after_seconds": null
  }
}

Errors

A failure has ok: false, changes nothing, and carries error plus one next. Branch on error.code and next, not on the HTTP status. The contract declares every code below for every tool; which one a call returns depends on the request and the purchase state.

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.

Downloads

OpenAPI · MCP catalog · Synthetic examples · Schemas