payments-ai Transactions API

openapi: 3.2.0
info:
  title: Payments AI MoR Merchant Public Transactions API
  version: 1.0.0
  description: Merchant Public API, partner onboarding, and buyer checkout endpoints. Authenticate every call with a Merchant API Key (pai_test_* / pai_live_*). The same key reaches its own merchant resources and those of any sub-merchant it has onboarded via POST /v1/public-api/merchants.
servers:
- url: https://sandbox.mor.payments.ai/api
  description: Sandbox API
tags:
- name: Transactions
paths:
  /v1/public-api/merchants/{merchantId}/transactions:
    post:
      operationId: PublicApiTransactions_createTransaction
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: idempotency-key
        in: header
        required: false
        schema:
          type: string
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiCheckoutPaymentConfirmationResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiCreateTransactionRequest'
      summary: Create transaction
      tags:
      - Transactions
    get:
      operationId: PublicApiTransactions_listTransactions
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: page
        in: query
        required: false
        schema:
          type: integer
          format: int32
        explode: false
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          format: int32
        explode: false
      - name: status
        in: query
        required: false
        schema:
          type: string
        explode: false
      - name: search
        in: query
        required: false
        schema:
          type: string
        explode: false
      - name: created_after
        in: query
        required: false
        schema:
          type: string
          format: date-time
        explode: false
      - name: order_id
        in: query
        required: false
        description: Return only the payments for this order id.
        schema:
          type: string
        explode: false
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiTransactionListResponse'
      summary: List transactions
      tags:
      - Transactions
  /v1/public-api/merchants/{merchantId}/transactions/{id}:
    get:
      operationId: PublicApiTransactions_getTransaction
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiTransactionDetailResponse'
      summary: Get transaction
      tags:
      - Transactions
components:
  schemas:
    PublicApiTransactionHistoryEvent:
      type: object
      required:
      - event
      - timestamp
      properties:
        event:
          type: string
        timestamp:
          type: string
          format: date-time
        id:
          type: string
        amount:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        currency:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        type:
          type: string
        triggeredBy:
          type: string
        message:
          type: string
        details:
          type: string
        occurredAt:
          type: string
          format: date-time
    SharedTypes.MoneyAmountValue:
      type: number
      format: decimal
      description: Decimal money amount for financial values.
    SharedTypes.CurrencyCode:
      type: string
      pattern: ^[a-z]{3}$
      description: ISO 4217 currency code. Always lowercase (e.g. 'usd', 'eur').
    PublicApiCreateTransactionRecurring:
      type: object
      required:
      - amount
      - intervalDays
      properties:
        amount:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        intervalDays:
          type: integer
          format: int32
          minimum: 2
        trialDays:
          type: integer
          format: int32
          minimum: 0
    PublicApiTransactionDetailResponse:
      type: object
      required:
      - id
      - transactionId
      - date
      - orderId
      - method
      - amountIsProvisional
      - breakdown
      - history
      properties:
        id:
          type: string
          description: Canonical merchant-facing transaction id (internal UUID v7).
        transactionId:
          type: string
          description: Deprecated Whop payment id (`pay_…`). Removed on 2027-01-15.
          deprecated: true
        date:
          type: string
          format: date-time
        status:
          type: string
        result:
          type: string
        customerId:
          type: string
        orderId:
          type: string
          nullable: true
          description: Order this payment paid for; `null` when the payment is not tied to an order.
        method:
          $ref: '#/components/schemas/PublicApiTransactionMethod'
        amountIsProvisional:
          type: boolean
          description: 'True while `breakdown.gross` is provisional: the payment provider sent a refund event before the payment''s success event, without the sale total or currency, so the amount is a lower bound or the currency a placeholder. Becomes `false` when the payment succeeds and its final amount replaces the provisional one. `remainingRefundable` is computed from the provisional amount, so it can be lower than the real remaining amount, never higher.'
        breakdown:
          $ref: '#/components/schemas/PublicApiTransactionBreakdown'
        humanReadableWhy:
          type: string
        history:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiTransactionHistoryEvent'
    PublicApiCreateTransactionRequest:
      type: object
      required:
      - amount
      - currency
      - confirmationToken
      - returnUrl
      properties:
        amount:
          allOf:
          - $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
          description: Charge amount in major currency units. Minimums are enforced per currency.
        currency:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        confirmationToken:
          type: string
          description: Payment token (`ctok_…`) from the client SDK. Never send card numbers or PANs.
        returnUrl:
          type: string
        description:
          type: string
        recurring:
          $ref: '#/components/schemas/PublicApiCreateTransactionRecurring'
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Optional string map stored with the charge and in audit logs. At most 25 keys; keys ≤64 chars, values ≤500 chars. Do not send card numbers, CVV, or PAN-like data.
    PublicApiTransactionListItem:
      type: object
      required:
      - id
      - transactionId
      - date
      - amountGross
      - currencyGross
      - amountIsProvisional
      - orderId
      properties:
        id:
          type: string
          description: Canonical merchant-facing transaction id (internal UUID v7).
        transactionId:
          type: string
          description: Deprecated Whop payment id (`pay_…`). Removed on 2027-01-15.
          deprecated: true
        date:
          type: string
          format: date-time
        method:
          $ref: '#/components/schemas/PublicApiTransactionMethod'
        amountGross:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        currencyGross:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        amountIsProvisional:
          type: boolean
          description: 'True while `amountGross` is provisional: the payment provider sent a refund event before the payment''s success event, without the sale total or currency, so the amount is a lower bound or the currency a placeholder. Becomes `false` when the payment succeeds and its final amount replaces the provisional one.'
        amountNet:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        currencyNet:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        status:
          type: string
        type:
          type: string
        errorReason:
          type: string
        orderId:
          type: string
          nullable: true
          description: Order this payment paid for; `null` when the payment is not tied to an order.
    PaginationMeta:
      type: object
      required:
      - totalRecords
      - totalPages
      - currentPage
      - limit
      properties:
        totalRecords:
          type: integer
          format: int32
        totalPages:
          type: integer
          format: int32
        currentPage:
          type: integer
          format: int32
        limit:
          type: integer
          format: int32
    PublicApiTransactionBreakdown:
      type: object
      required:
      - gross
      - grossCurrency
      - refundedAmount
      - refundedCurrency
      - remainingRefundable
      properties:
        gross:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        grossCurrency:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        refundedAmount:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        refundedCurrency:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        remainingRefundable:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        net:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        netCurrency:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
    PublicApiTransactionListResponse:
      type: object
      required:
      - data
      - meta
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiTransactionListItem'
        meta:
          $ref: '#/components/schemas/PaginationMeta'
    PublicApiCheckoutPaymentConfirmationResponse:
      type: object
      required:
      - paymentId
      - clientSecret
      - status
      properties:
        transactionId:
          type: string
          description: Internal PAI transaction id (UUID v7) when the payment row exists in Payments AI.
        paymentId:
          type: string
          description: Deprecated Whop payment id (`pay_…`). Removed on 2027-01-15.
          deprecated: true
        clientSecret:
          type: string
        status:
          type: string
    PublicApiTransactionMethod:
      type: object
      properties:
        scheme:
          type: string
        lastFour:
          type: string
  securitySchemes:
    UserOAuthCredentialAuth:
      type: http
      scheme: Bearer
      description: 'Signed-in user OAuth credential (`pai_mcp_*`) issued through the dashboard consent screen for this API: the authorization and token requests name the RFC 8707 resource `<API_URL>/v1/public-api` (ADR-0020). Credentials issued for the MCP server, or for no resource, are rejected with 401 `auth.invalid_token` and `WWW-Authenticate: Bearer resource_metadata="<API_URL>/.well-known/oauth-protected-resource/v1/public-api", error="invalid_token"`. Valid on the environment that issued it only. Each operation that accepts it names one required permission; a missing permission is 403 `auth.insufficient_scope` with `WWW-Authenticate: Bearer error="insufficient_scope", scope="<permission>"`. A merchant outside the user''s active memberships is 403 `merchant.access_forbidden`; a team role below the operation''s minimum is 403 `team.role_forbidden`.'
    MerchantApiKeyAuth:
      type: http
      scheme: Bearer
      description: 'Merchant API key from Developer Tools → API Keys. Example: `Authorization: Bearer pai_test_...`. Also accepted for any active sub-merchant this key''s own merchant created.'