Wallet Service

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. 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 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

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. 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:

{
  "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. 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.

Wallet tool reference

Parameters, scopes, return fields, and recovery behavior.

Continue with Browser Pay

Obtain a credential, submit payment, and report the result.

Get Started

Integration

Agent Solutions

Configure & Launch

Guides

Finance

Understand the three layers

Passkeys and purchase authorization

Read the wallet

Select or manage a card

Create a spending authorization

Read, update, or cancel an authorization

Registration and risk settings

Wallet tool reference

Continue with Browser Pay

​Understand the three layers

​Passkeys and purchase authorization

​Read the wallet

​Select or manage a card

​Create a spending authorization

​Read, update, or cancel an authorization

​Registration and risk settings

Wallet tool reference

Continue with Browser Pay

Understand the three layers

Passkeys and purchase authorization

Read the wallet

Select or manage a card

Create a spending authorization

Read, update, or cancel an authorization

Registration and risk settings