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

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.

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:

{
  "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.

Spending-limit tools

These tools need a key that can manage limits, such as your platform key. Buyer keys can’t call them, so an agent connected with a buyer’s key 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.

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. See Spending limits for each limit’s shape.

Overview

REST API

MCP and SDK

Errors

Sapiom Pay MCP tools reference

sapiom_check_transaction_compatibility

sapiom_list_payment_methods

sapiom_add_payment_method

sapiom_delete_payment_method

sapiom_request_transaction

sapiom_get_transaction

sapiom_update_transaction

sapiom_cancel_transaction

What transaction tools return

Spending-limit tools

sapiom_get_card_spending_limits

sapiom_set_card_spending_limits

​sapiom_check_transaction_compatibility

​sapiom_list_payment_methods

​sapiom_add_payment_method

​sapiom_delete_payment_method

​sapiom_request_transaction

​sapiom_get_transaction

​sapiom_update_transaction

​sapiom_cancel_transaction

​What transaction tools return

​Spending-limit tools

​sapiom_get_card_spending_limits

​sapiom_set_card_spending_limits

sapiom_check_transaction_compatibility

sapiom_list_payment_methods

sapiom_add_payment_method

sapiom_delete_payment_method

sapiom_request_transaction

sapiom_get_transaction

sapiom_update_transaction

sapiom_cancel_transaction

What transaction tools return

Spending-limit tools

sapiom_get_card_spending_limits

sapiom_set_card_spending_limits