Pay from a saved-card vault
Use the one-time card details as usual, or ask Envoy to save the card to the user's Instinct vault and pay from there.
A ready one-time card purchase can be paid two ways. By default the agent reads the card details and pays once at the merchant checkout. For an eligible Instinct purchase, the agent can instead ask Envoy to save the card to the user's Instinct vault and pay from the vault. The agent chooses; nothing is saved unless it asks.
Support revision: envoy@2026-10. Last updated: 28 October 2026.
All values below are synthetic.
The two ways to pay
| Way | What the agent does | When to use it |
|---|---|---|
| Card details (default) | Reads the card on the ready reply of get_purchase_status and pays once at the merchant checkout, as in Make a purchase, start to finish. | Always available on a ready card purchase. |
| Saved-card vault | Uses this purchase's named entry. If Envoy offers a save, the agent may request it first. | Use an existing named entry, or request the offered save when you would rather not handle card details. |
The offer appears only for eligible Instinct purchases. It never replaces the card details: the ready reply carries them either way.
How Envoy knows the purchase is Instinct's
Over MCP or the API, Envoy knows the agent from its connection. On Envoy's agent pages (https://agent.envoy.money/agent-interactions) every agent signs in the same way, so the agent names itself through the entry URL its guide gives it. Instinct opens the pages at https://agent.envoy.money/agent-interactions/hosts/instinct; the pages keep the name for the session. Without it, the pages work as usual but the vault offer does not appear. On those pages the offer is a Save card to Instinct vault button on the ready purchase, which sends the same submit_answer call.
Use only this purchase's saved card
Use only the vault entry named in the ready briefing. Never use another saved card, the user's Elixir card, or the merchant's selected default card.
If this purchase's entry is missing and no payment was attempted, use the card details Envoy delivered for this purchase. If you cannot identify its entry, do not use the vault. A missing entry is not permission to repeat a payment you already attempted. Reconcile an uncertain outcome first.
Find the offer
When a vault save is available, the ready reply carries one entry in follow_ups:
tool:submit_answerargs: thepurchase, withtypeanswer,questionvault_saveandanswersavewhy: "Optional. If you would rather not handle the card details, ask Envoy to save this card to the user's Instinct vault and pay from the vault. A sign-in code may be needed."
Over MCP the briefing says the same thing in its What to do line, and the slim agent data carries the call as follow_up (tool and args).
Ignoring the offer changes nothing. Pay with the card details and call report_checkout_result as usual.
Ask for the save
Call submit_answer once with exactly the args from the offer and a new idempotency_key. The answer must be save.
| Reply | What it means | What you do |
|---|---|---|
The purchase reads processing | Envoy is saving the card. The card details are held while it runs. | Follow next: keep reading get_purchase_status. If next says stop, the save is taking longer than expected. Tell the user, and check the purchase again shortly. Don't pay again, because the card is held until the save finishes. |
The purchase asks an otp question (needs_answer) | The vault needs the user's Instinct sign-in code. See below. | Show purchase.question.prompt exactly, then send the user's reply once with submit_answer and next.args. |
The purchase waits for the user (waiting_for_user, task enter_otp) | The vault needs a sign-in code. See below. | Tell the user to enter it in the Envoy app; follow next. |
The purchase reads ready | The save no longer holds the card. | Use this purchase's named vault entry if present, or its delivered card details before any payment attempt. |
NOT_ALLOWED | A vault save is not available for this purchase. | Pay with the card details. Don't ask again. |
UNAVAILABLE (retryable) | Envoy could not start the save just now. | Wait the seconds the reply gives, then ask again, or pay with the card details. |
INVALID_INPUT | The answer was not save. | Send the offer's args unchanged. |
Asking twice is harmless: a save already running or finished answers with where it stands.
If a sign-in code is needed
Signing in to the vault may need a code that Instinct sends the user. Follow the state and question in Envoy's reply:
needs_answerwith anotpquestion: Showpurchase.question.promptto the user word for word. Ask only for that open question's Instinct vault sign-in code. Send the user's exact reply once throughsubmit_answerwithnext.argsand a newidempotency_key. Never guess, repeat, log or keep the code. If the question changes, read status again; do not send the old answer to a new question.waiting_for_userwith taskenter_otp: Tell the user to enter the code in the Envoy app. Never ask for it in chat or send it throughsubmit_answer. Follownextto check progress.
The vault sign-in code is separate from a bank or payment OTP. For the one-time card, the bank OTP is its checkout_code: enter it once on the bank page, including when the card is saved in the vault. The bank sends the user no code for it. Never ask the user for a bank OTP or send one to an Envoy tool.
When the save finishes
- Saved. The purchase reads
readyagain. Pay from the user's Instinct vault. Use only the entry named in the ready briefing. Its format isenvoy-<creation date in India>-<first eight purchase hex digits>, for exampleenvoy-2026-10-28-5b1e9c7a. Then callreport_checkout_resultas usual. - The save failed. The purchase reads
readyagain with the card details, and the offer is shown again. Itswhysays the last save didn't finish, with a short reason when Envoy knows it, for example that Instinct needs the user to sign in again, or that the sign-in code wasn't entered in time. Pay with the card details, or ask for the save once more.
After checkout, call report_checkout_result with paid only when the merchant confirms payment. Otherwise report failed with a reason; use other when the outcome is unclear. Envoy removes the vault entry after the card is used or blocked.