openapi: 3.0.1
info:
  title: Smokeball Activity Codes Subscription Payments API
  version: '1.0'
  description: REST API for integrating with Smokeball legal practice management software. Supports matters, contacts, documents, time entries, billing, trust accounting, staff, webhooks, and law firm workflows across US, AU, and UK regions. Uses OAuth 2.0 (client credentials) authentication.
  contact:
    name: Smokeball Developer Support
    url: https://docs.smokeball.com/docs/api-docs/1e13a13124aee-introduction
  x-api-id: smokeball
  x-audience: external-public
servers:
- url: https://api.smokeball.com
- url: https://api.smokeball.com.au
- url: https://api.smokeball.co.uk
- url: https://stagingapi.smokeball.com
- url: https://stagingapi.smokeball.com.au
- url: https://stagingapi.smokeball.co.uk
security:
- api-key: []
  token: []
tags:
- name: Subscription Payments
paths:
  /subscriptions/paymentmethods:
    get:
      tags:
      - Subscription Payments
      summary: Get all customer payment methods
      description: Returns all payment methods attached to the current account's payment customer.
      operationId: GetCustomerPaymentMethodsAsync
      parameters:
      - name: Offset
        in: query
        schema:
          maximum: 2147483647
          minimum: 0
          type: integer
          format: int32
      - name: Limit
        in: query
        schema:
          maximum: 500
          minimum: 1
          type: integer
          format: int32
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodPagedCollection'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Internal Server Error
      x-excluded: true
    post:
      tags:
      - Subscription Payments
      summary: Add payment method
      description: "Adds a new payment method to the account.\r\n\r\nImportant notes:\r\n* Can optionally set as default payment method for the entire account\r\n* Can force immediate charge for overdue invoices for all active subscriptions\r\n* Payment information format depends on payment system"
      operationId: AddPaymentMethodAsync
      requestBody:
        description: Payment method details including system and payment information
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AddPaymentMethodRequest'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AddPaymentMethodRequest'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AddPaymentMethodRequest'
      responses:
        '202':
          description: When request is accepted. Returns a 'Link' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When subscription with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: When an error occurs while adding payment method.
      x-excluded: true
  /subscriptions/{subscriptionId}/paymentmethods:
    get:
      tags:
      - Subscription Payments
      summary: Get payment methods
      description: Returns the payment methods actively set on the specified subscription.
      operationId: GetPaymentMethodsAsync
      parameters:
      - name: subscriptionId
        in: path
        description: The unique identifier of the subscription
        required: true
        schema:
          type: string
      - name: Offset
        in: query
        schema:
          maximum: 2147483647
          minimum: 0
          type: integer
          format: int32
      - name: Limit
        in: query
        schema:
          maximum: 500
          minimum: 1
          type: integer
          format: int32
      responses:
        '200':
          description: When request is successful. Returns a paged collection of 'PaymentMethod' objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethodPagedCollection'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When subscription with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: When an error occurs while retrieving payment methods.
      x-excluded: true
    put:
      tags:
      - Subscription Payments
      operationId: UpdateSubscriptionPaymentMethodAsync
      parameters:
      - name: subscriptionId
        in: path
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SetDefaultPaymentMethodRequest'
              description: Request to set or clear a subscription default payment method.
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SetDefaultPaymentMethodRequest'
              description: Request to set or clear a subscription default payment method.
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/SetDefaultPaymentMethodRequest'
              description: Request to set or clear a subscription default payment method.
      responses:
        '202':
          description: Accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: Internal Server Error
      x-excluded: true
    post:
      tags:
      - Subscription Payments
      summary: Add payment method
      description: "Adds a new payment method to the account and sets it for the specified subscription \r\n\r\nImportant notes:\r\n* Can optionally set as default payment method for the entire account, or the specified subscription\r\n* Can force immediate charge for overdue invoices for the specified subscription\r\n* Payment information format depends on payment system"
      operationId: AddSubscriptionPaymentMethodAsync
      parameters:
      - name: subscriptionId
        in: path
        description: The unique identifier of the subscription
        required: true
        schema:
          type: string
      requestBody:
        description: Payment method details including system and payment information
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AddPaymentMethodRequest'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AddPaymentMethodRequest'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/AddPaymentMethodRequest'
      responses:
        '202':
          description: When request is accepted. Returns a 'Link' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When subscription with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: When an error occurs while adding payment method.
      x-excluded: true
  /subscriptions/{subscriptionId}/paymentmethods/{id}:
    get:
      tags:
      - Subscription Payments
      summary: Get payment method
      description: Returns a specific payment method associated with a subscription.
      operationId: GetPaymentMethodAsync
      parameters:
      - name: subscriptionId
        in: path
        description: The unique identifier of the subscription
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: The unique identifier of the payment method
        required: true
        schema:
          type: string
          format: uuid
      responses:
        '200':
          description: When request is successful. Returns a 'PaymentMethod' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentMethod'
        '400':
          description: When an unsupported request is made.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '404':
          description: When subscription or payment method with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: When an error occurs while retrieving payment method.
      x-excluded: true
    delete:
      tags:
      - Subscription Payments
      summary: Remove payment method
      description: "Removes a payment method from a subscription.\r\n\r\nImportant notes:\r\n* Can optionally specify a new default payment method\r\n* Removing default without replacement may cause subscription to go OVERDUE"
      operationId: RemovePaymentMethodAsync
      parameters:
      - name: subscriptionId
        in: path
        description: The unique identifier of the subscription
        required: true
        schema:
          type: string
      - name: id
        in: path
        description: The ID of the payment method to remove
        required: true
        schema:
          type: string
          format: uuid
      requestBody:
        description: Optional request containing new default payment method ID
        content:
          application/json-patch+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RemovePaymentMethodRequest'
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RemovePaymentMethodRequest'
          application/*+json:
            schema:
              allOf:
              - $ref: '#/components/schemas/RemovePaymentMethodRequest'
      responses:
        '202':
          description: When request is accepted. Returns a 'Link' object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Link'
        '404':
          description: When subscription or payment method with specified id does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProblemDetails'
        '500':
          description: When an error occurs while removing payment method.
      x-excluded: true
  /subscriptions/paymentsystems:
    get:
      tags:
      - Subscription Payments
      summary: Get supported payment systems
      description: "Returns all supported payment systems and their supported payment method types.\r\nCurrently supports:\r\n* STRIPE with CREDIT_CARD payment type"
      operationId: GetSupportedPaymentSystemsAsync
      responses:
        '200':
          description: When request is successful. Returns a collection of 'PaymentSystem' objects.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaymentSystemCollection'
        '500':
          description: When an error occurs while retrieving supported payment systems.
      x-excluded: true
components:
  schemas:
    AddPaymentMethodRequest:
      type: object
      properties:
        paymentSystemId:
          type: string
          description: Payment system to use.
          nullable: true
          example: STRIPE
        paymentInformation:
          allOf:
          - $ref: '#/components/schemas/PaymentInformation'
          description: "Payment information specific to the payment system.\r\n\r\nFor Stripe, this should be StripePaymentInformation."
          nullable: true
        isDefault:
          type: boolean
          description: "Whether to set this as the default payment method for the entire account \r\n\r\nThis does not set the default payment method for the subscription."
          nullable: true
          example: true
        chargeImmediately:
          type: boolean
          description: "Whether to charge immediately if subscription(s) are overdue.\r\n\r\nIf true, the payment system will attempt to charge the customer immediately if there are any overdue subscriptions.\r\n\r\nIf a subscription id is passed as a parameter to the request, only that subscription will be charged immediately if overdue."
          nullable: true
          example: true
      additionalProperties: false
    PaymentSystem:
      type: object
      properties:
        id:
          type: string
          description: Id of payment system.
          nullable: true
          example: STRIPE
        supportedPaymentTypes:
          type: array
          items:
            type: string
            description: "The payment type.\r\n\r\n* None - The payment type is missing or unknown.\r\n\r\n* CreditCard - Credit Card payment type.\r\n\r\n* DirectDeposit - Direct Deposit payment type. (not currently supported)"
          description: List of supported payment method types.
          nullable: true
      additionalProperties: false
    SetDefaultPaymentMethodRequest:
      type: object
      properties:
        paymentMethodId:
          type: string
          description: Public payment method id. Null clears the subscription override which reverts behavior to the Customer's default.
          format: uuid
          nullable: true
        subscriptionType:
          allOf:
          - $ref: '#/components/schemas/SubscriptionType'
          description: Deprecated. The subscription type is inferred from the route subscription id.
      additionalProperties: false
      description: Request to set or clear a subscription default payment method.
    SubscriptionType:
      enum:
      - 0
      - 1
      type: integer
      format: int32
    PaymentInformation:
      type: object
      additionalProperties: false
      description: Base class for payment information.
    PaymentMethodDetails:
      type: object
      properties:
        brand:
          type: string
          description: The brand of the credit card.
          nullable: true
        lastFourDigits:
          type: string
          description: Last four digits of the credit card.
          nullable: true
          example: '1234'
        expiry:
          type: string
          description: Expiry date of the credit card in MM/YY format.
          nullable: true
          example: 10/28
        expiryMonth:
          type: integer
          description: Expiry month.
          format: int64
          nullable: true
          example: 10
        expiryYear:
          type: integer
          description: Expiry year.
          format: int64
          nullable: true
          example: 2028
        accountNumber:
          type: integer
          description: "The account number of the direct deposit account.\r\n\r\nNot yet supported."
          format: int64
          nullable: true
          example: 123456789
        bsb:
          type: integer
          description: "The BSB of the direct deposit account.\r\n\r\nNot yet supported."
          format: int64
          nullable: true
      additionalProperties: false
    Link:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
      additionalProperties: false
    PaymentMethodPagedCollection:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        value:
          type: array
          items:
            $ref: '#/components/schemas/PaymentMethod'
          nullable: true
        offset:
          type: integer
          format: int32
          nullable: true
        limit:
          type: integer
          format: int32
          nullable: true
        size:
          type: integer
          format: int64
        first:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        previous:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        next:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        last:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
      additionalProperties: false
    PaymentMethod:
      type: object
      properties:
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        id:
          type: string
          description: Unique identifier of the payment method.
          nullable: true
          example: 784b3497-bf1f-47d2-93e6-1d38b96b8d3f
        paymentSystem:
          type: string
          description: Payment system.
          nullable: true
          example: STRIPE
        type:
          type: string
          description: "The payment type.\r\n\r\n* None - The payment type is missing or unknown.\r\n\r\n* CreditCard - Credit Card payment type.\r\n\r\n* DirectDeposit - Direct Deposit payment type. (not currently supported)"
          example: CreditCard
        isDefault:
          type: boolean
          description: Whether this is the default payment method for the customer.
          example: true
        details:
          allOf:
          - $ref: '#/components/schemas/PaymentMethodDetails'
          description: Payment method specific details for display.
          nullable: true
        lastPaymentState:
          type: string
          description: "The status of a payment.\r\n\r\n* None: The payment status is unknown.\r\n\r\n* Succeeded: The payment was successful.\r\n\r\n* Processing: The payment is being processed.\r\n\r\n* Canceled: The payment was canceled.\r\n\r\n* Failed: The payment requires a payment method to be provided, the provided payment method failed or other action is required (e.g. confirmation or other action by the customer)"
          example: Succeeded
        createdDate:
          type: string
          description: When this payment method was added.
          format: date-time
          example: '2022-04-23T14:00:00Z'
      additionalProperties: false
    PaymentSystemCollection:
      type: object
      properties:
        id:
          type: string
          nullable: true
        href:
          type: string
          nullable: true
        relation:
          type: string
          nullable: true
        method:
          type: string
          default: GET
          nullable: true
        self:
          allOf:
          - $ref: '#/components/schemas/Link'
          nullable: true
        value:
          type: array
          items:
            $ref: '#/components/schemas/PaymentSystem'
          nullable: true
      additionalProperties: false
    ProblemDetails:
      type: object
      properties:
        type:
          type: string
          nullable: true
        title:
          type: string
          nullable: true
        status:
          type: integer
          format: int32
          nullable: true
        detail:
          type: string
          nullable: true
        instance:
          type: string
          nullable: true
      additionalProperties: {}
    RemovePaymentMethodRequest:
      type: object
      properties:
        newDefaultPaymentMethodId:
          type: string
          description: Optional ID of payment method to set as new default.
          nullable: true
      additionalProperties: false
  securitySchemes:
    api-key:
      type: apiKey
      name: x-api-key
      in: header
    token:
      type: apiKey
      name: Authorization
      in: header
      x-amazon-apigateway-authtype: cognito_user_pools