openapi: 3.1.0
info:
  title: Ante Custom SDK API
  version: 1.0.0
  description: REST API for SDK merchants at splitante.com/api/v1
servers:
  - url: https://splitante.com/api/v1
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
  schemas:
    Error:
      type: object
      properties:
        request_id:
          type: string
        error:
          type: string
        details:
          type: array
          items:
            type: string
          description: Optional checklist for complex errors (e.g. Invalid cart signature)
    CartItem:
      type: object
      required: [name, quantity, unit_price]
      properties:
        id:
          type: string
          description: Merchant SKU or line id (sorted for HMAC)
        name:
          type: string
        quantity:
          type: integer
          minimum: 1
        unit_price:
          type: integer
          minimum: 0
          description: Unit price in smallest currency unit (cents for USD)
        image_url:
          type: string
          format: uri
          description: Optional HTTPS product thumbnail — not included in cart HMAC
    Cart:
      type: object
      required: [total, currency, items]
      properties:
        total:
          type: integer
          description: sum(qty × unit_price) + tax + shipping
        currency:
          type: string
          minLength: 3
          maxLength: 3
          description: Lowercase ISO 4217 (e.g. usd)
        items:
          type: array
          minItems: 1
          items:
            $ref: "#/components/schemas/CartItem"
        tax:
          type: integer
          minimum: 0
        shipping:
          type: integer
          minimum: 0
        metadata:
          type: object
          additionalProperties:
            type: string
          description: Use order_ref for your internal order id
    Session:
      type: object
      properties:
        session_id:
          type: string
        status:
          type: string
        expires_at:
          type: string
          format: date-time
paths:
  /sessions:
    get:
      summary: List SDK sessions
      responses:
        "200":
          description: Paginated sessions
        "401":
          description: Invalid API key
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "429":
          description: Rate limited
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
    post:
      summary: Create session
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [cart]
              properties:
                cart:
                  $ref: "#/components/schemas/Cart"
                signature:
                  type: string
                  description: Cart HMAC (or X-Ante-Signature header)
                group_config:
                  type: object
                webhook_url:
                  type: string
                  format: uri
      responses:
        "200":
          description: Session created
        "400":
          description: Invalid cart or signature
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "403":
          description: Headless API not enabled or secret key from browser
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /sessions/{sessionId}:
    get:
      summary: Get session
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
      responses:
        "404":
          description: Not found
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /sessions/{sessionId}/cancel:
    post:
      summary: Cancel session and refund paid shares
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
  /sessions/{sessionId}/remind:
    post:
      summary: Send payment reminders to pending group members
      parameters:
        - name: sessionId
          in: path
          required: true
          schema:
            type: string
  /merchants/me:
    get:
      summary: Merchant profile and fee rates
  /webhooks:
    get:
      summary: List webhook endpoints
    post:
      summary: Register webhook endpoint
  /webhooks/{webhookId}:
    delete:
      summary: Revoke webhook endpoint