# Entities

Canonical URL: https://magiccard.ai/docs/reference/entities
Markdown URL: https://magiccard.ai/docs/reference/entities.md
Summary: Use this page when you need the stable nouns used across product, SDK, API, and agent flows.
Description: Reference definitions for payment sessions, requests, events, Memory, and MagicCards.

## Canonical Answer

Use this page when you need the stable nouns used across product, SDK, API, and agent flows. Reference definitions for payment sessions, requests, events, Memory, and MagicCards. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context.

![How sessions, requests, Memory and MagicCard relate](https://magiccard.ai/docs-assets/images/reference-entities-map.svg)

## Payment Session

A payment operation initiated by an agent. It groups the user intent, provider work, requests, events, payment execution state, and final outcome.

## Request

The human-in-the-loop mechanism raised during session execution. Requests handle payment approvals, Memory reads and writes, purchase choices, and protected actions.

## Event

A recorded step in session execution. Events make the session inspectable and help the agent or UI show progress.

## Memory item

A reusable user-owned record such as a login, address, passport, or payment method that holds related fields. Fields can be open profile facts or secrets; the secret marker adds stricter handling (redaction, logging, and extra approval).

## MagicCard

The user-facing payment instrument and balance abstraction that hides individual payment rails from the user.

## Related

- Glossary: https://magiccard.ai/docs/glossary
- API Reference: https://magiccard.ai/docs/api
- Omnichannel UI: https://magiccard.ai/docs/components/omnichannel-ui