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.
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 acheckpoint 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_UNKNOWNand the spend stays held. This happens when you reportUNKNOWNorNOT_PAID. It also happens when a Link checkpoint with a recorded or started Link request lapses, orconfirm()refuses it because the approval lapsed or a rule now denies it. That checkpoint haslinkRequestOpen: true. Cancel the Link request and then the checkpoint to release the spend. Otherwise the owner records what happened.
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 ofcheckoutUrl. 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
RECIPIENTscope use that domain. - A list entry for
example.comalso coversshop.example.com. - Store rules match the host of
checkoutUrlthe same way. merchant.idandmerchant.nameare labels the owner sees. Write list entries as domains.checkoutUrlmust use the store’s domain name.begin()refuses an IP address or a single-word host such aslocalhostwith400.
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:
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
PAIDkeeps the amount counted toward the agent’s limits. When the receipt total is lower than the confirmed amount, send it asfinalAmountMinorand Conto counts that total instead. It can’t be more than the confirmed amount.NOT_PAIDkeeps it counted until the owner records what happened.UNKNOWNkeeps it counted until you reportPAIDor the owner records what happened.
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 reportedUNKNOWN, 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.