> ## Documentation Index
> Fetch the complete documentation index at: https://conto.finance/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Checkout checkpoints

> Check an agent's rules right before it opens Link or another payment method, and again right before it pays.

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.

## The two checkpoints

| When | Call | Continue only if |
| - | - | - |
| Before Link, a card form, Shop Pay, or PayPal opens | `checkout.begin()` | The stage is `APPROVED` |
| Right before the payment is submitted | `checkout.confirm()` | The stage is `CONFIRMED` |
| After the payment | `checkout.reportOutcome()` | Always report it |

```typescript theme={null}
const checkpoint = await conto.checkout.begin({
  idempotencyKey: order.id,
  merchant: { id: 'acme-retail', name: 'ACME Retail', checkoutUrl: page.url() },
  amountMinor: 7900,
  purpose: 'Drip coffee maker the shopper chose',
  lineItems: [{ name: 'Drip coffee maker', quantity: 1, unitAmountMinor: 7900 }],
});

// 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 fails, stop the checkout. A denial at either checkpoint returns an error, and the
amount stops counting toward the agent's limits.

## 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`. 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`.

After submission, report `PAID`, `NOT_PAID`, or `UNKNOWN` on the same checkpoint. 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](/docs/sdk/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.

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.

An approved checkpoint that is never confirmed is released when its approval expires, 30 minutes
after `begin()`. If a confirmed checkpoint never gets an outcome, the owner gets an alert to check
the order.

## MCP tools

An MCP agent can use the same flow without code: `checkout_checkpoint_begin`,
`checkout_checkpoint_confirm`, and `checkout_checkpoint_report_outcome`, plus
`checkout_checkpoint_cancel` and `checkout_checkpoint_status`. See [MCP tools](/docs/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.

For control at the moment of payment, pay through Conto: a
[managed wallet](/docs/guides/custody-modes), or a [connected card](/docs/guides/connected-cards) whose
single-use credential Conto releases only after the controls pass.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.