Complete checkout after approval

After the user completes the returned approval or payment task, read checkout_by in the latest status. Follow the matching route below. An agent payment is complete only when Envoy confirms it from money evidence.

Support revision: envoy@2026-10. Last updated: 3 November 2026.

This guide assumes a purchase already exists. Start with the purchase walkthrough if you need to create one. The examples below use synthetic values; they are not a test mode.

Agent checkout

When checkout_by is agent, the agent completes the merchant checkout.

1. Wait until the state is ready. The authorized get_purchase_status reply releases payment details. Check kind: use the one-time card for card, or follow voucher redemption instructions for gift_card.
2. Pay once at the merchant's checkout. Enter the delivery details at the merchant.
3. Call report_checkout_result once, right after you pay.
4. Follow next until Envoy confirms the outcome.

Envoy checkout

When checkout_by is envoy, Envoy checks out in its own browser.

• Totals above ₹10,000, up to ₹1,00,000, use this route. Envoy can also choose it for smaller totals.
• Envoy needs address or address_id in start_purchase to deliver the order.
• Envoy releases no payment details while it checks out. Do not open the merchant payment step. A gift-card checkout can return to an agent route if Envoy cannot operate it; follow the latest reply.
• report_checkout_result is refused, so do not call it.
• If Envoy needs something only the user can give, the state is needs_answer. See Answer Envoy's question.
• If the bank asks for an OTP, the user enters it in the Envoy app (user task enter_otp). Never ask the user for it in chat.
• Follow the returned status calls until completion, failure or a stop instruction. For a gift-card pay_link task, the user pays the returned link.

Answer Envoy's question

When Envoy checks out and needs something only the user can give, the state is needs_answer. purchase.question then holds the id, the kind and the prompt.

1. Show the user purchase.question.prompt word for word. Wait for the reply.
2. Call submit_answer with next.args unchanged. Add the user's exact words as answer and a new idempotency_key.
3. Keep following next.

• Never answer for the user, and never guess.
• Kind otp is a sign-in code for the merchant or an Instinct vault save, as the exact prompt states. Send the user's reply once for that open question. Never repeat or keep it.
• Envoy never asks for a merchant password through chat. Do not ask the user for one. When the merchant requires a password, the reply stops and says so; if the user agrees, call cancel_purchase.
• A payment or bank code never appears in purchase.question. The user enters that code in the Envoy app.
• If the reply is STATE_CONFLICT, Envoy has moved on to a newer question. Call get_purchase_status and read the new question. Never send the old answer to the new question.

Pay once when the state is ready

An agent checkout in state ready can release a one-time card or paid gift-card voucher. Read the authorized get_purchase_status result (data.payment_details over HTTP, card over MCP). Check its kind before use. For gift_card, follow the voucher procedure. The card instructions below apply to kind: card. Use it for this purchase's merchant checkout only. If the handout includes checkout_attempt_id, keep that exact value for the report; never replace it with an ID from a later handout. The get_purchase_status reference defines the reply.

A synthetic HTTP reply excerpt shows the route and next call without exposing card fields:

{"ok":true,"tool":"get_purchase_status","purchase":{"state":"ready","checkout_by":"agent"},"next":{"action":"checkout","tool":"report_checkout_result"}}

• Pay once, at or below amount_limit. Never copy the card into chat, logs, memory or files.
• The returned checkout_code is the matching card's OTP: when the bank page asks for a code or OTP, enter it once. If the bank rejects it, do not retry. The bank sends the user no code for this card.
• Never ask the user for a payment or bank OTP in chat, and never send one to an Envoy tool. If the bank rejects checkout_code, report failed with failure_reason: otp_failed.
• When checkout_code_expires_at is supplied and the code expires, read get_purchase_status for the same purchase before payment. A new code does not extend the card's spending access.
• If checkout fails, report failed with the closest failure_reason. Follow the returned next; a browser retry may be available except after price_changed or out_of_stock. See Retry a failed card checkout.
• If expires_at is present and you cannot pay before it, tell the user and stop. Do not request another card.
• If the merchant's total differs, do not pay. Call cancel_purchase and tell the user.

For some Instinct purchases, the ready reply offers an optional saved-card-vault step in follow_ups. Follow Pay from a saved-card vault only when the user wants that route.

A report stops use of the current handout. A failed report does not prove the issuer closed the card or refunded money. Envoy may reopen the same card with a new checkout code after reconciliation. Use it only when the latest status explicitly supplies a new ready handout. A disconnect ends disclosure. Read status before another action.

Show checkout progress

When the connected catalog offers report_checkout_step, you can report reached steps while you check out as the agent. Pass this purchase and copy checkout_attempt_id from its handout when present. Repeats are harmless. A step moves no money and returns no payment details; it does not replace report_checkout_result. Continue using the authorized details you already hold. Do not read ready status again just because you reported a step.

Report the result

On agent checkout, after the checkout attempt, call report_checkout_result once with one of two outcomes:

{
  "purchase": "pur_5b1e9c7a3f2d5a8e9c0b1d2e3f4a5b6c",
  "checkout_attempt_id": "11111111-2222-4333-8444-555555555555",
  "outcome": "paid",
  "merchant_order_ref": "SYNTHETIC-ORDER-0001",
  "amount_paid": "2499.00"
}

{
  "name": "report_checkout_result",
  "arguments": {
    "purchase": "pur_5b1e9c7a3f2d5a8e9c0b1d2e3f4a5b6c",
    "checkout_attempt_id": "11111111-2222-4333-8444-555555555555",
    "outcome": "paid",
    "merchant_order_ref": "SYNTHETIC-ORDER-0001"
  }
}

failure_reason is one of card_not_accepted, card_declined, otp_failed, price_changed, out_of_stock, site_error, site_blocked or other. merchant_order_ref is the reference the merchant showed, up to 128 printable characters.

Report paid only when the merchant confirmed payment. If you cannot tell, report failed with failure_reason: other. Include the exact checkout_attempt_id from the card handout when supplied; omit it only for a legacy handout. The first report for that attempt wins. Without an attempt ID, the first report for the purchase wins. A report records what the agent saw; it does not settle the purchase or close the card. Envoy refuses cancel_purchase after a report until it reopens the card (ready again). Follow next; another agent payment requires the latest reply to authorize it with a new ready handout. A replacement purchase also requires the previous card to be terminal and money settled.

If the report's reply is lost or ambiguous, recover before you do anything else:

• Keep the same purchase_id.
• After a lost reply, a timeout or retry check_status_first, call get_purchase_status before anything else.
• Never issue a new payment for an unknown outcome.
• Follow retry and next.
• Cancelling is not a refund, and it does not prove the card is blocked.

See Recover a purchase.

Retry a failed card checkout on Envoy's browser

After a failed report, follow next before offering a retry to the user. Envoy does not offer this retry for price_changed or out_of_stock. A linked replacement requires closure and refund before it pays with the user's own card. This differs from a fresh ready handout for the same card after reconciliation. The report itself never authorizes another merchant payment. Envoy enforces the required closure and refund before a linked replacement can pay.

From the connection that started the purchase, call start_purchase with retry_of set to the reported purchase_id or its original idempotency_key. Use a new idempotency_key and the same merchant_url, items, total and user_request. Envoy creates a linked purchase that pays only after the original card is stopped and refunded. A replacement needs the user's approval in the Envoy app.

On the retry route, Envoy performs checkout in its browser. The user may need to sign in to the merchant there. Never pay with the old card handout; for agent checkout, another payment requires a new ready handout. Never pay while a purchase is verifying. A failed report does not prove the old card closed. After a report, Envoy refuses cancel_purchase and reconciles the purchase, unless it reopens the card.

Confirm the outcome

After a report, follow the returned next and read the latest status. If the purchase is verifying (confirming over MCP), money is unsettled: keep reading status and never pay again while it remains there. A failed report may permit another attempt after reconciliation, but only a new ready handout authorizes another agent checkout. If the read stops while verifying, tell the user the payment is not confirmed yet.

purchase.money.status is a separate fact from the merchant order: not_started, unknown, debited, refund_pending, refunded or merchant_collects. The last value means the merchant collects payment on delivery; nothing was charged to the Elixir card. A debit does not prove the merchant order, and an order reference does not prove settlement.

When the state is completed, purchase.follow_up can ask for feedback, and the reply's follow_ups carries the submit_answer call with type feedback. It is optional. Ask the user only if it fits the conversation. Send the user's words as answer, with a rating from 1 to 5 if the user gives one. The reply carries data.receipt. Skipping it changes nothing.

Stop a purchase

Before any checkout report, call cancel_purchase with the purchase when the user changes their mind or the merchant total differs. You may add a reason; Envoy does not store it. After a report, Envoy refuses cancellation and the purchase must reconcile, unless Envoy reopens the card: once it reads ready again, cancel_purchase works.

• Cancelling is not proof of a refund, and not proof the card is blocked. Follow the returned purchase and next.
• If Envoy has not yet sent the purchase on for funding, a cancel ends it cancelled. Once sent, it reads verifying until money is settled, because money may already have moved.
• A card you already used at the merchant stays used. Reconcile first; see Recover a purchase.
• Disconnecting the agent does not cancel an open purchase. The user can still approve or cancel it in the Envoy app.