Perform an operation advertised by a vault item
Retrieve the item first and invoke only an operation listed in
available_operations, following its natural-language description.
Availability is rechecked at execution time; unavailable operations return 409.
Authorization and preparation may call an external provider and return updated state.
Link cards advertise authorize; pass browser_id and page_url from the final
checkout page so Kernel can inspect the checkout. Eligible unused
AgentCard cards advertise prepare_checkout, which requires checkout context
and obtains device approval before native Square Pay. Keep the returned
approval page open, poll until ready_to_submit, then submit before
preparation.expires_at. Unused preparations expire automatically and cannot
be reused. If spend-request creation is rejected with a non-retryable
provider error, the card item is deleted and the provider’s error code and
message are returned. Rate limits return HTTP 429 and retain the card item;
stop, back off, and retry the same authorize operation.
Ready Kernel cards advertise fill. Fill delivers card details for a few minutes; submit checkout promptly after filling. A repeated fill is safe.
Fill returns a value-free execution result. Validation failures before
writing return 400 (invalid request or targets), 403 (access or destination
denied), 404 (resource not found), or 409 (item or browser not ready).
Once writing starts, known partial failures and indeterminate field outcomes
return 200 with status failed or unknown. Fill never submits the page, so
it is safe to retry after a failure, an unknown outcome, or a transport error.
Connected Kernel wallets may advertise add_payment_method, which returns a single-use hosted card_enrollment link for a card, or with enrollment server a single-use card_ingest URL for the card’s issuer, and remove_payment_method, which removes one card without affecting the others. Both operations require vaults:write in addition to vaults:use on the vault for scoped API keys, and return 403 without both permissions.
Authorizations
Body
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
- Option 12
- Option 13
- Option 14
- Option 15
- Option 16
- Option 17
- Option 18
- Option 19
- Option 20
Authorize a Link, Kernel or Shop Pay card using its existing purchase specification. Use only after explicit user approval and when the item advertises authorize; follow the advertised operation's description. For a Link or Shop Pay card, pass browser_id and page_url together while the browser is on the final checkout page: Kernel confirms that checkout is open, sends it to the provider as the merchant, and limits fill to that checkout's origin in any browser with this vault attached. For Link it also chooses how the credential is delivered. Omitting both issues a virtual card that fills any page on the merchant origin. Once approval has been requested, browser_id and page_url are ignored and authorize only re-checks the request. Browser and checkout inspection errors occur before any provider request and can be retried once the browser is on the checkout page. Kernel cards accept browser_id but not page_url: browser_id names the browser that will pay, which must have this vault attached. For cards whose cardholder enters a fresh CVC on an encrypting card form, Kernel tries to route that browser through the card vault's proxy as soon as the CVC is entered, so authorize before the browser opens the payment step and retrieve the card until fill is advertised before opening it. Other cards, and any card whose routing fails, are routed at their first fill.
Response
Authorization or preparation completed or resumed, or fill execution outcomes returned
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
- Option 11
- Option 12
Authorization and preparation return the existing item shape. Fill and passkey operations return value-free results; WebMCP invocation returns the tool's output. None persist transient outcomes on the item. Payment-method operations return the affected wallet payment method. link_balance_setup returns the Link balance setup URL.