payments-ai JSON API

openapi: 3.2.0
info:
  title: Payments AI website JSON API
  version: 1.0.0
  summary: Read-only JSON, Markdown, and content-negotiation surface of www.payments.ai.
  description: 'Machine-readable surface of the Payments AI website: company and pricing facts as JSON, a Markdown representation of every page, and `Accept: text/markdown` content negotiation per acceptmarkdown.com. No authentication is required and every endpoint is a GET.


    ## Versioning and deprecation


    JSON endpoints are versioned in the URL under `/api/v1`, currently stable. Nothing on this host is deprecated.


    - Additive changes ship in place: a response may gain a field, and never loses or renames one.

    - A breaking change ships under a new version prefix (/api/v2). The previous prefix keeps responding.

    - A deprecated version keeps responding for at least 12 months from the day it is announced.

    - Deprecation is announced with the Deprecation (RFC 9745) and Sunset (RFC 8594) response headers on the affected endpoints, and restated in this document, /llms.txt, and /api/v1/site.json.


    In short: an integration against `/api/v1` has at least 12 months'' warning before anything stops answering, and the warning arrives as a response header rather than only as a blog post.


    Product and integration APIs (checkout, subscriptions, webhooks, MCP) are not part of this description; they are documented at https://docs.payments.ai.'
  contact:
    name: Payments AI support
    email: support@payments.ai
    url: https://docs.payments.ai
  license:
    name: Proprietary
    identifier: LicenseRef-Proprietary
servers:
- url: https://www.payments.ai
  description: Production website
tags:
- name: Json
  description: Read-only JSON endpoints under /api/v1
paths:
  /api/v1/site.json:
    get:
      operationId: getSite
      summary: Company, legal entity, and product facts
      description: Canonical facts about Payments AI — legal entity, contact addresses, documentation, and the two products — for citation by agents and answer engines.
      tags:
      - Json
      responses:
        '200':
          description: Company, legal entity, and product facts
          headers:
            Deprecation:
              description: 'Set only once this endpoint is deprecated: the date it became deprecated, as an IMF-fixdate (RFC 9745). Absent means supported. It is followed by at least 12 months of service before `Sunset`.'
              required: false
              schema:
                type: string
            Sunset:
              description: 'Set only once this endpoint is deprecated: the date it stops responding, as an IMF-fixdate (RFC 8594). Absent means no removal is scheduled.'
              required: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Site'
        '404':
          description: No such endpoint. The body names the documentation to read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/pages.json:
    get:
      operationId: getPages
      summary: Index of pages and their Markdown representations
      description: Every public page together with the path of its Markdown representation, so an agent can fetch prose without parsing HTML.
      tags:
      - Json
      responses:
        '200':
          description: Index of pages and their Markdown representations
          headers:
            Deprecation:
              description: 'Set only once this endpoint is deprecated: the date it became deprecated, as an IMF-fixdate (RFC 9745). Absent means supported. It is followed by at least 12 months of service before `Sunset`.'
              required: false
              schema:
                type: string
            Sunset:
              description: 'Set only once this endpoint is deprecated: the date it stops responding, as an IMF-fixdate (RFC 8594). Absent means no removal is scheduled.'
              required: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PageIndex'
        '404':
          description: No such endpoint. The body names the documentation to read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/pricing/mor.json:
    get:
      operationId: getMorPricing
      summary: Merchant of Record pricing
      description: 'Itemized Merchant of Record pricing: headline card rate, terms, and every fee line by category.'
      tags:
      - Json
      responses:
        '200':
          description: Merchant of Record pricing
          headers:
            Deprecation:
              description: 'Set only once this endpoint is deprecated: the date it became deprecated, as an IMF-fixdate (RFC 9745). Absent means supported. It is followed by at least 12 months of service before `Sunset`.'
              required: false
              schema:
                type: string
            Sunset:
              description: 'Set only once this endpoint is deprecated: the date it stops responding, as an IMF-fixdate (RFC 8594). Absent means no removal is scheduled.'
              required: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MorPricing'
        '404':
          description: No such endpoint. The body names the documentation to read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v1/pricing/platforms.json:
    get:
      operationId: getPlatformsPricing
      summary: Payment orchestration pricing
      description: Pricing model and terms for payment orchestration. Itemized orchestration rates are not public and are quoted by sales.
      tags:
      - Json
      responses:
        '200':
          description: Payment orchestration pricing
          headers:
            Deprecation:
              description: 'Set only once this endpoint is deprecated: the date it became deprecated, as an IMF-fixdate (RFC 9745). Absent means supported. It is followed by at least 12 months of service before `Sunset`.'
              required: false
              schema:
                type: string
            Sunset:
              description: 'Set only once this endpoint is deprecated: the date it stops responding, as an IMF-fixdate (RFC 8594). Absent means no removal is scheduled.'
              required: false
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PlatformsPricing'
        '404':
          description: No such endpoint. The body names the documentation to read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /openapi.json:
    get:
      operationId: getOpenapiJson
      summary: This OpenAPI description
      description: This description, at the well-known root path. Start here to discover every endpoint, media type, and schema on this host.
      tags:
      - Json
      responses:
        '200':
          description: OpenAPI 3.1 document.
          content:
            application/json:
              schema:
                type: object
                description: This document.
  /api/openapi.json:
    get:
      operationId: getApiOpenapiJson
      summary: This OpenAPI description
      description: The same description as at the root path, served under the API prefix for clients that look for it beside the endpoints it documents.
      tags:
      - Json
      responses:
        '200':
          description: OpenAPI 3.1 document.
          content:
            application/json:
              schema:
                type: object
                description: This document.
components:
  schemas:
    Error:
      type: object
      description: Error envelope returned by every JSON endpoint and by unknown paths under `/api`.
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - status
          - message
          - resolution
          - documentation_url
          properties:
            code:
              type: string
              description: Stable machine code, snake_case.
              examples:
              - not_found
              - method_not_allowed
            status:
              type: integer
              description: HTTP status of this response.
            message:
              type: string
              description: What went wrong.
            resolution:
              type: string
              description: What to do next to succeed.
            documentation_url:
              type: string
              format: uri
    Site:
      type: object
      description: Company, legal entity, and product facts.
      required:
      - name
      - legal_name
      - url
      - products
      - api
      properties:
        name:
          type: string
        legal_name:
          type: string
        url:
          type: string
          format: uri
        description:
          type: string
        logo:
          type: string
          format: uri
        documentation_url:
          type: string
          format: uri
        same_as:
          type: array
          items:
            type: string
        contact:
          type: object
          properties:
            support:
              type: string
              format: email
            compliance:
              type: string
              format: email
        address:
          type: object
          description: Registered entity address.
          properties:
            streetAddress:
              type: string
            addressLocality:
              type: string
            addressRegion:
              type: string
            postalCode:
              type: string
            addressCountry:
              type: string
        products:
          type: array
          items:
            type: object
            required:
            - id
            - name
            - url
            properties:
              id:
                type: string
              name:
                type: string
              audience:
                type: string
              description:
                type: string
              url:
                type: string
                format: uri
              pricing_url:
                type: string
                format: uri
        api:
          type: object
          description: Versioning and deprecation policy for the JSON endpoints on this host.
          required:
          - version
          - status
          - notice_period_months
          - policy
          properties:
            version:
              type: string
              examples:
              - v1
            base_url:
              type: string
              format: uri
            status:
              type: string
              examples:
              - stable
              - deprecated
            notice_period_months:
              type: integer
              description: Months a deprecated version keeps responding, counted from the announcement.
            policy:
              type: array
              items:
                type: string
            deprecation_header:
              type: string
            sunset_header:
              type: string
            currently_deprecated:
              type: array
              items:
                type: string
              description: Paths with a Deprecation header set. Empty when nothing is deprecated.
            openapi_url:
              type: string
              format: uri
        machine_readable:
          type: object
          additionalProperties: true
    MorPricing:
      type: object
      description: Itemized Merchant of Record pricing.
      required:
      - currency
      - headline
      - categories
      properties:
        currency:
          type: string
          examples:
          - USD
        headline:
          type: object
          description: The headline card rate, e.g. 2.7% + $0.30 per successful card transaction.
          properties:
            rate:
              type: string
            fixed:
              type: string
            basis:
              type: string
        terms:
          type: array
          items:
            type: string
        signup_url:
          type: string
          format: uri
        categories:
          type: array
          items:
            type: object
            required:
            - id
            - title
            - line_items
            properties:
              id:
                type: string
              title:
                type: string
              subtitle:
                type: string
              highlights:
                type: array
                items:
                  type: string
              line_items:
                type: array
                items:
                  type: object
                  required:
                  - name
                  - price
                  properties:
                    name:
                      type: string
                    price:
                      type: string
                      description: Rate as published, e.g. `2.7% + $0.30`.
                    description:
                      type: string
        human_url:
          type: string
          format: uri
        markdown_url:
          type: string
          format: uri
    PageIndex:
      type: object
      required:
      - pages
      properties:
        pages:
          type: array
          items:
            type: object
            required:
            - title
            - html_url
            - markdown_url
            properties:
              title:
                type: string
              description:
                type: string
              html_url:
                type: string
                format: uri
              markdown_url:
                type: string
                format: uri
        not_found_markdown_url:
          type: string
          format: uri
        content_negotiation:
          type: object
          additionalProperties: true
    PlatformsPricing:
      type: object
      description: Payment orchestration pricing model. Itemized rates are quoted by sales.
      required:
      - summary
      - itemized_rates_public
      properties:
        currency:
          type: string
          examples:
          - USD
        summary:
          type: string
        terms:
          type: array
          items:
            type: string
        itemized_rates_public:
          type: boolean
        quote:
          type: object
          properties:
            note:
              type: string
            sales_email:
              type: string
              format: email
            signup_url:
              type: string
              format: uri
        human_url:
          type: string
          format: uri
        markdown_url:
          type: string
          format: uri
externalDocs:
  url: https://docs.payments.ai
  description: Product and integration documentation