> ## Documentation Index > Fetch the complete documentation index at: https://docs.clinkbill.com/llms.txt > Use this file to discover all available pages before exploring further. # Wallet Service > Read a user’s wallet, manage payment cards, and create spending authorizations. Wallet Service connects an agent to a user's Clink payment cards and spending authorizations. Independent agents and cloud platforms use the same MCP tools after [connecting with OAuth](/guides/agent/mcp_integration). Use these tools when the user asks about their wallet, wants to manage a card, or wants to set up a spending authorization. **They are not a checklist to run before every payment.** For a [Browser Pay](/guides/agent/browser_pay) purchase, `get_credential` handles authorization matching and setup for the checkout total; do not first call `list_spendable_instructions` or `create_purchase_instruction`. ## Understand the three layers | Layer | What it permits | How it is established | | :- | :- | :- | | OAuth connection | The agent can call tools for a particular user, within granted scopes. | The user connects Clink in their agent host or platform. | | Payment card | Identifies which wallet card can fund a purchase. | The user adds a card and, when required, completes Agent Pay registration. | | Purchase instruction | Records the spending purpose and limits the user has approved. It contains one or more mandates. | The user activates the instruction on the Clink authorization page. | Connecting a wallet does not authorize every purchase. Creating an instruction also does not activate it: only an `ACTIVE` instruction with an applicable mandate can authorize spending. ## Passkeys and purchase authorization
Visa
The current Visa payment flow uses passkeys to register a card for Agent Pay and confirm a purchase authorization. During initial setup, the user can complete registration and approval in one flow. Registering a card alone does not approve a purchase. This passkey verification applies to payment authorization; the OAuth connection still only grants tool access. The user verifies on their own device with a fingerprint, face recognition, or device PIN. Passkeys provide phishing-resistant authentication. When biometrics are used, biometric data is processed on the device and is not sent to remote servers. See [FIDO's passkey explanation](https://fidoalliance.org/passkeys/). ```mermaid theme={null} %%{init: {"theme":"base","themeVariables":{"fontFamily":"inherit","fontSize":"14px","primaryColor":"#F7F7F7","primaryTextColor":"#161616","primaryBorderColor":"#E7E7E7","lineColor":"#71717A","edgeLabelBackground":"#FFFFFF"},"flowchart":{"nodeSpacing":40,"rankSpacing":38,"padding":14,"diagramPadding":12}}}%% flowchart TD U["User
Passkey approval"] --> I["Active authorization
Purpose and spending limits"] I --> C["Clink
Check limits and issue credential"] A["Agent
Purchase request"] --> C classDef emphasis fill:#F8E1CC,stroke:#F8E1CC,color:#161616 class C emphasis ``` Before issuing a payment credential, Clink checks whether the purchase meets the active authorization's conditions, including the card, amount, currency, and validity period. **When a valid authorization covers the purchase, a new passkey verification is not required for every payment.** When user verification is required, the Agent or platform presents the returned action link for the user to complete on their own device. Read the Operation and authorization status before continuing with payment. The Agent cannot complete the passkey approval on the user's behalf. ## Read the wallet Call `get_account_state` with `{}` when the user asks which cards are available, which is the default, or whether a named card can be used. Read again for each new wallet question: cards and defaults can change outside the conversation. The response contains `paymentMethods`, `defaultPaymentInstrumentId`, and `ready`. Show cards by `cardScheme` and `cardLastFour`; use `paymentInstrumentId` in tool calls. | Field | Meaning | | :- | :- | | `ready` | A usable payment method exists. It does not prove that the default card supports Browser Pay or that a purchase is authorized. | | `agent_pay_support` | The card is eligible for Agent Pay according to the current wallet response. Do not infer availability from the card brand alone. | | `strongAuthRegistered` | The card has completed Agent Pay registration. | | `strongAuthReady`, `authProtocol` | Authentication information for the current device. These do not replace `strongAuthRegistered`. | | `blockedReason: "NO_PAYMENT_METHOD"` | No usable payment method is available. Offer card setup. | ## Select or manage a card | User intent | Action | | :- | :- | | “Use my card ending in 4242 for this purchase.” | Read the wallet, identify exactly one card, then pass its `paymentInstrumentId` to `get_credential`. Keep the wallet default unchanged. | | “Make that card my default.” | Read the wallet, identify the card, then call `set_default_card`. Report the returned `account` state. | | “Add, replace, or remove a card.” | Call `start_payment_method_action` with `action: "add"`, `"replace"`, or `"remove"`. | | “Let me choose my default card myself.” | Call `start_payment_method_action` with `action: "set-default"`. | If a description matches several cards, ask the user which card they mean. Do not choose a new default automatically. Changing the default requires `wallet:setup` as well as `wallet:read`; if direct modification is unavailable, provide the user-managed `set-default` flow. `start_payment_method_action` returns an Operation with a `REDIRECT_USER` action. Give the URL to the user to open on their own device. After they complete it, read the same Operation with `get_operation`, then refresh `get_account_state`. Merely opening or returning from the page does not prove completion. ## Create a spending authorization Use `create_purchase_instruction` when the user explicitly wants to establish an authorization, such as a bounded budget or recurring spending. Preserve their purpose, amount, currency, and validity. Read the connected MCP server's current rules before creating it. The user's intent determines which flow to use: | User request | Integration flow | | :- | :- | | “Buy this office supply for no more than USD 25.00.” | Call `get_credential` with the final checkout amount and follow its authorization flow. Do not create a separate authorization first. | | “Set up a monthly authorization for future office supply purchases.” | Confirm the purpose, limit, currency, frequency, and validity with the user, then create a recurring authorization for the user to activate. Each purchase must still meet the active authorization's conditions. | For a separate one-time authorization, such as “Approve up to USD 25.00 for my next office supplies purchase,” use the example below. For the monthly scenario, use the recurring fields described after the authorization flow: ```json theme={null} { "requestId": "wallet-budget-example-001", "title": "Office supplies budget", "isRecurring": false, "mandates": [ { "description": "Purchase office supplies within the approved budget", "amountLimit": "25.00", "currencyCode": "USD" } ] } ``` Generate a unique `requestId` for each new user intent. After a timeout or setup step, reuse that ID **and the exact original arguments**. Do not create a second authorization just because the first request is still waiting. Instruction limits use decimal strings in **major currency units**: `"25.00"` means USD 25.00. Browser Pay's `get_credential.amount` uses **minor units**: `2500` means USD 25.00. The user first confirms the purpose and spending limit, then completes any needed card setup and Passkey authorization on Clink's authorization page. Afterward, read the same `operationId` and verify the same `instructionId`. ```mermaid theme={null} %%{init: {"theme":"base","themeVariables":{"fontFamily":"inherit","actorBkg":"#F7F7F7","actorBorder":"#E7E7E7","actorTextColor":"#161616","actorLineColor":"#E7E7E7","signalColor":"#71717A","signalTextColor":"#3F3F46","noteBkgColor":"#F8E1CC","noteBorderColor":"#F8E1CC","noteTextColor":"#161616"},"sequence":{"width":116,"height":44,"actorMargin":64,"diagramMarginX":12,"diagramMarginY":12,"messageMargin":28,"noteMargin":14,"boxMargin":12,"wrap":false,"mirrorActors":false,"actorFontSize":14,"messageFontSize":14,"noteFontSize":14}}}%% sequenceDiagram participant U as User participant A as Agent participant C as Clink U->>A: Approve scope A->>C: create_purchase_instruction C-->>A: Operation + user action A-->>U: Approval link Note over U: Use Passkey U->>C: Complete authorization A->>C: get_operation C-->>A: Updated state A->>C: get_instruction C-->>A: ACTIVE + card + mandates A-->>U: Ready to spend ``` Follow the returned `next_action`: setup and authorization can require more than one user action. If the instruction is `PENDING` and has no bound card, keep the same instruction through card setup. `CREATED`, `PENDING`, a failed read, or the user's statement that they finished is not evidence of an active authorization. The returned `effectiveUntilTime` is the effective expiry. The service may apply an expiry limit. For recurring instructions, set `isRecurring: true` and a `recurringFrequency` of `WEEKLY`, `MONTHLY`, or `YEARLY` on every mandate; this authorizes spending within those limits and does not schedule purchases by itself. ## Read, update, or cancel an authorization * Use `list_spendable_instructions` to find active instructions for a card. Omit `paymentInstrumentId` to use the current default. An active result still needs to match the intended purpose, currency, limit, merchant or category, and validity. * Use `get_instruction` to read a specific instruction and verify activation or a later change. * Use `start_instruction_action` with `action: "sign"` and `instructionId` to obtain an activation link for an existing instruction. * Use `action: "update"` or `"cancel"` to open the user-managed instruction page. These actions take no instruction ID; the user chooses the instruction on that page. Read the relevant instruction afterward to verify the change. `start_instruction_action` returns `{ action, actor, url, ... }`, not an Operation. Its `actor` is `USER_DEVICE_ONLY`; present `url` to the user. ## Registration and risk settings For an explicit Agent Pay registration request, call `start_agent_pay_registration` with the selected `paymentInstrumentId`. Follow the returned Operation and verify `strongAuthRegistered: true` for that same card. Browser Pay and instruction creation handle their own setup flow, so do not run standalone registration before them. Read current risk settings with `get_risk_rules`. To change them, call `start_risk_rules_action` and give the returned URL to the user. Read `get_risk_rules` afterward for the actual values; an Operation's completion alone does not describe the settings. Parameters, scopes, return fields, and recovery behavior. Obtain a credential, submit payment, and report the result. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.