# SDK Purchase Flow

Canonical URL: https://magiccard.ai/docs/guides/sdk-purchase
Markdown URL: https://magiccard.ai/docs/guides/sdk-purchase.md
Summary: Your own agent can search, browse, and reason independently, then call MagicPay SDK to resolve a protected value or run a protected payment action.
Description: How an external agent or backend calls MagicPay SDK when it reaches a payment or other protected step.

## Canonical Answer

Your own agent can search, browse, and reason independently, then call MagicPay SDK to resolve a protected value or run a protected payment action. How an external agent or backend calls MagicPay SDK when it reaches a payment or other protected step. Protected payment and identity data stays behind MagicPay requests instead of entering LLM-visible context.

![Your runtime hands the protected step to MagicPay](https://magiccard.ai/docs-assets/images/guides-sdk-purchase-flow.svg)

## When To Use The SDK

Use the SDK when your application already owns the surrounding agent, browser, worker, or MCP tool and needs a typed MagicPay client for sessions, requests, data resolution, and actions.

## Flow

Your agent runs until it reaches a protected step — payment, login, identity, confirmation — then hands only that step to MagicPay.

1. Create or reuse a MagicPay workflow session.
2. Create a data, action, or choice request with a stable client request id.
3. Wait for user approval or supplied data.
4. Use the returned artifact only in the trusted browser or provider call.
5. Resume the agent workflow after MagicPay reports the result.

Note: Done when: your agent gets a result object back — approved, denied, filled, or failed — and never sees the raw value.

## Minimal SDK Shape

A typical purchase uses sessions, data resolution, action execution, and result waiting.

```ts
const { session } = await client.sessions.create({ type: 'payment' });

// The agent never sees raw data; it asks for a value or a use-approval.
const handle = await client.memory.createRequest(session.id, input);
const result = await client.memory.waitForResult(session.id, handle);
```

## Related

- MagicPay SDK: https://magiccard.ai/docs/integrations/sdk
- API Reference: https://magiccard.ai/docs/api
- MagicPay Memory fill: https://magiccard.ai/docs/components/memory-fill