> ## 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 a reference 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 payment method

A payment session lets a shopper add a payment method without the agent seeing it. Call `create_payment_session` with the `shopper_id`, the `type` (`card`, `bank-account` or `digital-wallet`) and a `return_url`.

```json theme={null}
{
  "id": "pses_01K8V6Q2...",
  "shopperId": "cus_kosi_asuzu",
  "type": "card",
  "status": "awaiting-enrollment",
  "enrollmentUrl": "https://...",
  "paymentReferenceId": null,
  "returnUrl": "https://example.com/payment-complete",
  "expiresAt": "2026-10-24T10:30:00Z"
}
```

Send the shopper to `enrollmentUrl`. They enter their details on a hosted page, then return to `returnUrl`. Check progress with `get_payment_session`:

| Status | What it means |
| - | - |
| `awaiting-enrollment` | The shopper hasn't finished entering their details. |
| `complete` | Enrollment finished. `paymentReferenceId` holds the reference. |
| `expired` | The shopper didn't finish before `expiresAt`. |

A payment session only adds the payment method. Charging happens later, at checkout.

## Payment references

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

```json theme={null}
{
  "id": "pay_visa_4242",
  "shopperId": "cus_kosi_asuzu",
  "type": "card",
  "label": "Personal Visa",
  "maskedNumber": "****4242",
  "expiresAt": "2027-12-01T00:00:00Z",
  "isDefault": true,
  "createdAt": "2026-01-15T10:00:00Z"
}
```

| Tool | What it does |
| - | - |
| `list_payment_references` | Lists a shopper's active references. |
| `get_payment_reference` | Gets one reference. |
| `revoke_payment_reference` | Revokes a reference so it can't be used again. |

Pass the reference's `id` as `payment_reference_id` to `create_checkout`. The mandate the shopper approves names it as the payer. See [Mandates and approval](https://agentmall.mintlify.site/concepts/mandates-and-approval.md).


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