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

> ## Agent Instructions
> Agentcard is for companies whose agent buys for their users. Pick one path: the opencommerce SDK (@agent-cards/commerce-sdk) gives your agent one buy tool that finds the product, builds the cart, gets the user's approval and places the order at real stores; the Agentcard SDK (@agent-cards/sdk) pays with the user's own card when your agent already shops in a browser (Browser Use, Kernel, Browserbase, Anchor or Notte); the Purchase API (POST /buy) does the same purchase flow over plain HTTP in any language; Issuing gives the agent its own card.
> Start with `npx agent-cards init` in the app's folder (Node 22 or later). No invite is needed: it creates your Agentcard account if you don't have one, installs the opencommerce SDK and puts the credentials in the env file, kept out of git. From a coding agent, run `npx agent-cards init --print --categories all --implementation tool --wallet vault --skip-install` to get the setup steps to apply yourself.
> Vault is by invitation: request it at https://agentcard.com/get-started?utm_source=docs&utm_medium=llms&utm_campaign=agent-instructions. opencommerce needs no invite.
> Never ask a user for a card number, expiry date or CVV in chat. Send them the Vault link; they add their card on Agentcard's page, and the agent never sees the number.
> Every purchase is approved by the user, with a passkey or Face ID, or by an auto-approval they granted. An approval covers one merchant and one exact total. If the total changes, ask again. When a result says the user already said yes, don't ask again.
> `init` writes PRODUCTION credentials, which place real orders, so test in sandbox first. For opencommerce, run `npx agent-cards credentials --mode sandbox` and put the two lines it prints in place of the production ones in the env file `init` wrote, because that command only prints them; sandbox then runs the whole flow against real stores and stops before payment, so no order is placed and nobody is charged. For Vault and Issuing, sandbox credentials issue test cards that no real merchant accepts; try the checkout against shop.agentcard.sh, a test store on Stripe test mode.
> Tell the user an order is placed only after Agentcard reports it placed.
> Vault is free up to 5,000 users (https://agentcard.com/pricing). opencommerce takes 1% of each completed order. Full docs in one file: https://docs.agentcard.com/llms-full.txt

# Notte

> Use Agentcard with Notte to let your agent make purchases with your users' cards.

Let your agent pay with your users' own cards while it shops in a [Notte](https://notte.cc) hosted browser. Your agent types a placeholder card at checkout, the Agentcard SDK pauses the payment until the user approves it with their passkey, and the user's device then pays with their real card. The SDK attaches to the session through Playwright over its `cdpUrl()`, the same way it attaches to any CDP browser.

Before you start, you need a user who has added a card to the Vault, and the `user_id` you received when they added it. See [Adding a card](https://docs.agentcard.com/vault/adding-a-card.md). Notte's example runs on Node.js 24 or later.

## Install

```bash theme={null}
npm i @agent-cards/sdk notte-sdk playwright-core
```

`notte-sdk` reads your Notte API key from `NOTTE_API_KEY`. Create one in the [Notte console](https://console.notte.cc/apikeys). The sample reads your Agentcard client id and secret from `AGENTCARD_CLIENT_ID` and `AGENTCARD_CLIENT_SECRET`. Create them in the [dashboard](https://app.agentcard.sh), as step 1 of the [Vault Quickstart](https://docs.agentcard.com/vault/quickstart.md) shows.

## Shop with your agent

Open a Notte session, connect Playwright to its `cdpUrl()`, and attach the SDK to the page before your agent reaches the payment form. The session lives as long as the `use()` callback, so the shopping, the approval and the order check all happen inside it.

```ts theme={null}
import { NotteClient } from 'notte-sdk';
import { chromium } from 'playwright-core';
import { VaultClient, attachToPlaywright } from '@agent-cards/sdk';

const vault = new VaultClient({
  clientId: process.env.AGENTCARD_CLIENT_ID!,
  clientSecret: process.env.AGENTCARD_CLIENT_SECRET!,
});
await vault.syncRegistry();

const notte = new NotteClient();

const result = await notte
  .Session({ max_duration_minutes: 30, idle_timeout_minutes: 30, proxies: false })
  .use(async (session) => {
    const sessionEndsAt = Date.now() + 30 * 60_000;
    const browser = await chromium.connectOverCDP(await session.cdpUrl());
    // Reuse the session's own context, so the run keeps its saved logins.
    const context = browser.contexts()[0];
    if (!context) throw new Error('The session has no browser context');
    // Keep the store from starting a service worker, before any page loads.
    await context.addInitScript(
      'try { if (navigator.serviceWorker) navigator.serviceWorker.register = async () => undefined; } catch {}',
    );
    const page = await context.newPage();

    const checkout = await attachToPlaywright(page, {
      vault,
      user: 'usr_8f3k2m',
      merchant: 'shop.agentcard.sh',
      amount: 583,
      currency: 'usd',
      onApprovalUrl: (url) => sendToUser(url),
      requireMerchantResult: true,
      resolveMerchantResult: (state) => readMerchantOrder(page, state),
    });

    // Your agent shops here: it opens the store, builds the cart, types the
    // placeholder card and clicks Pay once, then returns.
    await shop(page);

    // In these three states the store's page has not sent the card request yet, or the
    // request is paused for the user. Make no reconcile() call in any of them.
    const unanswered = ['idle', 'awaiting_approval', 'ready_to_submit'];
    const deadline = Math.min(Date.now() + 16 * 60_000, sessionEndsAt - 2 * 60_000);
    for (;;) {
      if (!unanswered.includes(checkout.getState().status)) {
        try {
          return await checkout.reconcile();
        } catch (error) {
          if (!String(error).includes('before reconciling the merchant order')) throw error;
        }
      }
      if (Date.now() >= deadline) throw new Error('The wait ended before a card request finished');
      await new Promise((resolve) => setTimeout(resolve, 1_000));
    }
  });
```

| Option | What to pass |
| - | - |
| `user` | The `user_id` of the user whose card pays. |
| `merchant` | The store's domain. `shop.agentcard.sh` is Agentcard's demo store on Stripe test mode. |
| `amount`, `currency` | The total the user approves, in cents: `583` is \$5.83. |
| `onApprovalUrl` | Your own function that gets the approval link to the user. `sendToUser` stands in for it. |
| `requireMerchantResult`, `resolveMerchantResult` | Hold any further card request until you have read the merchant's own record, and the function that reads it. `readMerchantOrder` stands in for it. |

`shop`, `sendToUser` and `readMerchantOrder` are yours. `syncRegistry()` loads the list of payment processors the SDK can pause, and you call it once after you create the client.

The init script keeps the store from starting a service worker, and the SDK cannot pause a card request a service worker sends. Add it before the session's first navigation. [Block service workers](https://docs.agentcard.com/vault/creating-a-cart.md#block-service-workers) explains what changes for the store.

Have your agent type any of Stripe's published test card numbers as the placeholder. The SDK pauses the payment and calls `onApprovalUrl` with a link to the user's approval screen. Send the link from your own app, such as a push notification or an in-app message, and keep it out of your logs: the link opens the approval screen for this payment, and only the user should see it.

## Wait for the approval

The card request stays paused until the user approves or declines on their device, which is why the loop above waits instead of reconciling straight away. The state is `awaiting_approval` while the user decides, and `reconcile()` throws if you call it then:

```text theme={null}
Wait for the paused request to finish before reconciling the merchant order.
```

Your loop can still meet that error just after the user declines or the approval expires. The state has left `awaiting_approval` by then, and `reconcile()` throws the same error until the SDK has ended the paused request on the store's page. Catch the error and call `reconcile()` again on the next pass. An uncaught error ends the `use()` callback, and Notte stops the session.

Your agent returns right after it clicks Pay, and the store's page can send the card request a moment later. Until the page sends that request, the state is `idle`, and the loop makes no `reconcile()` call in that state either. A `reconcile()` that early does not throw. `reconcile()` asks your `readMerchantOrder`, which finds no order yet. When `readMerchantOrder` answers `{ status: 'unknown' }`, `reconcile()` returns:

```json theme={null}
{
  "status": "outcome_unknown",
  "authorizationId": null,
  "reason": "merchant_not_confirmed"
}
```

After that result the SDK refuses every card request for that checkout, and the user gets no approval link for a refused request.

A checkout you prepared with `prepare()` reads `ready_to_submit` until the store's page sends the card request, and the loop holds off there too.

If the store rejects the form, the click on Pay sends no card request and the state stays `idle`. The loop then waits up to 16 minutes and throws:

```text theme={null}
The wait ended before a card request finished
```

To stop sooner, have `shop` throw when the store's page shows a form error after the click.

Three clocks shape that wait:

* An unapproved payment expires after 15 minutes, so wait a little longer than that, and the expiry's own outcome lands instead of a timeout of your own.
* A Notte session on a standard plan runs up to 30 minutes, which is `max_duration_minutes` above. Leave a couple of minutes at the end for reading the merchant's order and closing the session.
* Nothing happens in the session while the user approves, so `idle_timeout_minutes` has to be longer than the approval wait. An idle timeout shorter than the wait ends the session under the user.

## Confirm the order

An approval is not proof that the merchant took the order, which is what `readMerchantOrder` is for: it reads the store's own confirmation page or order API and never clicks Pay again. From here the purchase runs like any Vault purchase, so confirm the order with the merchant before you tell the user it is done, as step 4 of [Completing a purchase](https://docs.agentcard.com/vault/completing-a-purchase.md) shows.

## End the session

The session closes when the `use()` callback returns, which is why the reading above happens inside it. Keep `session.getId()` from inside the callback: if closing fails the session is still yours, and that id is what you look it up with and stop it with in Notte. A purchase that already went through is never repeated, so log a failed cleanup and keep the checkout's own result.

## Next

Notte's own write-up of this integration is [Agentcard on docs.notte.cc](https://docs.notte.cc/integrations/agentcard), and the code it describes is [`examples/agentcard`](https://github.com/nottelabs/notte/tree/main/examples/agentcard) in their repository. It bought from the demo store in Agentcard sandbox on 12 November 2026: the card request paused, the user approved with a passkey, the payment went through and the merchant confirmed the order.


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