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

> ## Agent Instructions
> Sapiom Pay is for platforms whose agent shops for many end users. Each end user is a buyer with their own Sapiom key and saved cards.
> Use the buyer's key for every call made on that buyer's behalf. Never use one buyer's key for another user, and never give the agent the platform key.
> Agents call the hosted MCP tools at https://api.sapiom.ai/v1/mcp. Backends call the REST API at https://api.sapiom.ai/v1. Both take the key in an x-api-key header.
> Never ask a buyer for a card number, expiry date or CVV in chat. Buyers enter card details only on Sapiom's hosted pages.
> Follow the nextAction in each transaction result. Action links are secrets for the intended buyer only.
> Use one idempotencyKey per transaction. After a timeout, retry with the same key. Never start a new transaction to escape an uncertain outcome.
> Report an order as placed only when order.outcome is confirmed. If it is unknown, stop and hand off to a person.

# Quickstart: set up your first buyer

> Create a buyer for a test user, save a card for them, and connect your agent as that buyer. No transaction is made.

In a few minutes you will set up one buyer end to end: create the buyer, save a card for them, and connect an agent that acts as them. No transaction is made.

**You need:**

* A platform key that can create buyers (`org.tenants.write`). [Request access](https://docs.sapiom.ai/request-access.md) to get one. Save it as `SAPIOM_PLATFORM_KEY`.
* An agent client that can connect to remote MCP servers. The examples use Claude Code.

**1. Create a buyer**

A buyer represents one of your users. Use your own ID for that user as `externalId`:

```bash theme={null}
curl https://api.sapiom.ai/v1/tenants \
  -H "x-api-key: $SAPIOM_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Test user","externalId":"test-user-1"}'
```

Save the `id` from the response as `BUYER_ID`.

**2. Create a key for the buyer**

```bash theme={null}
curl "https://api.sapiom.ai/v1/tenants/$BUYER_ID/api-keys" \
  -H "x-api-key: $SAPIOM_PLATFORM_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"test-user-1"}'
```

Save `plainKey` from the response as `SAPIOM_BUYER_KEY`. It is shown only once.

**3. Save a card for the buyer**

Create a setup link with the buyer's key:

```bash theme={null}
curl https://api.sapiom.ai/v1/payment-cards/setup-links \
  -H "x-api-key: $SAPIOM_BUYER_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Open the `url` from the response and save a card. In production, you send this link to your user instead.

**4. Connect your agent as the buyer**

```bash theme={null}
claude mcp add --transport http sapiom https://api.sapiom.ai/v1/mcp \
  --header "x-api-key: $SAPIOM_BUYER_KEY"
```

Ask your agent: **"List my Sapiom payment methods."** It shows the card you just saved, with its brand and last four digits.

**5. Check a merchant**

Ask your agent: **"Can Sapiom buy from shop.example?"**, with a real store's domain. The answer is `supported`, `unsupported` or `unknown`. `supported` means the store offers UCP checkout.

You now have a buyer with a saved card and an agent that acts for that buyer. In production, your agent switches keys for each user it serves. See [Connect your agent](https://docs.sapiom.ai/buyers/connect-agent.md).

## Next steps

> **[Authorize a transaction](https://docs.sapiom.ai/transactions/authorize.md)**
>
> Send a merchant checkout and get the buyer's approval.

> **[Manage buyers](https://docs.sapiom.ai/buyers/create-buyers.md)**
>
> Set up buyers for real users in production.


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