> ## 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.

# Save a buyer's card with a hosted setup link

> Send your user a hosted link to save their card, confirm the card is ready, and manage saved cards.

You never touch sensitive card credentials. Create a setup link with the user's buyer key, show it to them in your product flow, and check the card is ready when they finish.

**You need:** the user's [buyer key](https://docs.sapiom.ai/buyers/create-buyers.md).

## Create a setup link

**API**

```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 '{"returnUrl":"https://your-app.example/cards/done","cardholderEmail":"jane@example.com"}'
```

Returns the link's `id`, `status`, `expiresAt` and a one-time `url`.

**Agent (MCP)**

```json theme={null}
{
  "name": "sapiom_add_payment_method",
  "arguments": { "returnUrl": "https://your-app.example/cards/done" }
}
```

Returns `url` and `setupLink: { id, status, expiresAt }`.

| Field | Notes |
| - | - |
| `returnUrl` | Optional. Where the user lands after saving their card. Must be HTTPS, except for `localhost`. |
| `cardholderEmail` | API only. Pre-fills the user's email. They can change it. |
| `expiresInMinutes` | API only. How long the link works: 30 by default, from 5 to 1440. |

Show `url` only to that user. Sapiom returns it once and never stores it, so keep the `id` to check progress.

## What the user sees

The hosted page shows your platform's name and logo and asks for the user's email and card details. After saving, the user goes to your `returnUrl`, if you set one.

![Sapiom's hosted Add a card page showing the Wayfare logo, an email field, card number, expiry and CVV fields, and a Save card button](https://mintcdn.com/sapiom-1f975ca2/vcqXb2-NpI6o1Vkd/images/card-setup-page-v2.png?fit=max\&auto=format\&n=vcqXb2-NpI6o1Vkd\&q=85\&s=37afdb20363f0dd76e09b3b969a53dfb)

The hosted setup page, branded for a platform called Wayfare

## Check the card is ready

After saving, read the link:

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

When `status` is `completed`, `cardId` is the new card. Store it with your user. The card is ready to pay once `GET /v1/payment-cards/{cardId}` shows `status` as `active` and `readiness` as anything other than `not_ready`.

## Pick a card for a transaction

List the user's cards with `sapiom_list_payment_methods` or `GET /v1/payment-cards`. Each card shows its `brand`, `last4`, `isDefault`, `status` and `readiness`.

Suggest the default card if it is active and ready. Once the user picks a card, use that card ID for the whole transaction, including retries.

## Manage saved cards

| Task | API | MCP tool |
| - | - | - |
| List cards | `GET /v1/payment-cards` | `sapiom_list_payment_methods` |
| Read one card | `GET /v1/payment-cards/{cardId}` | |
| Set the default card | `PUT /v1/payment-cards/{cardId}/default` | |
| Remove a card | `DELETE /v1/payment-cards/{cardId}` | `sapiom_delete_payment_method` |

Removing a card stops future transactions with it. It does not cancel or refund past orders.


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