Checkout checkpoints

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.

npm install @conto_finance/sdk

The two checkpoints

When	Call	Continue only if
Before Link, a card form, Shop Pay, or PayPal opens	`checkout.begin()`	The stage is `APPROVED`
While the owner reviews the purchase	`checkout.waitForApproval()`	It returns the approved checkpoint
Right before the payment is submitted	`checkout.confirm()`	The stage is `CONFIRMED`
After the payment	`checkout.reportOutcome()`	Always report it

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.

import { Conto } from '@conto_finance/sdk';

const conto = new Conto({ apiKey: process.env.CONTO_API_KEY! });

let checkpoint = await conto.checkout.begin({
  idempotencyKey: order.id,
  merchant: { id: 'acme-retail', name: 'ACME Retail', checkoutUrl: page.url() },
  amountMinor: 1500,
  purpose: 'Phone charger the shopper chose',
  lineItems: [{ name: 'USB-C phone charger', quantity: 1, unitAmountMinor: 1500 }],
});

if (checkpoint.stage === 'AWAITING_APPROVAL') {
  // The owner reviews the purchase. Throws if they reject it or the request expires.
  checkpoint = await conto.checkout.waitForApproval(checkpoint, { timeoutMs: 15 * 60_000 });
}

// Open Link. The buyer signs in and the final total appears.

const confirmed = await conto.checkout.confirm(checkpoint, {
  amountMinor: finalTotal,
  totals: finalTotals,
});

// Submit the payment.

await conto.checkout.reportOutcome(confirmed.id, { outcome: 'PAID', reference: orderNumber });

If any call throws, stop the checkout. A denial at either checkpoint throws an error, and the amount stops counting toward the agent’s limits.

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 Alerts & Approvals. 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:

{
  "stage": "AWAITING_APPROVAL",
  "nextAction": "WAIT_FOR_APPROVAL",
  "expiresAt": "2026-10-05T15:00:00.000Z",
  "approval": {
    "requestId": "cmg8x2k1p0004l70a9c3d7f2e",
    "status": "PENDING",
    "expiresAt": "2026-10-05T15:00:00.000Z"
  }
}

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.

Option	Default	Meaning
`timeoutMs`	10 minutes	Stop waiting after this long. The spend stays held
`pollIntervalMs`	5 seconds	Time between reads. The minimum is 1 second
`signal`	None	An `AbortSignal` that stops the wait

Errors

Each error has a checkpoint property with the checkpoint as Conto last returned it.

Error	When	What to do
`CheckoutApprovalDeniedError`	The owner rejected the purchase	Do not pay. Conto released the spend
`CheckoutApprovalExpiredError`	The request expired before the owner decided	Do not pay. Conto released the spend
`CheckoutApprovalTimeoutError`	`timeoutMs` passed before the owner decided	Wait again, or cancel the checkpoint to release the spend
`CheckoutApprovalPendingError`	The checkpoint still needs approval when you call `confirm()`	Call `waitForApproval(error.checkpoint)`, then confirm the checkpoint it returns
`CheckoutCheckpointClosedError`	The checkpoint is already denied, cancelled, expired, or not paid	Stop this checkout. Start a new purchase with a new idempotency key

CheckoutApprovalDeniedError and CheckoutApprovalExpiredError extend CheckoutCheckpointClosedError. begin() throws CheckoutCheckpointClosedError when you retry it with the key of a checkpoint that already closed.

Reject, expire, or cancel

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.

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.

Step	Method and path	Scope
Begin	`POST /checkout-checkpoints`	`payments:request`
Read	`GET /checkout-checkpoints/{id}`	`transactions:read`
Confirm	`POST /checkout-checkpoints/{id}/confirm`	`payments:execute`
Report outcome	`POST /checkout-checkpoints/{id}/outcome`	`payments:confirm`
Cancel before confirm	`POST /checkout-checkpoints/{id}/cancel`	`payments:execute`

Begin with a stable idempotencyKey, merchant ID, name and HTTPS checkout URL, amount in USD cents, purpose, and a cart with line items and totals. 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. Conto refuses a reference that contains a card number with 400. After submission, report PAID, NOT_PAID, or UNKNOWN on the same checkpoint. An outcome sent before CONFIRMED returns 409. 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.

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. If the final total needs the owner’s approval, the owner gets a new request for it. confirm() throws CheckoutApprovalPendingError:

import { CheckoutApprovalPendingError, type CheckoutCheckpoint } from '@conto_finance/sdk';

const final = { amountMinor: finalTotal, totals: finalTotals };
let confirmed: CheckoutCheckpoint;
try {
  confirmed = await conto.checkout.confirm(checkpoint, final);
} catch (error) {
  if (!(error instanceof CheckoutApprovalPendingError)) throw error;
  const approved = await conto.checkout.waitForApproval(error.checkpoint);
  confirmed = await conto.checkout.confirm(approved, final);
}

Pass pageUrl to confirm() to check that the payment is submitted on the merchant’s site or the payment method’s own pages.

Report the outcome

PAID keeps the amount counted toward the agent’s limits.
NOT_PAID releases it.
UNKNOWN keeps it counted until you report again 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. When a confirmed 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 Alerts & Approvals. 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. checkout_checkpoint_confirm can return AWAITING_APPROVAL for a changed total. The agent waits the same way, then calls confirm again. 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.

Get started

Integrate

Payments

Conto Commerce

Spending controls

Operate

Conto Pay

Checkout checkpoints

The two checkpoints

When the owner must approve

Errors

Reject, expire, or cancel

The merchant is the checkout domain

HTTP endpoints

When the total changes

Report the outcome

What the owner sees

MCP tools

How strong this control is

​The two checkpoints

​When the owner must approve

​Errors

​Reject, expire, or cancel

​The merchant is the checkout domain

​HTTP endpoints

​When the total changes

​Report the outcome

​What the owner sees

​MCP tools

​How strong this control is

The two checkpoints

When the owner must approve

Errors

Reject, expire, or cancel

The merchant is the checkout domain

HTTP endpoints

When the total changes

Report the outcome

What the owner sees

MCP tools

How strong this control is