payments-ai Orders API

openapi: 3.2.0
info:
  title: Payments AI MoR Merchant Public Orders 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: Orders
paths:
  /v1/public-api/merchants/{merchantId}/orders:
    post:
      operationId: PublicApiOrders_create
      description: Create an immutable order. A repeat with the same Idempotency-Key returns the original order even when the body differs.
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: idempotency-key
        in: header
        required: false
        description: Optional. Maximum 255 characters. A replay returns the original order and does not compare the body.
        schema:
          type: string
          maxLength: 255
      responses:
        '201':
          description: The request has succeeded and a new resource has been created as a result.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiOrderResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiCreateOrderRequest'
      summary: Create order
      tags:
      - Orders
  /v1/public-api/merchants/{merchantId}/orders/{orderId}:
    get:
      operationId: PublicApiOrders_getById
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: orderId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiOrderResponse'
      summary: Get order
      tags:
      - Orders
components:
  schemas:
    PublicApiOrderResponse:
      type: object
      required:
      - orderId
      - checkoutUrl
      - currency
      - amountDue
      - recurringAmount
      - billingPeriod
      - periodLength
      - trialPeriodDays
      - items
      - metadata
      - status
      - transactionId
      properties:
        orderId:
          type: string
        checkoutUrl:
          type: string
        currency:
          $ref: '#/components/schemas/SharedTypes.CurrencyCode'
        amountDue:
          allOf:
          - $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
          description: Amount the buyer owes today, before tax.
        recurringAmount:
          type: number
          allOf:
          - $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
          nullable: true
          description: Later renewal total. Null when the order has no recurring item.
        billingPeriod:
          allOf:
          - $ref: '#/components/schemas/BillingPeriod'
          nullable: true
        periodLength:
          type: integer
          format: int32
          nullable: true
        trialPeriodDays:
          type: integer
          format: int32
          nullable: true
        items:
          type: array
          items:
            $ref: '#/components/schemas/PublicApiOrderItemResponse'
        metadata:
          type: object
          additionalProperties:
            type: string
          description: The metadata sent on create, exactly as sent. `{}` when none was sent.
        status:
          $ref: '#/components/schemas/PublicApiOrderStatus'
        transactionId:
          type: string
          nullable: true
          description: Internal Payments AI transaction id when a payment row exists for this order (excluding pending or failed). Null while unpaid or between checkout confirm and webhook linkage.
        subscriptionId:
          type: string
          description: Present when the order has exactly one recurring line item and one subscription row is linked.
        subscriptionIds:
          type: array
          items:
            type: string
          description: Present when the order has two or more recurring line items, or when multiple subscription rows are linked.
      description: Order returned by API-key create and read. No mount fields and no processor purchase URL.
    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').
    PublicApiOrderStatus:
      type: string
      enum:
      - open
      - completed
      - expired
      description: Payment lifecycle for a merchant order read. `open` includes unpaid and paid-awaiting-webhook (checkout confirmed, transaction row not yet linked).
    BillingPeriod:
      type: string
      enum:
      - day
      - week
      - month
      - year
    PublicApiOrderItemResponse:
      type: object
      required:
      - label
      - unitPrice
      - quantity
      - lineTotal
      - itemType
      properties:
        label:
          type: string
        unitPrice:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        quantity:
          type: integer
          format: int32
          minimum: 1
        lineTotal:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        itemType:
          $ref: '#/components/schemas/PublicApiOrderItemType'
        billingPeriod:
          $ref: '#/components/schemas/BillingPeriod'
        periodLength:
          type: integer
          format: int32
          minimum: 1
      description: One line returned after create or merchant read.
    PublicApiCreateOrderInvoiceItem:
      type: object
      required:
      - invoiceId
      properties:
        invoiceId:
          type: string
      description: Invoice line. The price comes from the invoice. Send only invoiceId. The invoice must be open or past due, have a positive amount, and belong to this merchant.
    PublicApiCreateOrderPlanItem:
      type: object
      required:
      - planId
      - quantity
      properties:
        planId:
          type: string
        quantity:
          type: integer
          format: int32
          minimum: 1
          maximum: 10000
      description: Catalogue line. Price comes from the plan. Do not send label or unitPrice on this shape.
    PublicApiCreateOrderCustomItem:
      type: object
      required:
      - label
      - unitPrice
      - quantity
      - type
      properties:
        label:
          type: string
          minLength: 1
          maxLength: 255
        unitPrice:
          allOf:
          - $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
          maximum: 100000
          description: Must be greater than 0 and at most 100000. unitPrice x quantity, and the order total, are also capped at 100000.
          minimum: 0
          exclusiveMinimum: true
        quantity:
          type: integer
          format: int32
          minimum: 1
          maximum: 10000
        type:
          $ref: '#/components/schemas/PublicApiOrderItemType'
        billingPeriod:
          allOf:
          - $ref: '#/components/schemas/BillingPeriod'
          description: Required when type is recurring. Omit for one_time.
        periodLength:
          type: integer
          format: int32
          minimum: 1
          maximum: 365
          description: 'Required when type is recurring. Omit for one_time. At most one year of billingPeriod: 365 day, 52 week, 12 month, 1 year.'
        trialPeriodDays:
          type: integer
          format: int32
          minimum: 1
          maximum: 730
          description: Optional free trial in days for recurring custom lines only. Omit when there is no trial. At most 730 days. When set, amountDue today can be 0 until the trial ends. All recurring lines in the order must use the same trial length.
      description: Caller-priced line. Accepted only on this API-key route. When type is recurring, send both billingPeriod and periodLength. Omit both for one_time.
    PublicApiCreateOrderRequest:
      type: object
      required:
      - currency
      - items
      properties:
        currency:
          allOf:
          - $ref: '#/components/schemas/SharedTypes.CurrencyCode'
          description: One of usd, eur, gbp, pln, chf, sek, dkk, nok, cad, aud, jpy. jpy has no minor unit, so its amounts are whole yen (500, not 500.5).
        items:
          type: array
          items:
            anyOf:
            - $ref: '#/components/schemas/PublicApiCreateOrderPlanItem'
            - $ref: '#/components/schemas/PublicApiCreateOrderCustomItem'
            - $ref: '#/components/schemas/PublicApiCreateOrderInvoiceItem'
          minItems: 1
          maxItems: 20
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Optional. Your own key/value pairs for this order, such as a CRM or ERP order number. Flat object with string values only. At most 50 keys; each key is 1 to 40 characters and each value is at most 500 characters, else 400 `Validation failed`. Keys and values are stored and returned exactly as sent. Omitted means `{}`. Returned on order reads and on `payment.*` and `subscription.*` webhooks that name this order. Never sent to the payment processor.
    PublicApiOrderItemType:
      type: string
      enum:
      - one_time
      - recurring
  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.'