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

# Check out inside your app

> Open the add-a-card and approval pages in an in-app browser, and send the shopper back into your app the moment they finish.

Your iPhone app opens the add-a-card page or the approval page in an in-app browser, a browser window that opens inside your app. The shopper saves a card in the Vault, Agentcard's page where the shopper keeps their card and approves payments, or approves the payment with Face ID. The page then sends them straight back into your app at the link you chose, such as `yourapp://agentcard-done`, and the shopper never has to find their way back from Safari.

## Set your return link

Pass your app's link once, and every add-a-card link and approval link Agentcard hands out from then on ends at it.

> [tab] SDK
>
> Pass `returnUrl` when you build the tool:
>
> ```ts agentcard.ts theme={null}
> const buy = buyTool({
>   agentcard,
>   externalUserId: viewer.id,
>   returnUrl: 'yourapp://agentcard-done',
> });
> ```
>
> Every `vault` and `approval` link the tool hands to `sendLink` ends at `yourapp://agentcard-done`.

> [tab] MCP
>
> The MCP server's `buy` tool takes no return link, so a page opened from its `links` ends on Agentcard's page. Open the `url` in an in-app browser all the same, and close it when [`get_updates`](https://docs.agentcard.com/commerce-mcp/tools/get_updates) reports that the step ended. To send the shopper back into your app on their own, use the SDK or the API.

> [tab] API
>
> Send `return_url` on every call to `POST /buy`:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/buy \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "ask": "two packs of AA batteries from amazon",
>     "external_user_id": "user-42",
>     "return_url": "yourapp://agentcard-done"
>   }'
> ```
>
> Every `add_card_url` and `approval_url` that call hands out ends at `yourapp://agentcard-done`. Agentcard puts the link on the pages that are open when the call answers, so send it on every call, not only the first. A page that already carries a return link keeps it.
>
> `return_url` works only on a call made with your company's own access token, the one your `client_id` and `client_secret` exchange for, as [Get an access token](https://docs.agentcard.com/purchase-api/http.md#get-an-access-token) shows.

## Register your app's link

Agentcard sends a shopper only to a link your company registered, so a link copied into a request from anywhere else goes nowhere. Add the exact link, such as `yourapp://agentcard-done`, to your sandbox credentials, the ones for Agentcard's test mode, which charges nothing, and to your production credentials alike.

In the dashboard, open `Settings → Developers → Credentials`, add the link under `Redirect URIs` on the `Sandbox` tab, then add it again on the `Production` tab. A link in your app's own scheme, the prefix such as `yourapp://` that opens your app, works, and so does `https`. An `http` link works only on `localhost`, in the sandbox.

Agentcard refuses a link you did not register before it starts the purchase, and nothing happens to the shopper's cart:

> [tab] SDK
>
> The call throws an `AgentcardApiError` with `code: invalid_return_url` and `status: 400`:
>
> ```text theme={null}
> AgentcardApiError: return_url must be exactly one of this client's registered redirect URIs (scheme and host compared without case, a default port dropped, the fragment ignored, path and query as registered); http only on localhost in test mode.
> ```

> [tab] MCP
>
> The MCP server sends no return link, so there is nothing to refuse.

> [tab] API
>
> ```text theme={null}
> 400
> {
>   "error": "return_url must be exactly one of this client's registered redirect URIs (scheme and host compared without case, a default port dropped, the fragment ignored, path and query as registered); http only on localhost in test mode.",
>   "code": "invalid_return_url",
>   "reason": "return_url is not exactly one of the registered redirect URIs"
> }
> ```

Register that exact link on the credentials the call used, and send the call again.

## Open the page in an in-app browser

Open each add-a-card link and approval link in `SFSafariViewController` or `ASWebAuthenticationSession`. Both run Safari, so the shopper's passkey, the fingerprint or face check that approves a payment, works there with Face ID or Touch ID.

A `WKWebView`, a web view your app draws itself, cannot use the shopper's passkey. The page then shows the shopper a button that opens it in Safari instead, and the shopper returns to your app from there. Use one of the two Safari views to keep the shopper inside your app.

Open each URL exactly as Agentcard gave it. [Send each link](https://docs.agentcard.com/opencommerce/guides/sending-each-link.md) shows where each link appears.

> [tab] SDK
>
> ```ts chat.ts theme={null}
> const turn = buy.turn(message, {
>   sendLink: (link) => {
>     if (link.kind === 'vault' || link.kind === 'approval') return openInAppBrowser(viewer.id, link.url); // your code
>     return deliverLink(viewer.id, link);
>   },
> });
> ```

> [tab] MCP
>
> Open each `url` in the result's `links` whose `kind` is `add_card` or `approval`.

> [tab] API
>
> Open each `add_card_url` and `approval_url` from the answer.

## Read what the shopper did

The page sends the shopper to your link with what happened on it, so your app can close the browser and move on without asking Agentcard.

| Page | Your app opens |
| - | - |
| Vault, once the card is saved | `yourapp://agentcard-done` |
| Approval, once the shopper approves | `yourapp://agentcard-done?authorization_id=cauth_3f9a…&status=approved` |
| Approval, once the shopper declines | `yourapp://agentcard-done?authorization_id=cauth_3f9a…&status=declined` |

`authorization_id` names the payment the shopper decided on. A registered link that already carries a query, such as `yourapp://done?from=agentcard`, comes back exactly as registered, with nothing added.

`ASWebAuthenticationSession` hands the link to its completion handler and closes on its own when you start it with your link's scheme. With `SFSafariViewController`, your app's link handler receives it, and your app dismisses the view.

Agentcard still tells your server what happened: a `card_added` message once the card is saved, and `order_placed` once the order goes through. Move the purchase on from those, as [Move the purchase on](https://docs.agentcard.com/opencommerce/guides/taking-the-next-step.md) shows.

## Get your own value back

Make the add-a-card link yourself when your app wants a value of its own back, such as the screen the shopper was buying from. The shopper then returns to `yourapp://agentcard-done?state=moment-7`.

> [tab] SDK
>
> ```ts vault.ts theme={null}
> const link = await agentcard.mintVaultLink({
>   externalUserId: viewer.id,
>   returnUrl: 'yourapp://agentcard-done',
>   state: 'moment-7',
> });
> ```
>
> `state` needs `returnUrl`. A `state` without one throws a `TypeError`, and no request is sent.

> [tab] MCP
>
> The MCP server has no tool that makes an add-a-card link. Use the SDK or the API for this.

> [tab] API
>
> Create a Vault link with `return_url` and `state`, and send the shopper the `url` the answer carries:
>
> ```bash theme={null}
> curl https://api.agentcard.sh/api/v2/vault_sessions \
>   -H "Authorization: Bearer $AGENTCARD_TOKEN" \
>   -H "Content-Type: application/json" \
>   -d '{
>     "external_user_id": "user-42",
>     "return_url": "yourapp://agentcard-done",
>     "state": "moment-7"
>   }'
> ```
>
> `state` needs `return_url`. Agentcard refuses a `state` sent alone, and creates no link:
>
> ```text theme={null}
> 400
> {"error":{"code":"invalid_request","message":"state and code_challenge ride the return link: pass return_url, a registered redirect URI.","docs":"https://docs.agentcard.com"}}
> ```
>
> Send the same request again with `return_url` set to one of your registered links. [Create a vault session](https://docs.agentcard.com/api-reference/vault/sessions-create.md) documents the endpoint in full.

## Check it in the sandbox

1. Register `yourapp://agentcard-done` on your sandbox credentials.
2. Send a return link you did not register. Check that Agentcard refuses it with `invalid_return_url`.

> [tab] SDK
>
> 3. Build the tool with `returnUrl`, and send "two packs of AA batteries from Amazon" as a test shopper nobody connected.
> 4. Open the `vault` link in `SFSafariViewController`, and save a test card with Face ID or Touch ID. A shopper nobody connected saves their card first, so the link asks for no code. Check that your app opens `yourapp://agentcard-done` and the browser closes.

> [tab] MCP
>
> 3. Open an add-a-card link from `links` in `SFSafariViewController`, and save a test card with Face ID or Touch ID. Check that the page stays on Agentcard's page and your app closes the view itself. The sandbox sends no `card_added` message, so `get_updates` reports the saved card only with live credentials.

> [tab] API
>
> 3. Create a Vault link with `return_url` for a new test shopper, open its `url` in `SFSafariViewController`, and save a test card with Face ID or Touch ID. Check that your app opens `yourapp://agentcard-done` and the browser closes.
> 4. Confirm a cart at a store that runs its own checkout, open the `approval_url` the answer carries, and approve. Check that your app opens `yourapp://agentcard-done?status=approved`, and that the next confirm answers `approved_not_charged`.

At a store Agentcard pays itself, the sandbox stops before payment, so check that approval page and its return with live credentials by buying one inexpensive item with your own card, as [Approving a purchase](https://docs.agentcard.com/commerce-sdk/guides/approving-a-purchase.md) shows.


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