|
| 1 | +# Vault payments |
| 2 | + |
| 3 | +The vault tools prepare and observe payment credentials. They do **not** submit |
| 4 | +merchant payments, expose real card values, or complete provider approval actions. |
| 5 | +They use the same vault API as the Kernel CLI. |
| 6 | + |
| 7 | +## Tools and scope |
| 8 | + |
| 9 | +| Tool | Actions | |
| 10 | +| ---------------------- | ------------------------------------------- | |
| 11 | +| `manage_vaults` | `create`, `list`, `get`, `delete` | |
| 12 | +| `manage_vault_wallets` | `create`, `payment_methods` | |
| 13 | +| `manage_vault_cards` | `create`, `update` | |
| 14 | +| `manage_vault_items` | `list`, `get`, `invoke`, `events`, `delete` | |
| 15 | + |
| 16 | +Every tool accepts an optional `project` name or ID. Vaults are project-owned; |
| 17 | +omitting `project` uses the API's effective default project, **not** all projects. |
| 18 | +Project-scoped connections cannot switch projects. Use `get_connection_context` |
| 19 | +to inspect the connection's scope. |
| 20 | + |
| 21 | +`vault` accepts an ID or immutable name. `key` is an immutable item key within that |
| 22 | +vault, not the item ID. Vault names, item keys, and project ownership cannot be renamed. |
| 23 | + |
| 24 | +Wallet/card writes take a `provider` (`link` or `agentcard`) and a JSON `spec` |
| 25 | +**object**, not a string or a `{type, spec}` envelope. The tool injects `provider`; |
| 26 | +if present in `spec`, it must match. Tool schemas describe the provider-specific |
| 27 | +fields and reject unknown fields, including nested ones. No defaults or currency |
| 28 | +normalization are applied. Amounts are integer minor currency units. All integer |
| 29 | +inputs, including `expires_at`, must fit JavaScript's safe integer range; unsafe |
| 30 | +numbers are rejected, not silently rounded. The API enforces provider/state rules. |
| 31 | + |
| 32 | +These capabilities use the existing MCP authentication and deployment. To expose |
| 33 | +only payment tools on a self-hosted server, set: |
| 34 | + |
| 35 | +```sh |
| 36 | +KERNEL_MCP_ENABLED_TOOLSETS=vaults |
| 37 | +``` |
| 38 | + |
| 39 | +For browser checkout automation too, use `vaults browsers playwright computer`. |
| 40 | +To hide the payment tools, set `KERNEL_MCP_DISABLED_TOOLSETS=vaults`. |
| 41 | +This filters discovery; API authorization still enforces resource access. |
| 42 | + |
| 43 | +## Link flow |
| 44 | + |
| 45 | +1. Create or retrieve a vault with `manage_vaults`: |
| 46 | + |
| 47 | + ```json |
| 48 | + { "action": "create", "name": "checkout" } |
| 49 | + ``` |
| 50 | + |
| 51 | +2. Connect a wallet with `manage_vault_wallets`: |
| 52 | + |
| 53 | + ```json |
| 54 | + { |
| 55 | + "action": "create", |
| 56 | + "vault": "checkout", |
| 57 | + "key": "wallet-1", |
| 58 | + "provider": "link", |
| 59 | + "spec": { |
| 60 | + "authorization": { |
| 61 | + "method": "oauth", |
| 62 | + "client": { "type": "kernel_managed" } |
| 63 | + } |
| 64 | + } |
| 65 | + } |
| 66 | + ``` |
| 67 | + |
| 68 | + Give the returned `item.action.url` to the user to complete with the provider. |
| 69 | + Do not ask for card details or OAuth codes/tokens in chat. Observe the wallet |
| 70 | + with `manage_vault_items`, `action: "get"`, the same vault/key, and `wait: 30`. |
| 71 | + |
| 72 | +3. Once connected, call `manage_vault_wallets` with `action: "payment_methods"` |
| 73 | + and the same vault/key. Explicitly select a returned method ID with the user; |
| 74 | + do not automatically choose the default. Capabilities are advisory: absent |
| 75 | + means unknown, not ineligible. |
| 76 | + |
| 77 | +4. Create the purchase request with `manage_vault_cards`, replacing |
| 78 | + `pm_selected` with the selected returned ID: |
| 79 | + |
| 80 | + ```json |
| 81 | + { |
| 82 | + "action": "create", |
| 83 | + "vault": "checkout", |
| 84 | + "key": "order-1", |
| 85 | + "provider": "link", |
| 86 | + "spec": { |
| 87 | + "wallet": "wallet-1", |
| 88 | + "payment_method_id": "pm_selected", |
| 89 | + "amount": 1234, |
| 90 | + "currency": "usd", |
| 91 | + "merchant_name": "Example Shop", |
| 92 | + "merchant_url": "https://shop.example", |
| 93 | + "context": "Purchase the selected office supplies from Example Shop for the approved order, with a total spending limit of 1234 minor currency units." |
| 94 | + } |
| 95 | + } |
| 96 | + ``` |
| 97 | + |
| 98 | + Link also supports `line_items`, `totals`, `metadata`, and `expires_at`. |
| 99 | + Creating or updating the card does **not** implicitly authorize it. |
| 100 | + |
| 101 | +5. Read `available_operations` with `manage_vault_items`, `action: "get"`. |
| 102 | + Read the operation description and obtain explicit user approval before |
| 103 | + invoking an advertised operation: |
| 104 | + |
| 105 | + ```json |
| 106 | + { |
| 107 | + "action": "invoke", |
| 108 | + "vault": "checkout", |
| 109 | + "key": "order-1", |
| 110 | + "operation": "authorize" |
| 111 | + } |
| 112 | + ``` |
| 113 | + |
| 114 | + The tool fetches the item again and submits only a currently advertised |
| 115 | + operation. The current API accepts only `{"type":"authorize"}`; there are no |
| 116 | + operation parameters. New parameterless operation names can be forwarded when |
| 117 | + the API advertises them. Follow any returned provider action and observe state. |
| 118 | + OAuth, enrollment, MFA, and approval actions are for the user, not operation names. |
| 119 | + |
| 120 | +6. When ready, create a new browser with `manage_browsers`: |
| 121 | + |
| 122 | + ```json |
| 123 | + { |
| 124 | + "action": "create", |
| 125 | + "vaults": [{ "name": "checkout" }] |
| 126 | + } |
| 127 | + ``` |
| 128 | + |
| 129 | + Use only returned `item.state.aliases` through the browser tools in **that |
| 130 | + browser**, respecting returned permitted domains. Merchant checkout submission |
| 131 | + is a separate browser action and requires the user's authorization. |
| 132 | + |
| 133 | +## AgentCard flow |
| 134 | + |
| 135 | +Use a separate vault or different immutable item keys. Create the vault as above, |
| 136 | +then connect a wallet with `manage_vault_wallets`: |
| 137 | + |
| 138 | +```json |
| 139 | +{ |
| 140 | + "action": "create", |
| 141 | + "vault": "checkout", |
| 142 | + "key": "agentcard-wallet", |
| 143 | + "provider": "agentcard", |
| 144 | + "spec": {} |
| 145 | +} |
| 146 | +``` |
| 147 | + |
| 148 | +Complete the returned enrollment action. Alternatively, `spec.user_id` may refer |
| 149 | +to a user already enrolled in this organization. Once connected, configure a card |
| 150 | +with `manage_vault_cards`: |
| 151 | + |
| 152 | +```json |
| 153 | +{ |
| 154 | + "action": "create", |
| 155 | + "vault": "checkout", |
| 156 | + "key": "agentcard-order", |
| 157 | + "provider": "agentcard", |
| 158 | + "spec": { |
| 159 | + "wallet": "agentcard-wallet", |
| 160 | + "merchant": "Example Shop", |
| 161 | + "amount": 1234, |
| 162 | + "currency": "usd" |
| 163 | + } |
| 164 | +} |
| 165 | +``` |
| 166 | + |
| 167 | +AgentCard uses `merchant`, not Link's `merchant_name`. Optionally inspect wallet |
| 168 | +payment methods and provide a returned `card_id`; otherwise the cardholder selects |
| 169 | +one at approval. AgentCard currently does not advertise `authorize`: authorization |
| 170 | +happens at checkout. Attach the vault to a new browser and use returned aliases. |
| 171 | +Observe the card for its checkout authorization and any approval URL for the user. |
| 172 | +A reusable card remaining `ready` does not establish that the last payment succeeded. |
| 173 | + |
| 174 | +## Observation, updates, and safety |
| 175 | + |
| 176 | +- Single-item responses are JSON text containing `{item, guidance}`. They preserve |
| 177 | + public state, non-secret aliases, masks, safe action/approval URLs, advertised |
| 178 | + operations/expansions, and payment outcomes. Unknown provider fields, opaque |
| 179 | + event data, free-form metadata, and URLs carrying OAuth codes/tokens are omitted. |
| 180 | + There is no raw-output or raw-card tool. |
| 181 | +- Vault lists return `{items, has_more, next_offset}`. Item lists return `{items}`. |
| 182 | + `get` with `expand: ["payment_methods"]` is equivalent to the wallet |
| 183 | + `payment_methods` action. An unavailable expansion returns an API error. |
| 184 | +- `get` and `events` accept `wait: 0..60`. Each call is one bounded observation, |
| 185 | + not a background polling loop or readiness guarantee. The SDK timeout is the |
| 186 | + wait plus 30 seconds; configure the MCP client's timeout accordingly, or use |
| 187 | + shorter waits. Request cancellation is propagated to the SDK. |
| 188 | +- `events` accepts `after` and returns `{events, next_after, guidance}`. Pass |
| 189 | + `next_after` on the next call for the same vault/key. An empty result preserves |
| 190 | + the input cursor (or returns `null` without one). |
| 191 | +- **Ready does not mean paid.** Inspect state and immutable events for outcomes. |
| 192 | + No vault request is automatically retried. After a failed, timed-out, rejected, |
| 193 | + or indeterminate payment, inspect state/events; do not replay checkout, invoke |
| 194 | + again, or reconfigure a card to retry it. |
| 195 | +- Card `update` replaces the **entire spec**; omitted optional fields are removed. |
| 196 | + The API decides when a card can be reconfigured. |
| 197 | +- Browser attachments accept at most 20 references, each containing exactly one |
| 198 | + `id` or `name`. They are creation-only and unavailable for browser pools. You |
| 199 | + cannot add vaults to an existing browser. Vault-bound browser creation also |
| 200 | + disables automatic SDK retries. |
| 201 | +- Provider-assigned permitted domains are not configurable through these tools. |
| 202 | +- Vault/item deletion invalidates the affected credentials. Confirm with the user |
| 203 | + first. Any HTTP 404 returns `deleted_or_not_found`, including a missing project; |
| 204 | + other errors fail. Non-delete 404s remain errors. |
| 205 | +- The existing analytics filter omits tool inputs, outputs, and error messages; |
| 206 | + do not add payment payloads or action URLs to application logs. |
0 commit comments