payments-ai Checkout API

openapi: 3.2.0
info:
  title: Payments AI MoR Merchant Public Checkout 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: Checkout
paths:
  /v1/public-api/merchants/{merchantId}/checkout/customization:
    get:
      operationId: PublicApiCheckoutCustomizationApi_getCustomization
      description: 'Auth: Merchant API key, or user OAuth credential with `checkout:read` · tenant `{merchantId}` · any team member · 401 `auth.invalid_token` · 403 `auth.insufficient_scope`, `merchant.access_forbidden`.'
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiCheckoutCustomizationResponse'
      tags:
      - Checkout
      security:
      - MerchantApiKeyAuth: []
      - UserOAuthCredentialAuth: []
      summary: Get customization
    patch:
      operationId: PublicApiCheckoutCustomizationApi_updateCustomization
      description: 'Auth: Merchant API key, or user OAuth credential with `checkout:write` · tenant `{merchantId}` · Owner, Admin, or Editor (user credential) · 401 `auth.invalid_token` · 403 `auth.insufficient_scope`, `merchant.access_forbidden`, `team.role_forbidden`.'
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiCheckoutCustomizationResponse'
      tags:
      - Checkout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiUpdateCheckoutCustomizationRequest'
      security:
      - MerchantApiKeyAuth: []
      - UserOAuthCredentialAuth: []
      summary: Update customization
  /v1/public-api/merchants/{merchantId}/checkout/logo/confirm:
    post:
      operationId: PublicApiCheckoutCustomizationApi_confirmLogo
      description: 'Step 2 of 2: confirm the uploaded logo and store it on the customization. The backend never fetches a client-supplied URL. Auth: Merchant API key, or user OAuth credential with `checkout:write` · tenant `{merchantId}` · Owner, Admin, or Editor (user credential) · 401 `auth.invalid_token` · 403 `auth.insufficient_scope`, `merchant.access_forbidden`, `team.role_forbidden`.'
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiConfirmCheckoutLogoResponse'
      tags:
      - Checkout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiConfirmCheckoutLogoRequest'
      security:
      - MerchantApiKeyAuth: []
      - UserOAuthCredentialAuth: []
      summary: Confirm logo
  /v1/public-api/merchants/{merchantId}/checkout/logo/upload-url:
    post:
      operationId: PublicApiCheckoutCustomizationApi_createLogoUploadUrl
      description: 'Step 1 of 2: mint a logo upload URL. Auth: Merchant API key, or user OAuth credential with `checkout:write` · tenant `{merchantId}` · Owner, Admin, or Editor (user credential) · 401 `auth.invalid_token` · 403 `auth.insufficient_scope`, `merchant.access_forbidden`, `team.role_forbidden`.'
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiCheckoutLogoUploadUrlResponse'
      tags:
      - Checkout
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiCheckoutLogoUploadUrlRequest'
      security:
      - MerchantApiKeyAuth: []
      - UserOAuthCredentialAuth: []
      summary: Create logo upload url
  /v1/public-api/merchants/{merchantId}/checkout/plans/{planId}:
    get:
      operationId: PublicApiCheckout_resolveByPlanId
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: planId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiCheckoutByPlanResponse'
      summary: Get checkout by plan
      tags:
      - Checkout
  /v1/public-api/merchants/{merchantId}/checkout/plans/{planId}/confirm:
    post:
      operationId: PublicApiCheckout_confirmPaymentByPlanId
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: planId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiCheckoutPaymentConfirmationResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiConfirmCheckoutPaymentRequest'
      summary: Confirm payment by plan id
      tags:
      - Checkout
  /v1/public-api/merchants/{merchantId}/checkout/plans/{planId}/promo-code-preview:
    post:
      operationId: PublicApiCheckout_previewPromoCodeByPlanId
      description: Read-only promo quote for this plan. Same result as the deprecated promo-codes path.
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: planId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiPreviewCheckoutPromoCodeResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiPreviewCheckoutPromoCodeRequest'
      summary: Preview promo code by plan id
      tags:
      - Checkout
  /v1/public-api/merchants/{merchantId}/checkout/plans/{planId}/promo-codes:
    post:
      operationId: PublicApiCheckout_applyPromoCodeByPlanId
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: planId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiApplyCheckoutPromoCodeResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiApplyCheckoutPromoCodeRequest'
      deprecated: true
      summary: Apply promo code by plan id
      tags:
      - Checkout
  /v1/public-api/merchants/{merchantId}/checkout/plans/{planId}/receipts/{receiptId}:
    get:
      operationId: PublicApiCheckout_getReceiptByPlanId
      description: Receipt lookup by payment reference. Prefer internal transaction UUID v7 in `receiptId`; legacy Whop `pay_…` ids are deprecated until removal on 2027-01-15.
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: planId
        in: path
        required: true
        schema:
          type: string
      - name: receiptId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiCheckoutReceiptResponse'
      summary: Get checkout receipt
      tags:
      - Checkout
  /v1/public-api/merchants/{merchantId}/checkout/plans/{planId}/session:
    post:
      operationId: PublicApiCheckout_createSessionByPlanId
      parameters:
      - name: merchantId
        in: path
        required: true
        schema:
          type: string
      - name: planId
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request has succeeded.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PublicApiCheckoutSessionResponse'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PublicApiCreateCheckoutSessionRequest'
      summary: Create checkout session
      tags:
      - Checkout
components:
  schemas:
    PublicApiApplyCheckoutPromoCodeResponse:
      type: object
      required:
      - code
      - promoType
      - amountOff
      - discountAmount
      - subtotal
      - total
      - renewalTotal
      - currency
      - billingPeriod
      - billingPeriodLength
      - billingPeriodUnit
      properties:
        code:
          type: string
        promoType:
          type: string
        amountOff:
          type: string
        discountAmount:
          type: number
          format: double
        subtotal:
          type: number
          format: double
        total:
          type: number
          format: double
        renewalTotal:
          type: number
          format: double
          nullable: true
        currency:
          type: string
        billingPeriod:
          type: string
        billingPeriodLength:
          type: integer
          format: int32
          nullable: true
        billingPeriodUnit:
          type: string
          nullable: true
    PublicApiPreviewCheckoutPromoCodeResponse:
      type: object
      required:
      - code
      - promoType
      - amountOff
      - discountAmount
      - subtotal
      - total
      - renewalTotal
      - currency
      - billingPeriod
      - billingPeriodLength
      - billingPeriodUnit
      properties:
        code:
          type: string
        promoType:
          type: string
        amountOff:
          type: string
        discountAmount:
          type: number
          format: double
        subtotal:
          type: number
          format: double
        total:
          type: number
          format: double
        renewalTotal:
          type: number
          format: double
          nullable: true
        currency:
          type: string
        billingPeriod:
          type: string
        billingPeriodLength:
          type: integer
          format: int32
          nullable: true
        billingPeriodUnit:
          type: string
          nullable: true
    PublicApiCheckoutLogoUploadUrlRequest:
      type: object
      required:
      - fileName
      - contentType
      properties:
        fileName:
          type: string
        contentType:
          type: string
          enum:
          - image/png
          - image/jpeg
          - image/jpg
          - image/webp
      description: Request a short-lived presigned S3 PUT URL for a checkout logo. Upload size limit is 5 MB, checked at confirm.
    PublicApiCheckoutCustomizationResponse:
      type: object
      required:
      - merchantId
      - customization
      properties:
        merchantId:
          type: string
        customization:
          $ref: '#/components/schemas/PublicApiCheckoutCustomization'
    PublicApiCheckoutSessionResponse:
      type: object
      required:
      - sessionId
      properties:
        sessionId:
          type: string
        purchaseUrl:
          type: string
          nullable: true
    PublicApiCreateCheckoutSessionRequest:
      type: object
      required:
      - returnUrl
      properties:
        returnUrl:
          type: string
    PublicApiCheckoutCustomizationPatch:
      type: object
      properties:
        themeMode:
          type: string
          enum:
          - light
          - dark
          nullable: true
        backgroundColor:
          type: string
          nullable: true
        buttonColor:
          type: string
          nullable: true
        buttonTextColor:
          type: string
          nullable: true
        fontColor:
          type: string
          nullable: true
        fontFamily:
          type: string
          enum:
          - Inter
          - Roboto
          nullable: true
        inputStyle:
          type: string
          enum:
          - rounded
          - square
          nullable: true
    PublicApiCheckoutLogoUploadUrlResponse:
      type: object
      required:
      - uploadUrl
      - path
      - expiresAt
      properties:
        uploadUrl:
          type: string
          description: Presigned S3 PUT URL. Upload the raw bytes with the same Content-Type used when minting.
        path:
          type: string
          description: Storage key to echo back to the confirm step. Bound to the merchant.
        expiresAt:
          type: string
          format: date-time
    PublicApiApplyCheckoutPromoCodeRequest:
      type: object
      required:
      - code
      properties:
        code:
          type: string
          description: Buyer-entered promo/discount code (case-insensitive; stored uppercased).
    PublicApiUpdateCheckoutCustomizationRequest:
      type: object
      required:
      - customization
      properties:
        customization:
          allOf:
          - $ref: '#/components/schemas/PublicApiCheckoutCustomizationPatch'
          description: Merged over the stored customization; omitted fields keep their value (ADR-0008). Explicit `null` resets a field to its default. The logo is set only through the logo upload steps.
    PublicApiConfirmCheckoutPaymentRequest:
      type: object
      required:
      - confirmationToken
      - returnUrl
      properties:
        confirmationToken:
          type: string
        returnUrl:
          type: string
        promoCode:
          type: string
          description: Optional buyer-entered promo/discount code. Resolved server-side before charging.
    PublicApiCheckoutCustomization:
      type: object
      properties:
        themeMode:
          type: string
          enum:
          - light
          - dark
        backgroundColor:
          type: string
        buttonColor:
          type: string
        buttonTextColor:
          type: string
        fontColor:
          type: string
          description: Primary body/content text color for the merchant product panel.
        logoUrl:
          type: string
          description: Presigned URL resolved on the read side from the stored logo.
        logoExpiresAt:
          type: string
          format: date-time
          description: ISO-8601 UTC expiry of `logoUrl`.
        fontFamily:
          type: string
          enum:
          - Inter
          - Roboto
        inputStyle:
          type: string
          enum:
          - rounded
          - square
          description: Corner radius preset for checkout inputs (`rounded` maps to 8px, `square` to 0).
    SharedTypes.MoneyAmountValue:
      type: number
      format: decimal
      description: Decimal money amount for financial values.
    PublicApiPreviewCheckoutPromoCodeRequest:
      type: object
      required:
      - code
      properties:
        code:
          type: string
          description: Buyer-entered promo/discount code (case-insensitive; stored uppercased).
    PublicApiCheckoutByPlanResponse:
      type: object
      required:
      - planId
      - productId
      - productName
      - type
      - amount
      - initialPrice
      - currency
      - checkoutUrl
      - customization
      properties:
        planId:
          type: string
        productId:
          type: string
        productName:
          type: string
        productDescription:
          type: string
        productImagePath:
          type: string
          nullable: true
        type:
          type: string
        billingPeriod:
          type: string
        lengthOfBillingPeriod:
          type: integer
          format: int32
        amount:
          $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
        initialPrice:
          allOf:
          - $ref: '#/components/schemas/SharedTypes.MoneyAmountValue'
          description: Amount charged at checkout today. Zero for recurring plans with a free trial; otherwise matches amount.
        currency:
          type: string
        checkoutUrl:
          type: string
        websiteUrl:
          type: string
          nullable: true
        termsUrl:
          type: string
          nullable: true
          description: Seller Terms URL or stable API redirect for a PDF. Null when unset.
        privacyUrl:
          type: string
          nullable: true
          description: Seller Privacy URL or stable API redirect for a PDF. Null when unset.
        returnPolicyUrl:
          type: string
          nullable: true
          description: Seller Return policy URL or stable API redirect for a PDF. Null when unset.
        eulaUrl:
          type: string
          nullable: true
          description: Seller EULA URL or stable API redirect for a PDF. Null when unset.
        customization:
          type: object
          additionalProperties: {}
    PublicApiConfirmCheckoutLogoRequest:
      type: object
      required:
      - path
      properties:
        path:
          type: string
          description: Exact `path` returned by the upload-url step.
    PublicApiConfirmCheckoutLogoResponse:
      type: object
      required:
      - logoUrl
      properties:
        logoUrl:
          type: string
          description: Presigned GET URL for the stored logo.
    PublicApiCheckoutReceiptResponse:
      type: object
      required:
      - subtotal
      - taxAmount
      - total
      - currency
      - taxBehavior
      properties:
        subtotal:
          type: number
          format: double
        taxAmount:
          type: number
          format: double
        total:
          type: number
          format: double
        currency:
          type: string
        taxBehavior:
          type: string
          enum:
          - exclusive
          - inclusive
    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
  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.'