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

# Vault and credentials

> How payment details stay out of your agent's context, and what your agent works with instead.

Your agent never sees payment details. Card numbers, bank accounts and wallet tokens stay in the vault. Your agent only gets an opaque payment method id that stands for the payment method.

This matters because an agent's context is logged, cached and replayed. A card number in the context ends up in every system that touches it. Keeping secrets in the vault keeps them out of reach.

## Adding a card

Call `write_payment_method` with the `session_id` and either:

* `vault_ref` — an existing Basis Theory card token id, or
* `card` — `{ number, expiration_month, expiration_year, cvc }` to mint a token server-side

The platform stores the mapping and returns a `payment_method_id` the agent can pass to `place_order`. The vault token itself stays internal.

```json theme={null}
{
  "payment_method_id": "pay_…",
  "last4": "4242"
}
```

`place_order` also accepts `vault_ref` or `card` directly (exactly one of `payment_method_id`, `vault_ref`, `card`).

## Adding an address

Call `write_address` with either:

* `vault_ref` — a Basis Theory PII/address token, or
* `fields` — `{ name, line1, city, region, postal, … }` (also vaulted when provided raw)

`place_order` accepts `address_id`, or `address_vault_ref`, or `address` fields.

## Payment methods

A payment method is what your agent uses at checkout. It carries enough to show the shopper which card it is, and nothing that could be used to pay.

| Tool | What it does |
| - | - |
| `write_payment_method` | Saves a card from a Basis Theory token id. |
| `list_payment_methods` | Lists the cards saved with your key. |
| `get_payment_reference` | Gets one card by `payment_method_id`, with `revoked_at`. |
| `revoke_payment_reference` | Revokes a card. `place_order` rejects it afterwards. |

`list_payment_methods` returns id, brand, last4 and expiry only:

```json theme={null}
[
  {
    "payment_method_id": "pmt_8f2c1d0e9b7a4c3e8d6f5a4b3c2d1e0f",
    "brand": "visa",
    "last4": "4242",
    "exp_month": 12,
    "exp_year": 2030
  }
]
```

Pass the `payment_method_id` to `place_order`. AgentMall resolves it to the vault token at checkout time. An unknown, revoked or expired card returns a typed error before anything happens at the merchant. The agent never falls back to a card saved at the merchant. See [Mandates and approval](https://agentmall.mintlify.site/concepts/mandates-and-approval.md).

## Errors

| Code | What it means | What to do |
| - | - | - |
| `vault_not_configured` | Cards aren't enabled for this endpoint or key yet. | Ask us to enable them. |
| `invalid_vault_ref` | `vault_ref` isn't a token id, or the token isn't a card. | Tokenize the card with Basis Theory first. |
| `payment_reference_not_found` | No such token in AgentMall's vault, or no such card for your key. | Tokenize with AgentMall's public key, or list cards. |
| `payment_method_expired` | The card's expiry month has passed. Nothing saved or charged. | Ask your user for another card. |
| `payment_session_not_found` | No payment session with that id for your key. | Create a new one. |
| `vault_unavailable` | The vault didn't answer. | Retry after `retry_after_seconds`. |


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