STACK
MENU
DOCS / THE ACCOUNT / YOUR OWN CARD

Your own card

How you add your card once, how an agent pays with it on a merchant's checkout page, and how you approve each purchase. What the service is and what it costs is on Services.

Before you start

  • The agent needs an open account with a browser: see Browser. The checkout runs in the agent's browser session.
  • The card is yours. It is held by the card provider, Agentcard. STACK never sees the number.
  • There are no terminal commands for checkout: it is used from an AI client or from code.

Add your card

prompt
Show me the card link for the assistant account.

The client calls stack_get_account. While the card waits for you, its details carry card_link_url. Open that link on your own device and enter the card there. The card is ready a few minutes later, when its state is ready. One card serves all of your agents. With controls on, you can give each agent a monthly budget.

Add it on the device you will approve purchases from, normally your phone. Each purchase is approved with a passkey that is made on that device.

Pay on a checkout page

prompt
Buy the 12-dollar domain renewal on example-registrar.com.

The agent opens the merchant's checkout page in its browser, then starts the checkout:

typescript
const browser = stack.accounts.browser;

const purchase = await browser.checkout('acct_123', session.session_id, {
  merchant_origin: 'https://example-registrar.com',
  amount_minor: 1200,
  currency: 'USD',
}, { passportToken });
// purchase.purchase_id, purchase.placeholder_card
  • The tool is stack_browser_checkout.
  • merchant_origin must be the https site the browser is on. A checkout started for another site is refused.
  • amount_minor is in the smallest unit of the currency: 1200 is 12.00 USD. Where the agent has a budget, the amount is reserved against it.
  • The answer carries a placeholder card. The agent types that into the form. It works for 15 minutes, once, and only on that site.
  • A real card number typed by the agent is refused.

Approve the purchase

  • You approve every purchase yourself, whatever the trust switch says, on the device where you added the card.
  • STACK sends you a link for each purchase in your connected chat (Telegram, Slack or text message), or by email when none is connected. The link works for 15 minutes and goes only to you, never to the agent.
  • Open the link in your browser, not inside Telegram or another app.
  • Your bank may stop a purchase to check it with you. The agent cannot answer the bank's check: confirm it with your bank, then have the agent try again.
  • With controls on, a policy can also hold a purchase over an amount for your review. The agent is told review_required and retries once you have approved it.

Read how it ended

typescript
const state = await stack.accounts.purchases.get('acct_123', purchase.purchase_id);
// state.status: reserved, awaiting_approval, approved, settled, declined, refused, expired, failed

await stack.accounts.purchases.reportMerchantResult('acct_123', purchase.purchase_id,
  { status: 'completed', order_id: 'A-1001' }, { passportToken });
  • The agent is woken when a purchase is approved, declined, refused, expired or failed. No rule is needed.
  • requires_user_action means the merchant asked for an extra step, such as a bank confirmation. The agent waits and does not try again.
  • stack_report_purchase_result records what the merchant's page showed, such as the order number. It moves no money.
  • The budget is settled at the amount actually charged. STACK never retries a payment.
  • A purchase nobody approves expires after 20 minutes and the reservation is released.

What counts as an action

Starting a checkout is one action, beside the browser steps that led to it. Reading a purchase and reporting the result are free.

When it is refused

  • 409 ACCOUNT_PIECE_NOT_READY - the card has not been added yet.
  • 403 PURCHASE_REFUSED, reason merchant_origin_mismatch - the browser is on another site than the one named.
  • 403 PURCHASE_REFUSED, reason checkout_in_progress - the session already has an open checkout.
  • 403 CARD_NUMBER_REFUSED or CARD_ORIGIN_MISMATCH - a real card number was typed, or the placeholder was typed on another site.
  • 422 CURRENCY_NOT_SUPPORTED - the currency cannot be converted.
  • 402 AGENT_BUDGET_EXCEEDED - the agent has a budget and it cannot cover the amount.
  • 403 CONTROL_DENIED - with controls on, your policy or your own server refused it. Controls are asked as card.checkout, with the merchant and the amount.

Reference

Every field is on Workspace and Browser. Every tool is in the tool reference. The browser steps are in Browser.

Your own card | Docs