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

# Transactions

> Every charge on your company's cards and every Vault checkout your agents opened, authenticated with your platform token.

Reconcile your spend, catch up on what your webhook endpoint missed, or show a user their history. A transaction is one purchase attempt: a charge on a card, or a checkout paid from a user's Vault.

Every endpoint here takes your [platform token](https://docs.agentcard.com/api-reference/access-tokens/overview.md). Your credential decides the mode: sandbox credentials read sandbox transactions, production credentials read live ones. There is no mode parameter.

## The transaction object

| Field | Type | Description |
| - | - | - |
| `object` | string | `transaction` |
| `id` | string | The `transaction_id` its webhook events carry. |
| `source` | string | What paid. See [Sources](#sources). |
| `status` | string | See [Statuses](#statuses). |
| `amount` | integer | The figure billed, in the smallest unit of `currency`. A settled Vault checkout reads at what was paid. |
| `currency` | string | The billing currency, lowercase ISO 4217. Null on a simulated sandbox charge. |
| `amount_display` | string | `amount` and `currency` ready to show, such as `$12.50`. |
| `merchant_amount`, `merchant_currency` | integer, string | The merchant's own figure, when it charged in another currency. Otherwise null. |
| `merchant` | string | The merchant's name. |
| `mcc` | string | The merchant category code. Null on a Vault checkout. |
| `decline_reason` | string | Why it was declined, when it was. |
| `user_id` | string | The user it belongs to. Null on a card nobody has claimed yet. |
| `card_id`, `last4` | string | The card charged. Null on a Vault checkout. |
| `vault_card_id` | string | The Vault card used. Null on a card charge. |
| `processor_transaction_id` | string | The processor's reference, the `id` a `transaction.*` webhook event carries. Null on a Vault checkout. |
| `created_at` | string | When it happened, in ISO 8601. |

A transaction never carries a card number or a CVC.

## Sources

| `source` | What paid |
| - | - |
| `issued` | A card your company issued. |
| `added` | A one-time card made from a card the user added. |
| `vault` | A checkout with a card in the user's Vault. |

A Vault checkout paid with a card your company issued is listed once, as the charge on that card.

## Statuses

The statuses use the same words as the [`transaction.*` webhooks](https://docs.agentcard.com/webhooks/cards/overview).

| `status` | Meaning |
| - | - |
| `pending` | Waiting for the user's approval. Vault checkouts only. |
| `authorized` | Approved, not settled yet. |
| `cleared` | Settled. |
| `declined` | Refused by the user or the network. |
| `voided` | Cancelled, expired or reversed. No money moved. |
| `refunded` | Money went back. `amount` is negative. |


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