Skip to main content
When your agent completes a checkout itself, call Conto at two points: right before it opens the payment method, and right before it submits the payment. Conto checks the agent’s rules at both, counts the amount toward its limits in between, and records the outcome your agent reports. You need an agent and a standard SDK key, which has every scope these calls use. No wallet is needed.

The two checkpoints

New organizations start with these limits: $25 per transaction, $100 a day, and owner approval above $10. The $15 purchase below fits under the cap and goes to the owner for approval. See starter guardrails.
If any call throws, stop the checkout. A denial at either checkpoint throws an error and releases the amount from the agent’s limits. A denial by a policy rule or spend limit also counts toward the agent’s auto-freeze policy violation count. amount from the agent’s limits. A Link checkpoint with a recorded Link request keeps the amount held until you cancel the Link request and then the checkpoint, because a checkpoint cancel does not close a Link card. See Stripe Link cards for these holds in full.

When the owner must approve

When the agent’s rules require approval, begin() returns the stage AWAITING_APPROVAL with nextAction: WAIT_FOR_APPROVAL. Conto holds the spend against the agent’s limits and sends the owner an approval request in Inbox. The organization’s approval workflow sets who can approve it. Do not open the payment method while the checkpoint waits. The checkpoint carries the request:
approval.status is PENDING, APPROVED, DENIED, EXPIRED, or CANCELLED. While the checkpoint waits, expiresAt is when the owner’s decision window closes. The request expires when its approval workflow does, and no later than 24 hours after begin(). waitForApproval(checkpoint, options) reads the checkpoint until the owner decides. It returns the approved checkpoint, with stage APPROVED. The 30 minutes to confirm start at the approval.

Errors

Each error has a checkpoint property with the checkpoint as Conto last returned it. CheckoutApprovalDeniedError and CheckoutApprovalExpiredError extend CheckoutCheckpointClosedError. begin() throws CheckoutCheckpointClosedError when you retry it with the key of a checkpoint that already closed.

Reject, expire, cancel, or unknown outcome

  • The owner rejects the purchase. The stage becomes DENIED, and Conto releases the spend.
  • The request expires. The stage becomes EXPIRED, and Conto releases the spend.
  • The agent cancels while it waits. Conto withdraws the approval request and releases the spend. The stage becomes CANCELLED.
  • The outcome is unknown. The stage becomes OUTCOME_UNKNOWN and the spend stays held. This happens when you report UNKNOWN or NOT_PAID. It also happens when a Link checkpoint with a recorded or started Link request lapses, or confirm() refuses it because the approval lapsed or a rule now denies it. That checkpoint has linkRequestOpen: true. Cancel the Link request and then the checkpoint to release the spend. Otherwise the owner records what happened.
Until the owner approves, the confirm endpoint returns 409 APPROVAL_REQUIRED and the SDK’s confirm() throws CheckoutApprovalPendingError. Retrying begin() with the same key returns the same waiting checkpoint.

The merchant is the checkout domain

Conto names the merchant by the registrable domain of checkoutUrl. Case and a leading www. do not matter. https://WWW.Example.com/cart and https://shop.example.com/checkout are both the merchant example.com. Stores on a shared store platform’s domain each count as their own merchant.
  • Allow and block lists, payee status, and velocity rules with RECIPIENT scope use that domain.
  • A list entry for example.com also covers shop.example.com.
  • Store rules match the host of checkoutUrl the same way.
  • merchant.id and merchant.name are labels the owner sees. Write list entries as domains.
  • checkoutUrl must use the store’s domain name. begin() refuses an IP address or a single-word host such as localhost with 400.
See checkout purchases for how rules count them.

HTTP endpoints

If your integration calls the HTTP API directly, use an agent SDK key with the scope for each step. All paths below begin with /api/sdk and return { "checkpoint": { ... } } with an id, stage, nextAction, and expiresAt. Begin with a stable idempotencyKey (8 to 255 characters), a merchant with id, name and an HTTPS checkoutUrl, amountMinor in USD cents (at most 500000), currency: "USD", purpose, and a cart with lineItems and totals. Pass checkoutMethod when the payment method is not Link. Continue only after APPROVED with CONFIRM_BEFORE_PAYING. When begin returns 200 with AWAITING_APPROVAL and WAIT_FOR_APPROVAL, read the checkpoint every few seconds until the stage changes. Continue after APPROVED. Stop after DENIED, CANCELLED, or EXPIRED. Confirm with the final amountMinor, currency, and, when available, the final cart and pageUrl. The raw HTTP confirm refuses a changed total. Cancel the old checkpoint, begin a new one at the final total with a new idempotency key, and confirm that one. The SDK checkout.confirm() helper performs that replacement automatically. Submit payment only after CONFIRMED with PAY_THEN_REPORT_OUTCOME. Confirm and report outcome also accept an optional paymentReference, such as { "provider": "LINK", "id": "lsrq_..." } for the Link request behind a Stripe Link card. The checkpoint keeps the first reference it receives and returns 409 for a different one. Retrying the same reference is safe. A reference that contains a card number is refused with 400. Once a reference is recorded, the spend stays held even if the approval lapses. A new reference sent while a confirm is being checked also returns 409, so read the checkpoint and send it again once the stage changes. If the checkpoint has closed, cancel the Link request and do not pay. For a Link card, call link-request-started with no body right before you ask Link to create the card request. Then record the request ID with payment-reference as soon as Link returns it. From the first call on, the spend stays held if the approval lapses or a rule stops the checkpoint before confirm, even if the request ID never reaches Conto. Such a checkpoint has linkRequestOpen: true and no paymentReference, so find the request in Link and cancel it before you cancel the checkpoint. The first link-request-started call returns 409 once the approval has ended, and then do not ask Link for a card. A repeat is accepted until the checkpoint closes, so a retry can find the request an earlier attempt may have created and record it. After submission, report PAID, NOT_PAID, or UNKNOWN on the same checkpoint. An outcome sent before CONFIRMED returns 409. The exception is a checkpoint with linkRequestOpen: true, where PAID records the payment and UNKNOWN keeps the spend held for the owner. NOT_PAID changes nothing there, so you can still cancel. Read its status before retrying after a timeout. Never submit the payment twice. A reported outcome has settlementVerified: false and is not proof of settlement. If Conto returns 503 PAYMENTS_PAUSED, stop checkout and ask the owner to check payment availability. See error handling. Stage CONFIRMING means a confirm started and has not finished. Do not pay, and do not cancel a Link request, because the check can still end in CONFIRMED. It normally lasts seconds. If Conto stopped during the check, confirm, cancel, and outcome calls return 409 and the spend stays held. About 5 to 10 minutes after expiresAt, the stage changes on its own: to OUTCOME_UNKNOWN with linkRequestOpen: true if Conto has the Link request on record, otherwise to EXPIRED with the spend released. The owner can record what happened on the checkout page at any time before then. A closed checkpoint has holdReleasePending: true while its spend is still held because the release has not finished. Conto retries it within minutes, so you do not need to release it. The field says nothing about a Link card, so still cancel an open Link request.

When the total changes

Tax and shipping often appear only after the buyer signs in and enters an address. The final total still has to pass the agent’s rules. If it differs from the approved total, confirm() replaces the approval with one for the final total before it confirms. If the final total breaks a rule, the payment stops there. When the total differs, confirm() reads the checkpoint first, so the key needs transactions:read. A checkpoint with a Link request throws LINK_CARD_TOTAL_CHANGED instead. See Stripe Link cards. If the final total needs the owner’s approval, the owner gets a new request for it. confirm() throws CheckoutApprovalPendingError:
When you pass lineItems or totals to confirm(), Conto checks the items and the final total. A totals row has the form { type, label, amountMinor }. Include exactly one row with type: 'total' that equals amountMinor. Other rows, such as subtotal, tax and shipping, may differ from the ones passed to begin(). A substituted item at the same total gets a 409. SDK 0.7.0 and later send these fields to Conto. Pass pageUrl to confirm() to check that the payment is submitted on the merchant’s site or the payment method’s own pages. Conto knows the payment method from the checkoutMethod you pass to begin(): LINK (the default), CARD, SHOP_PAY or PAYPAL. A checkpoint begun without it counts as Link, so a PayPal or Shop Pay pageUrl is refused with 409 and a budget counts the spend under Stripe Link.

Report the outcome

  • PAID keeps the amount counted toward the agent’s limits. When the receipt total is lower than the confirmed amount, send it as finalAmountMinor and Conto counts that total instead. It can’t be more than the confirmed amount.
  • NOT_PAID keeps it counted until the owner records what happened.
  • UNKNOWN keeps it counted until you report PAID or the owner records what happened.
Report an outcome only after confirm() succeeds. To stop before that, cancel the checkpoint. Checkout spend counts toward the agent’s daily, weekly, and monthly limits at agent or organization scope, together with its wallet and card spend. An approved checkpoint that is never confirmed is released when its approval expires, 30 minutes after begin() or after the owner’s approval. A Link checkpoint whose Link request Conto has stays held instead, because the Link card may still work. When a confirmed checkpoint or a held Link checkpoint has no outcome, the owner gets an alert to check the order with the merchant.

What the owner sees

Each checkout appears in Transactions, with its status, amount, payment method, agent, purpose, order number, and steps. A checkout that waits for approval links to its request in Inbox. When a confirmed checkout has no outcome, or the agent reported UNKNOWN, its page shows Mark as paid and Mark as not paid. Owners, Admins, and Managers can use them. Mark as paid keeps the amount counted toward the agent’s limits. Mark as not paid releases it.

MCP tools

An MCP agent uses the same flow with five tools: checkout_checkpoint_begin, checkout_checkpoint_confirm, checkout_checkpoint_report_outcome, checkout_checkpoint_cancel, and checkout_checkpoint_status. When checkout_checkpoint_begin returns AWAITING_APPROVAL, its result tells the agent not to open the payment method. The agent calls checkout_checkpoint_status every few seconds until the stage is APPROVED, then continues. It stops if the stage becomes DENIED, CANCELLED, or EXPIRED. When the total changed, checkout_checkpoint_confirm starts a new checkpoint at the final total and returns it, confirmed or as AWAITING_APPROVAL. The agent uses the new checkpoint’s id from then on. If it is AWAITING_APPROVAL, the agent waits the same way, then calls confirm again with the new id. A checkpoint with a Stripe Link request returns LINK_CARD_TOTAL_CHANGED instead. See MCP tools.

How strong this control is

Checkpoints are the lightweight way to add Conto to a checkout. Conto decides, and your checkout acts on the answer. Conto does not see the card or the charge, so it does not check a payment your agent makes without calling the checkpoints, and it records the outcome you report. With Stripe Link, the Stripe Link card integration goes further. The agent asks Conto before it asks Stripe Link for a card, and Stripe Link is asked only after Conto approves the purchase. For control at the moment of payment, pay through Conto: a managed wallet, or a connected card whose single-use credential Conto releases only after the controls pass.

Shared budgets

A shared budget that covers an agent counts its checkout checkpoints. begin() holds the amount on each budget that covers the agent, and the outcome settles or releases it. A paused or expired budget refuses them. If a budget refuses, begin() throws a ContoError with status 409, code POLICY_VIOLATION and a reasonCode such as SHARED_BUDGET_EXCEEDED, and the owner’s Transactions row reads Refused by a budget. A retry with the same key throws CheckoutCheckpointClosedError, so use a new key. See checkouts and Stripe Link. Card checkouts that Conto completes for an approved cart are still refused for any agent a budget covers. Concurrent checkpoints for one agent cannot spend the same remaining limit twice, and retrying a cancel releases its hold only once.