> ## 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. # Get the checkout > Hands any newer merchant evidence to governance first, then returns the checkout, session, governance, payment, and `nextAction`: what the agent should do next. With `maxWaitSeconds`, waits for something to act on: until `nextAction` is not `wait`, or, with `since`, until the envelope `version` differs from it. The wait only reads stored state, and stops if the client goes away. Requires a [buyer key](/api-reference/overview#authentication). ## OpenAPI ````yaml /api-reference/openapi.json get /v1/transactions/{transactionId}/ucp/checkout openapi: 3.0.0 info: title: Sapiom Pay API version: '1.0' description: >- Create buyers, save their cards and authorize transactions. Send your platform key or a buyer key in the `x-api-key` header. servers: - url: https://api.sapiom.ai description: Production security: - api-key: [] tags: - name: Buyers description: One buyer per end user. Called tenants in the API. - name: Cards description: Hosted card setup links and the buyer's saved cards. - name: Spending limits description: Limits on what each card can spend. - name: Merchants description: Check whether Sapiom can buy from a merchant. - name: Transactions description: Create a transaction and drive its UCP checkout. - name: Browser checkout description: Placeholder cards and the relay Browser Pay uses. paths: /v1/transactions/{transactionId}/ucp/checkout: get: tags: - Transactions summary: Get the checkout description: >- Hands any newer merchant evidence to governance first, then returns the checkout, session, governance, payment, and `nextAction`: what the agent should do next. With `maxWaitSeconds`, waits for something to act on: until `nextAction` is not `wait`, or, with `since`, until the envelope `version` differs from it. The wait only reads stored state, and stops if the client goes away. Requires a [buyer key](/api-reference/overview#authentication). operationId: UcpCheckoutController_get parameters: - name: transactionId required: true in: path schema: type: string - name: maxWaitSeconds required: false in: query description: >- Wait up to this many seconds (0 to 25) for something to act on. Default 0. schema: type: string - name: since required: false in: query description: >- A previous envelope's `version`: with `maxWaitSeconds`, answer as soon as the envelope changes from it schema: type: string responses: '200': description: '' content: application/json: schema: $ref: '#/components/schemas/UcpCheckoutEnvelopeDto' '400': description: '`maxWaitSeconds` is not a whole number from 0 to the maximum' '404': description: No checkout for this transaction and tenant security: - api-key: [] components: schemas: UcpCheckoutEnvelopeDto: type: object properties: checkout: type: object nullable: true description: >- Latest merchant checkout accepted as evidence: status, currency, totals, line items, fulfillment methods (destinations, and per group the delivery options with id, title, description, carrier, fulfillment times and totals, as the merchant sent them), messages and expiry. continueUrl is withheld until authorized session: type: object description: >- State, merchant origin, negotiated version, transport and derived completion path governance: type: object description: >- Decision (pending | waiting_approval | authorized | denied | closed), revision, reasons, whether it covers the latest evidence, and the blocker (total_unknown | unsupported_currency | merchant_change_unconfirmed | zero_total | too_many_line_items) when the latest evidence cannot be governed payment: type: object nullable: true description: >- On a checkout funded by the tenant's card: the current revision's payment status (none | pending | authorized | failed | cancelled …), amount, card, typed denial (card_unavailable | no_card_route | verification_required | allowance_insufficient), and the placeholder card to submit once continue_url is released nextAction: type: object description: >- What the agent should do next: wait (governing | paying | merchant, with retryAfterSeconds), refresh (with retryAfterSeconds), update (the merchant messages an update can fix), revise (governance reasons), requires_action (a person must act: kind approval | security_code | allowance_verification | escalation, with url (null until there is a page for it), expiresAt, the card payment denial and the merchant messages), hand_off (continueUrl, and any messages a person must act on), blocked (unsupported_currency | zero_total | too_many_line_items | merchant_unrecoverable | no_continue_url | payment_ended), done, or closed (buyer_canceled or confirmation_expired reason and a message when the transaction confirmation ended) version: type: string description: >- Changes when anything an agent acts on changes; pass it as `since` to wait for a change required: - checkout - session - governance - payment - nextAction - version securitySchemes: api-key: type: apiKey in: header name: x-api-key description: >- Your platform key for buyer management, or a buyer key for everything else. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.