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

# Cancel a transaction

> Cancels the transaction. For a UCP checkout, Sapiom cancels the merchant checkout first, then the card payment. Cancelling again does nothing. Returns `409` once it's too late, such as after the card was relayed. It doesn't refund an order. Requires a [buyer key](/api-reference/overview#authentication).



## OpenAPI

````yaml /api-reference/openapi.json post /v1/transactions/{transactionId}/cancel
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, read and cancel a transaction, and drive its UCP checkout.
  - name: Browser checkout
    description: The relay Browser Pay uses.
paths:
  /v1/transactions/{transactionId}/cancel:
    post:
      tags:
        - Transactions
      summary: Cancel a transaction
      description: >-
        Cancels the transaction. For a UCP checkout, Sapiom cancels the merchant
        checkout first, then the card payment. Cancelling again does nothing.
        Returns `409` once it's too late, such as after the card was relayed. It
        doesn't refund an order. Requires a [buyer
        key](/api-reference/overview#authentication).
      operationId: TransactionController_cancelPurchase
      parameters:
        - name: transactionId
          required: true
          in: path
          schema:
            type: string
        - name: Idempotency-Key
          required: false
          in: header
          schema:
            type: string
          description: >-
            Optional. Sapiom sends it with the merchant cancel. Reuse it when
            you retry.
      responses:
        '200':
          description: The cancelled transaction
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/TransactionResponseDto'
        '404':
          description: Transaction not found
        '409':
          description: >-
            `card_relayed`: the card was relayed or is being relayed, so it may
            reach the merchant; complete the transaction instead.
            `not_a_browser_purchase`: the transaction buys nothing.
            `transaction_ended`: it is completed or denied. `payment_settled`:
            its payment has completed or is settling. A UCP purchase also
            answers with the checkout route's codes (`session_closed`,
            `operation_in_flight`, …).
      security:
        - api-key: []
components:
  schemas:
    TransactionResponseDto:
      type: object
      properties:
        returnUrl:
          type: string
          nullable: true
          description: Integrator-provided return destination for hosted transaction steps
        nextAction:
          type: object
          description: >-
            The next step in one vocabulary (`type` + `actor`: `wait`,
            `buyer_security_code`, `approval`, `payment_ready`, `closed`, …),
            always present for a purchase. For a transaction that buys nothing,
            only an approval or security-code step, absent when nobody needs to
            act. Links are derived at read time.
        purchase:
          type: object
          description: >-
            For a purchase: what is bought, from whom, for how much, and who
            said so (`assertedBy`: `merchant` for the merchant's own checkout
            answer, `agent` for the agent's unchecked statement). Read from
            durable records; absent for a transaction that buys nothing.
          example:
            type: ucp_checkout
            assertedBy: merchant
            merchant:
              origin: https://shop.example
            total:
              amount: '19.99'
              currency: USD
            lineItems:
              - title: Mug
                itemId: item_123
                quantity: 1
                unitAmount: '19.99'
            revision: 1
        order:
          type: object
          nullable: true
          description: >-
            For a purchase: the merchant-confirmed order outcome (`confirmed`,
            `not_confirmed`, `unknown`). Null for a browser purchase, which has
            no order confirmation.
        version:
          type: string
          description: >-
            For a purchase: changes whenever anything the caller acts on
            changes. Pass it back as `since` to wait for the next change.
        approvals:
          type: object
          description: >-
            Approval obligations and linked successor attempts; inspect an
            approval for current authority
        id:
          type: string
          description: Transaction ID
          example: 123e4567-e89b-12d3-a456-426614174000
        tenantId:
          type: string
          description: Organization ID
          example: 123e4567-e89b-12d3-a456-426614174000
        serviceName:
          type: string
          description: Service identifier
          example: openai
        actionName:
          type: string
          description: Action being performed
          example: completion
        resourceName:
          type: string
          description: Resource being accessed
          example: gpt-4
        serviceId:
          type: string
          nullable: true
          description: Service entity ID (foreign key reference)
          example: 123e4567-e89b-12d3-a456-426614174000
        status:
          enum:
            - pending
            - preparing
            - waiting_approval
            - authorized
            - completed
            - denied
            - cancelled
            - needs_revision
          type: string
          description: Transaction status
          example: authorized
        requiresPayment:
          type: boolean
          description: Whether the transaction requires payment
          example: true
        qualifiers:
          type: object
          description: Additional qualifiers for the transaction
          example:
            model: gpt-4
            tokens: 1000
        metadata:
          type: object
          description: Additional metadata for the transaction
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp
          example: '2024-01-01T00:00:00.000Z'
        updatedAt:
          format: date-time
          type: string
          description: Last update timestamp
          example: '2024-01-01T00:00:00.000Z'
        authorizedAt:
          format: date-time
          type: string
          description: Authorization timestamp
          example: '2024-01-01T00:00:00.000Z'
        completedAt:
          format: date-time
          type: string
          description: Completion timestamp
          example: '2024-01-01T00:00:00.000Z'
        outcome:
          enum:
            - success
            - error
          type: string
          description: Transaction outcome (set when completed)
          example: success
        currentPaymentTransactionId:
          type: string
          nullable: true
          description: Current payment transaction ID if transaction requires payment
          example: 123e4567-e89b-12d3-a456-426614174000
        payment:
          description: Payment transaction details when transaction requires payment
          allOf:
            - $ref: '#/components/schemas/PaymentTransactionResponseDto'
        trace:
          description: Trace information for workflow grouping
          allOf:
            - $ref: '#/components/schemas/TraceResponseDto'
        agentId:
          type: string
          nullable: true
          description: Agent ID if transaction is associated with an agent
          example: 123e4567-e89b-12d3-a456-426614174000
        agent:
          description: Agent information if transaction is associated with an agent
          allOf:
            - $ref: '#/components/schemas/AgentResponseDto'
      required:
        - id
        - tenantId
        - serviceName
        - actionName
        - resourceName
        - status
        - requiresPayment
        - createdAt
        - updatedAt
    PaymentTransactionResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Payment transaction ID
          example: 123e4567-e89b-12d3-a456-426614174000
        transactionId:
          type: string
          description: Transaction ID this payment belongs to
          example: 123e4567-e89b-12d3-a456-426614174000
        fiatAmount:
          type: string
          description: The payment amount in USD, as a decimal string.
        status:
          enum:
            - pending
            - preparing
            - authorized
            - settling
            - completed
            - failed
            - cancelled
          type: string
          description: Payment status
          example: authorized
        fundingSource:
          type: string
          description: '`external_card`: the buyer''s saved card pays.'
          enum:
            - external_card
        paymentCardId:
          type: string
          nullable: true
          description: The card paying a card-funded payment
          format: uuid
        credentialRoute:
          type: string
          description: >-
            `real_card_number`: the relay puts the real card into the merchant's
            payment request.
          enum:
            - real_card_number
          nullable: true
        placeholder:
          description: >-
            An authorized card payment's placeholder card, while it can still be
            relayed. Submit it in the merchant's card form; the relay swaps it
            for the real credential once.
          allOf:
            - $ref: '#/components/schemas/CardPlaceholderDto'
        reason:
          type: string
          nullable: true
          description: >-
            Why the payment failed, when it is a public code: `sapiom_error` (a
            fault on Sapiom's side; report the transaction's requestId). Absent
            otherwise; a transaction's checkout `nextAction` says why it ended.
          enum:
            - sapiom_error
          example: sapiom_error
        createdAt:
          format: date-time
          type: string
          description: Creation timestamp
          example: '2024-01-01T00:00:00.000Z'
        updatedAt:
          format: date-time
          type: string
          description: Last update timestamp
          example: '2024-01-01T00:00:00.000Z'
        authorizedAt:
          format: date-time
          type: string
          nullable: true
          description: Authorization timestamp
          example: '2024-01-01T00:00:00.000Z'
      required:
        - id
        - transactionId
        - fiatAmount
        - status
        - createdAt
        - updatedAt
    TraceResponseDto:
      type: object
      properties:
        id:
          type: string
          description: Trace ID
          example: 123e4567-e89b-12d3-a456-426614174000
        externalId:
          type: string
          nullable: true
          description: Optional user-supplied external ID for trace correlation
          example: checkout-session-abc123
      required:
        - id
    AgentResponseDto:
      type: object
      properties:
        id:
          type: string
        tenantId:
          type: string
        label:
          type: string
        name:
          type: string
        description:
          type: string
          nullable: true
        status:
          type: string
        createdAt:
          format: date-time
          type: string
        updatedAt:
          format: date-time
          type: string
      required:
        - id
        - tenantId
        - label
        - name
        - status
        - createdAt
        - updatedAt
    CardPlaceholderDto:
      type: object
      properties:
        number:
          type: string
          description: Card number shaped like the real card's brand; not a real card
          example: '4000123412341234'
        expMonth:
          type: number
          example: 7
        expYear:
          type: number
          example: 2029
        cvc:
          type: string
          example: '123'
        brand:
          type: string
          example: visa
        expiresAt:
          type: string
          description: After this the placeholder no longer relays
          example: '2026-10-13T13:00:00.000Z'
        injectionRef:
          type: string
          description: The armed injection the relay looks the placeholder up by
        transactionId:
          type: string
          description: The transaction the placeholder is relayed through
      required:
        - number
        - expMonth
        - expYear
        - cvc
        - brand
        - expiresAt
        - injectionRef
        - transactionId
  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.