ASAP Payments Connect API

openapi: 3.2.0
info:
  title: ASAP Platform Payments Connect API
  description: 'Public HTTP API for ASAP Platform (api.asap.cool).


    All `/v1` responses are wrapped in a standard envelope. Success responses are `{ "data": , "meta": { "request_id", "next_cursor"?, "has_more"? } }` — the schema documented for each operation describes the inner `data` value. Errors are `{ "error": { "code", "message", "field"?, "request_id" } }`. Every response also carries an `X-Request-Id` header matching `meta.request_id` / `error.request_id`.'
  license:
    name: BUSL-1.1
  version: 0.0.0
servers:
- url: https://api.asap.cool
  description: Production
tags:
- name: payments-connect
  description: 'ASAP Payments connected account: platform-created Stripe account, embedded-component sessions and status (owner-only).'
paths:
  /v1/payments/connect/account:
    post:
      tags:
      - payments-connect
      summary: '`POST /v1/payments/connect/account`'
      operationId: stripeConnectCreateAccount
      responses:
        '200':
          description: The org's connected account (created on first call).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectStatusView'
        '401':
          description: Caller is not a session owner of the active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '503':
          description: Stripe Connect is not configured or Stripe is unreachable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/payments/connect/account-session:
    post:
      tags:
      - payments-connect
      summary: '`POST /v1/payments/connect/account-session`'
      operationId: stripeConnectCreateAccountSession
      responses:
        '200':
          description: A fresh Account Session secret for the embedded components.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectAccountSessionView'
        '401':
          description: Caller is not a session owner of the active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: The org has no platform-created account (`connect_account_missing`, `connect_legacy_account`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '503':
          description: Stripe Connect is not configured or Stripe is unreachable.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/payments/connect/disconnect:
    post:
      tags:
      - payments-connect
      summary: '`POST /v1/payments/connect/disconnect`'
      operationId: stripeConnectDisconnect
      responses:
        '200':
          description: Legacy OAuth account disconnected (idempotent).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectDisconnectView'
        '401':
          description: Caller is not a session owner of the active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '409':
          description: The account was created by ASAP and cannot be disconnected (`connect_platform_account`).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '503':
          description: Stripe Connect is not configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
  /v1/payments/connect/status:
    get:
      tags:
      - payments-connect
      summary: '`GET /v1/payments/connect/status`'
      operationId: stripeConnectStatus
      responses:
        '200':
          description: Connection status for the active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ConnectStatusView'
        '401':
          description: Caller is not a session owner of the active org.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
        '503':
          description: Stripe Connect is not configured.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorBody'
components:
  schemas:
    ConnectStatusView:
      type: object
      description: 'Response of `GET /v1/payments/connect/status` and

        `POST /v1/payments/connect/account`.'
      required:
      - connected
      - charges_enabled
      - payouts_enabled
      - details_submitted
      - requirements_due
      properties:
        charges_enabled:
          type: boolean
          description: Whether the connected account can accept charges (onboarding done).
        connected:
          type: boolean
          description: Whether the org has a connected Stripe account.
        details_submitted:
          type: boolean
          description: Whether the connected account finished submitting onboarding details.
        disabled_reason:
          type:
          - string
          - 'null'
          description: 'Why Stripe disabled the account (`requirements.disabled_reason`), if it

            did.'
        onboarding_mode:
          oneOf:
          - type: 'null'
          - $ref: '#/components/schemas/ConnectOnboardingMode'
            description: How the account was created. Absent when not connected.
        payouts_enabled:
          type: boolean
          description: Whether the connected account can receive payouts.
        requirements_due:
          type: array
          items:
            type: string
          description: Requirement keys Stripe currently needs (empty when none).
        stripe_account_id_last4:
          type:
          - string
          - 'null'
          description: 'Last 4 chars of the connected account id, for display only. `None`

            when not connected. The full `acct_…` id is never returned.'
    ConnectOnboardingMode:
      type: string
      description: How the org's connected account was created.
      enum:
      - platform
      - oauth
    ConnectAccountSessionView:
      type: object
      description: Response of `POST /v1/payments/connect/account-session`.
      required:
      - client_secret
      properties:
        client_secret:
          type: string
          description: 'Short-lived Account Session secret for Connect.js. Single use; request

            a new one whenever Connect.js asks.'
    ConnectDisconnectView:
      type: object
      description: Response of `POST /v1/payments/connect/disconnect`.
      required:
      - connected
      properties:
        connected:
          type: boolean
          description: Always `false` after a successful disconnect.
    ErrorBody:
      type: object
      description: 'Generic error body returned by API handlers when they fail. `code` is a

        stable machine-readable token; `message` is human-friendly and meant for

        surfacing to end users.'
      required:
      - code
      - message
      properties:
        code:
          type: string
          description: Stable machine token (e.g. `invalid_credentials`).
        field:
          type:
          - string
          - 'null'
          description: Offending request field for validation errors, when known.
        message:
          type: string
          description: Human-readable message.
  securitySchemes:
    api_key:
      type: http
      scheme: bearer
    session:
      type: apiKey
      in: cookie
      name: asap_session