Skip to main content
Stripe Link is Stripe’s payment wallet. With Link CLI, Stripe’s command-line tool, an agent can ask Stripe Link for a virtual card for one purchase. Link enforces its own limits and any required customer approval before issuing the card. Conto works with Link CLI so the agent asks Conto first. Conto checks the purchase against the owner’s rules. Only after Conto approves does Link CLI ask Stripe Link for a card, for exactly the approved amount at that store. If Conto does not approve, Stripe Link is never asked, so no card exists.

How it works

  1. At the payment step, once the final total is known, the agent’s code calls conto.checkout.getLinkCard().
  2. Conto checks the purchase against the agent’s rules and holds the amount against its limits. When a rule requires it, the owner approves in Conto first.
  3. After Conto approves, Stripe’s Link CLI on your machine asks Stripe Link for a card for that amount at that store. The person completes any approval Link requires through the supported Link flow.
  4. Your code gets the card and fills in the store’s card form. Keep the card out of any model prompt, tool result, or log.
  5. Right before paying, the agent calls confirm(). After paying, it reports the outcome.
Stripe Link sends the card to your machine. Conto does not receive the card number or security code. Conto stores only the Link request ID, so the owner can see which Link request paid.

Set up

Install Stripe’s Link CLI on the machine where your agent runs, and log in with the Link account that pays:
Complete any approval required by your Link flow, in the app or on the web. See Link’s own authorization for supported approval experiences. Nobody connects Link to Conto, and there is no Link setup in the Conto dashboard. You also need an agent and its standard SDK key, as for checkout checkpoints. The SDK uses the same hosted policy, approval, and spending services as checkout checkpoints before asking Link for the card. A shared budget that covers the agent counts the purchase. If it refuses, getLinkCard() and replaceLinkCard() fail with status 409 and a reasonCode before Stripe Link is asked for a card. Organization policies, per-agent limits, and configured approval workflows apply as described in managing several agents.

Get a card with the SDK

getLinkCard() takes the same purchase details as checkout.begin(), plus the wallet. The checkout method is always LINK. It waits for the owner when a rule requires approval, then for the person in Link. Two optional settings limit each wait, and both default to 10 minutes: ownerApprovalTimeoutMs and linkApprovalTimeoutMs. Pass signal to stop early. While Conto’s approval is open and no confirm() has started, retrying getLinkCard() with the same input resumes the same checkpoint and the same Link request, so the person is not asked twice. Once a confirm() has started, a retry returns no card and leaves Link alone. Do not retry getLinkCard() while another flow may confirm the same checkpoint. A failed attempt closes the Link request, and Conto cannot refuse that confirm and close the card in one step.

Approve on the web

The person does not need the Link app. Each Stripe Link request has an approval page on link.com, and the person can approve there while signed in to Link. Pass onLinkApproval to get that page and show it to them:
The SDK calls it once, after Conto approves the purchase and Link creates the request, and before it waits for the person. It receives checkpoint, linkRequestId, approvalUrl, and approvalExpiresAt, the time Link stops accepting approval. approvalUrl is always an HTTPS link.com address. It is missing when Link does not provide one, and the person can still approve in the Link app. The page works only for the Link account that is signed in. The SDK does not wait for onLinkApproval, and an error in it does not stop the purchase. A retry that resumes the same Link request calls it again with the same page. replaceLinkCard() takes it too. A LinkCardError also has approvalUrl when the SDK stopped while the request was waiting for the person. With code LINK_CARD_NOT_CANCELLED the request is still open, so the person can approve there and a retry with the same input resumes it. After a LinkCardTimeoutError, Conto has already cancelled the request.

The card

The card stays in your agent’s process. Printing or serializing the result shows only the last four digits, the brand, and the expiry. Use the card only in the store’s card form for this purchase. linkCliWallet() runs Link CLI without a shell and reads the card from a private temporary file that it deletes before the call returns. Its options are binary (defaults to link-cli on PATH), test, paymentMethodId (defaults to the person’s default payment method), timeoutSeconds, and env.

When the total changes

Read the actual final items and charges in your trusted checkout adapter and pass them as lineItems and totals to confirm(). SDK builds with final-cart forwarding check the items and the final total even when the total is unchanged. Other rows, such as tax and shipping, may differ from the ones passed to begin(). A substituted item at the same price still requires a fresh authorization. SDK 0.7.0 and later include this behavior. For changed items at the same price, retire the unused credential and cancel its checkpoint before starting a new intent with the new items and a new idempotency key. replaceLinkCard() handles a changed total, not a same-price substitution. The executor must own an atomic payment dispatch claim. A repeated confirm() may return its existing confirmation, so it is not permission to press Pay a second time. Call getLinkCard() at the payment step, when the total includes shipping and tax. The card covers the amount Conto approved, so confirm() refuses a different total for it with LINK_CARD_TOTAL_CHANGED. From SDK 0.8.1, confirm() reads the checkpoint from Conto when your copy has no Link request, so a saved copy is safe to pass. If the total changes anyway, get a new card for the final total:
replaceLinkCard() cancels the old Link request and checkpoint, checks the final total against the agent’s rules, and gets a new card. Confirm replacement.checkpoint with the final total. From SDK 0.8.1, replaceLinkCard() reads the checkpoint before it touches the card. If the checkpoint was already confirmed, is still being checked, or has a different Link request on record, it throws LINK_CARD_NOT_REPLACED and changes nothing, at the same total too. If the old card closes but Conto does not release the spend, it throws CHECKPOINT_NOT_CANCELLED, and trying again is safe. If the total changes again, pass the latest result to replaceLinkCard(). Do not run it while another flow may confirm the same checkpoint, because Conto cannot refuse that confirm and close the card in one step. These reads need the transactions:read scope, which standard agent keys have.

When something goes wrong

If any call throws, do not pay. A ContoError from confirm() means something else, even with the same code. Link already has a request, and the spend may still be held. The error has no checkpoint, so read it with conto.checkout.get(result.checkpoint.id). Act on the stage in the table under When LINK_CARD_NOT_CANCELLED is thrown, and use result.linkRequestId as the request ID. For LINK_CARD_TOTAL_CHANGED, follow error.retryGuidance instead. The four Link errors extend LinkCardError, which also covers other Link failures. Each has holdReleased, which is true when the checkpoint no longer holds the spend. It says nothing about the card, so follow error.retryGuidance whatever its value. Error messages never contain card data. From SDK 0.8.1, these codes mean: Link could still issue the card, or a card may already be out. Before you cancel anything, read the checkpoint with conto.checkout.get(error.checkpoint.id), because another attempt may have confirmed it. Then act on the stage: A few more things to check:
  • A second request. error.linkRequestId holds one ID, the request on record when there is one. If the error names a second Link request, cancel that one too before you call conto.checkout.cancel().
  • No record. If error.checkpoint.paymentReference is missing, Conto has no record of the request, so the spend can be released when the approval lapses while the card may still work. Retry or cancel before then. With no linkRequestId at all, the wallet failed while asking Link for the card, so Conto cannot tell whether Link created the request. Retry with the same input to resume it.
  • Logged out. With Link CLI logged out, the retry and wallet.cancel() both fail, so run link-cli auth login first. Do not call conto.checkout.cancel() before the request is closed, because Conto cannot see the card and would release the spend while it still works.
  • A request with no checkpoint. If error.retryGuidance names a Link request with no checkpoint on it, a retry cannot resume until that request closes. Do not cancel that request yourself, because it may be the person’s own purchase. Follow that guidance.
  • An action in Link. A request in requires_action that Link will not resume cannot be retried or cancelled, but Link closes it on its own. wallet.waitForApproval(error.linkRequestId, { timeoutSeconds: 0 }) returns its actionUrl, where the person can fix the problem. To buy this, begin a new purchase with a new idempotency key once they have. Do not call conto.checkout.cancel() yet. The hold stays until Link closes the request, and then a retry releases it.
From SDK 0.8.1, linkCliWallet().cancel() also succeeds when Link already closed the request, for example when it expired. If it throws, the card may still work or may have been used, so do not call conto.checkout.cancel(). Fix what stopped it and try again. If it keeps failing, stop. If error.checkpoint.paymentReference is set, the owner gets a review alert after the approval lapses and records what happened on the checkout page. If it is missing, or the checkpoint has closed, no alert comes, and the card may still work with nothing held behind it, so tell the owner.

Stage CONFIRMING

CONFIRMING means a confirm() started and has not finished. Conto has not cleared the payment, so do not pay. Do not cancel the Link request either, because the check can still end in CONFIRMED. This normally lasts seconds. Wait, read the checkpoint with conto.checkout.get(), and act on the new stage. If you have no checkpoint ID, call conto.checkout.begin() with the same input and checkoutMethod: 'LINK' to get it. If Conto stopped during the check, the stage does not change on its own. confirm(), conto.checkout.cancel(), and reportOutcome() all return 409, so stop trying after a few minutes. The spend stays held. The owner gets a review alert about 30 minutes after expiresAt and records what happened on the checkout page.

When Conto’s approval ends

SDK 0.8.0 and later tell Conto the Link request ID as soon as Link creates it. If the checkpoint then lapses or a rule stops it before confirm(), Conto keeps the spend held, because the card may still work. A confirm() refused for either reason moves the checkpoint to stage OUTCOME_UNKNOWN at once. A lapse with no confirm() moves it about 5 to 10 minutes later. Until then the stage still reads APPROVED, and retrying getLinkCard() with the same input can return the card, but confirm() refuses it. Once the stage is OUTCOME_UNKNOWN, that retry throws a ContoError with code CHECKOUT_CHECKPOINT_NOT_APPROVED. From SDK 0.8.1, it is a LinkCardError with the linkRequestId. The checkpoint then has linkRequestOpen: true, which a confirmed checkpoint with no outcome never has. The SDK’s TypeScript types list this field from 0.8.1. To release the spend, cancel the Link request, then call conto.checkout.cancel(checkpoint.id). Otherwise the owner gets a review alert and records what happened. If the card was used anyway, report PAID, or UNKNOWN if you cannot tell, which keeps the spend held until the owner records what happened. After a cancel or a not paid decision, a retry throws CheckoutCheckpointClosedError. A not paid decision does not close the card, which can work for up to 48 hours. After CheckoutCheckpointClosedError, if error.checkpoint.paymentReference is set, cancel the request with wallet.cancel(error.checkpoint.paymentReference.id) before you start a new purchase. If that call throws, the card may have been used, so do not begin a new purchase. If Conto cannot record the request, the SDK reads the checkpoint, cancels the request in Link, then cancels the checkpoint, and throws LINK_CARD_NOT_RECORDED. holdReleased is false if the checkpoint could not be cancelled. If the read fails, a confirm has started, or Link cannot cancel a request that is still open, the SDK throws LINK_CARD_NOT_CANCELLED instead. Conto may have no record of that request, so the hold can end when the approval lapses while the card may still work.

Test mode

linkCliWallet({ test: true }) creates test-mode Link requests. Link returns test card data and charges nothing. Complete any Link approval required by the test flow. Conto checks and records test purchases like any other purchase.

MCP

The Conto MCP server does not issue Link cards. A tool result goes into the model’s context and often into the MCP host’s logs, so a card number and CVC must never be in one. Get the card with conto.checkout.getLinkCard() in code the model does not see, and pass the model only the checkpoint ID, the linkRequestId, and the card’s last four digits. The MCP checkpoint tools still take a linkRequestId. checkout_checkpoint_confirm and checkout_checkpoint_report_outcome send it to Conto as the payment reference. With CONTO_LINK_WALLET set to link-cli, checkout_checkpoint_cancel also cancels the request Conto has on record, or the linkRequestId you pass, and keeps the spend held until Link cancels it or reports it closed. Pass the ID if your SDK is older than 0.8.0, because Conto then has no record of the request. These rules need MCP server 0.7.2 or later. See MCP tools.

What this protects

This integration makes Conto’s approval part of how the agent pays, as long as Conto is the agent’s only way to get a Link card. It stops:
  • An agent going off script. Link is asked for a card only for a purchase Conto approved.
  • Overspending. The card is limited to the approved amount, and the amount counts toward the agent’s limits.
  • The wrong store. Conto checks the store’s domain against the owner’s rules before any card exists, and the person sees the store in Link.
  • Too many purchases. Count and velocity rules apply to each card request.
It does not stop a builder who also gives the agent raw Link access. An agent that can run Link CLI itself, use a shell, or call Link with your credentials can get a card without asking Conto. Give the agent the Conto SDK or the MCP tool, not Link CLI or a shell.

What the owner sees

Each purchase appears in Transactions like any checkout. Its page shows the Link request ID next to the order number, and each step that reported it. A purchase that needs approval appears in Inbox first.