How it works
- At the payment step, once the final total is known, the agent’s code calls
conto.checkout.getLinkCard(). - 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.
- 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.
- 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.
- Right before paying, the agent calls
confirm(). After paying, it reports the outcome.
Set up
Install Stripe’s Link CLI on the machine where your agent runs, and log in with the Link account that pays: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. PassonLinkApproval to get that page
and show it to them:
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 aslineItems 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:
When LINK_CARD_NOT_CANCELLED is thrown
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.linkRequestIdholds one ID, the request on record when there is one. If the error names a second Link request, cancel that one too before you callconto.checkout.cancel(). - No record. If
error.checkpoint.paymentReferenceis 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 nolinkRequestIdat 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 runlink-cli auth loginfirst. Do not callconto.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.retryGuidancenames 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_actionthat Link will not resume cannot be retried or cancelled, but Link closes it on its own.wallet.waitForApproval(error.linkRequestId, { timeoutSeconds: 0 })returns itsactionUrl, where the person can fix the problem. To buy this, begin a new purchase with a new idempotency key once they have. Do not callconto.checkout.cancel()yet. The hold stays until Link closes the request, and then a retry releases it.
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 beforeconfirm(), 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 withconto.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.