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.

{
  "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.

{
  "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.