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

# Sapiom Pay MCP tools reference

Your agent calls these tools through the hosted MCP server at `https://api.sapiom.ai/v1/mcp`, connected with the [buyer's key](https://docs.sapiom.ai/buyers/connect-agent.md). Argument names are case-sensitive.

| Tool | Purpose | Permission |
| - | - | - |
| `sapiom_check_transaction_compatibility` | Check a merchant | `org.transactions.read` |
| `sapiom_list_payment_methods` | List cards | `org.transactions.read` |
| `sapiom_add_payment_method` | Create a card setup link | `org.transactions.write` |
| `sapiom_delete_payment_method` | Remove a card | `org.transactions.write` |
| `sapiom_request_transaction` | Start or resume a transaction | `org.transactions.write` |
| `sapiom_get_transaction` | Read a transaction | `org.transactions.read` |
| `sapiom_update_transaction` | Replace a transaction's checkout | `org.transactions.write` |
| `sapiom_cancel_transaction` | Cancel a transaction's checkout | `org.transactions.write` |
| `sapiom_get_card_spending_limits` | Read a card's spending limits | `org.read` |
| `sapiom_set_card_spending_limits` | Set a card's spending limits | `org.write` |

## sapiom\_check\_transaction\_compatibility

`{ "domain": "shop.example" }`. Takes a bare domain or HTTPS origin.

Returns `merchant`, `status`, `reason`, `protocol`, `capabilities: [{ name, supported }]`, `checkedAt`, `expiresAt` and `retryAfterSeconds`.

| `status` | `reason` |
| - | - |
| `supported` | `compatible_ucp_profile`. Use only capabilities marked `supported: true`. |
| `unsupported` | `no_manifest`, `no_compatible_version` or `no_checkout` |
| `unknown` | `timeout`, `fetch_failed`, `upstream_error` or `invalid_profile`. Honor `retryAfterSeconds`. |

## sapiom\_list\_payment\_methods

`{}`. Returns `{ data: [...] }`, newest first, with pending and active cards. Each card includes `id`, `status`, `brand`, `last4`, `expMonth`, `expYear`, `isDefault` and `readiness`. A card can pay when `status` is `active` and `readiness` is not `not_ready`. Card numbers are never returned.

## sapiom\_add\_payment\_method

`{ "returnUrl": "https://your-app.example/cards/done" }`. `returnUrl` is optional: HTTPS, or HTTP for localhost, up to 2,048 characters.

Returns `url` and `setupLink: { id, status, expiresAt }`, plus instructions in `nextStep`. `url` is returned only once. See [Vault a card](https://docs.sapiom.ai/cards/vault-a-card.md).

## sapiom\_delete\_payment\_method

`{ "cardId": "<uuid>" }`. Returns `{ cardId, status, message }`. Calling again with the same ID safely retries cleanup. Removal does not cancel or refund orders.

## sapiom\_request\_transaction

| Argument | Notes |
| - | - |
| `idempotencyKey` | Required, up to 200 characters. One per transaction. |
| `merchantOrigin` | Required HTTPS origin. |
| `checkout` | Required UCP checkout create request, with no payment data. |
| `paymentMethodId` | The card's `id`. Send this or `setupLinkId`. |
| `setupLinkId` | Open setup link ID. Returns `status: setup_required`, with `nextAction.type` `complete_payment_method_setup`, until setup completes. |

Returns the transaction view. See [Authorize a transaction](https://docs.sapiom.ai/transactions/authorize.md).

## sapiom\_get\_transaction

`{ "transactionId": "<uuid>", "since": "<version>", "waitSeconds": 20 }`. `since` and `waitSeconds` (0 to 22, default 0) are optional. Reads stored state only; it never pays or refreshes the merchant.

## sapiom\_update\_transaction

`{ "transactionId", "version", "idempotencyKey", "checkout" }`. `checkout` replaces the whole checkout, so build it from the latest transaction plus your change. Changing items or totals can require the buyer to approve again.

## sapiom\_cancel\_transaction

`{ "transactionId", "idempotencyKey" }`. Cancels an unfinished checkout. It cannot stop a completion in progress or refund a placed order.

## What transaction tools return

All four transaction tools return the same object. This one is ready for your browser worker to pay:

```json theme={null}
{
  "transactionId": "00000000-0000-4000-8000-000000000003",
  "version": "7:4:authorized",
  "checkout": {
    "merchantOrigin": "https://shop.example",
    "status": "ready_for_complete",
    "currency": "USD",
    "totals": [{ "type": "total", "amount": 2999 }],
    "lineItems": [
      { "id": "line-1", "itemId": "merchant-product-id", "title": "Notebook", "quantity": 1, "unitPriceMinor": 2999 }
    ],
    "fulfillmentMethods": [],
    "expiresAt": "2026-10-23T18:00:00.000Z",
    "revision": 2,
    "governed": true,
    "decision": "authorized",
    "reasons": []
  },
  "localSession": { "state": "open" },
  "payment": {
    "status": "authorized",
    "amount": "29.99",
    "paymentMethodId": "00000000-0000-4000-8000-000000000001",
    "denial": null
  },
  "order": { "outcome": "not_confirmed", "evidence": null, "observationSeq": 4 },
  "nextAction": {
    "type": "payment_ready",
    "actor": "agent",
    "continueUrl": "https://shop.example/checkouts/abc123",
    "buyerMessages": []
  }
}
```

`totals` and `unitPriceMinor` are in minor units (cents), while `payment.amount` is a decimal string. Pass `version` as `since` on your next read. Other `nextAction` types are listed in [Authorize a transaction](https://docs.sapiom.ai/transactions/authorize.md#follow-nextaction).

## Spending-limit tools

> [!NOTE]
>
> These tools need a key that can manage limits, such as your [platform key](https://docs.sapiom.ai/api-reference/overview.md#authentication). Buyer keys can't call them, so an agent connected with a [buyer's key](https://docs.sapiom.ai/buyers/connect-agent.md) can't read or raise its own limits.

### sapiom\_get\_card\_spending\_limits

`{ "cardId": "<uuid>" }`. Returns the card's three limits, the saved `version`, and `usage`, which shows what the period and date-range limits have `used` and have `remaining`. Same as [Get spending limits](https://docs.sapiom.ai/api-reference/spending-limits/get-spending-limits.md).

### sapiom\_set\_card\_spending\_limits

`{ "cardId", "version", "purchaseLimit", "recurringLimit", "customLimit" }`. Replaces all three limits, so send `null` for any you don't want, with the `version` you read (`0` the first time). Same as [Set spending limits](https://docs.sapiom.ai/api-reference/spending-limits/set-spending-limits.md). See [Spending limits](https://docs.sapiom.ai/controls/spending-limits.md) for each limit's shape.


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