Lithic Management Operations API

openapi: 3.1.0
info:
  contact:
    email: support@lithic.com
  description: 'The Lithic Developer API is designed to provide a predictable programmatic interface for accessing your Lithic account through an API and transaction webhooks.

    Note that your API key is a secret and should be treated as such. Don''t share it with anyone, including us. We will never ask you for it.

    '
  termsOfService: https://lithic.com/legal/terms
  license:
    name: Apache 2.0
    url: https://www.apache.org/licenses/LICENSE-2.0.txt
  title: Lithic Developer 3DS Management Operations API
  version: 1.0.0
servers:
- description: Sandbox environment that provides key functionality mirroring production
  url: https://sandbox.lithic.com
security:
- ApiKeyAuth: []
tags:
- name: Management Operations
paths:
  /v1/management_operations:
    get:
      description: List management operations
      parameters:
      - description: Management operation category to be returned.
        in: query
        name: category
        schema:
          $ref: '#/components/schemas/management_operation_category'
      - description: Globally unique identifier for the financial account. Accepted type dependent on the program's use case.
        in: query
        name: financial_account_token
        schema:
          format: uuid
          type: string
      - in: query
        name: business_account_token
        required: false
        schema:
          format: uuid
          title: Business Account Token
          type: string
      - description: Management operation status to be returned.
        in: query
        name: status
        schema:
          $ref: '#/components/schemas/transaction_status'
      - $ref: '#/components/parameters/beginTime'
      - $ref: '#/components/parameters/endingBefore'
      - $ref: '#/components/parameters/endTime'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/startingAfter'
      operationId: getManagementOperations
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/management_operation_transactions_response'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: List management operations
      tags:
      - Management Operations
    post:
      description: Create management operation
      operationId: postManagementOperations
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/create_management_operation_request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/management_operation_transaction'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Create management operation
      tags:
      - Management Operations
  /v1/management_operations/{management_operation_token}:
    get:
      description: Get management operation
      parameters:
      - description: Globally unique identifier for the management operation
        in: path
        name: management_operation_token
        required: true
        schema:
          format: uuid
          type: string
      operationId: getManagementOperation
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/management_operation_transaction'
          description: OK
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Get management operation
      tags:
      - Management Operations
  /v1/management_operations/{management_operation_token}/reverse:
    post:
      description: Reverse a management operation
      parameters:
      - description: Globally unique identifier for the management operation
        in: path
        name: management_operation_token
        required: true
        schema:
          format: uuid
          type: string
      operationId: reverseManagementOperation
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/management_operation_action_request'
        required: true
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/management_operation_transaction'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
      summary: Reverse management operation
      tags:
      - Management Operations
components:
  schemas:
    base_transaction:
      title: base_transaction
      description: Base class for all transaction types in the ledger service
      type: object
      properties:
        status:
          $ref: '#/components/schemas/transaction_status'
          description: The status of the transaction
        token:
          type: string
          description: Unique identifier for the transaction
          format: uuid
        created:
          type: string
          description: ISO 8601 timestamp of when the transaction was created
          format: date-time
        updated:
          type: string
          description: ISO 8601 timestamp of when the transaction was last updated
          format: date-time
      required:
      - status
      - token
      - created
      - updated
    management_operation_transaction:
      title: Management Operation Transaction
      allOf:
      - $ref: '#/components/schemas/base_transaction'
      - type: object
        properties:
          family:
            type: string
            const: MANAGEMENT_OPERATION
            description: MANAGEMENT_OPERATION - Management Operation Transaction
          result:
            $ref: '#/components/schemas/transaction_result'
          category:
            $ref: '#/components/schemas/management_operation_category'
          settled_amount:
            type: integer
          pending_amount:
            type: integer
          currency:
            type: string
          events:
            type: array
            items:
              $ref: '#/components/schemas/management_operation_event'
          user_defined_id:
            type:
            - string
            - 'null'
          financial_account_token:
            type: string
            format: uuid
          direction:
            $ref: '#/components/schemas/management_operation_direction'
          transaction_series:
            oneOf:
            - $ref: '#/components/schemas/transaction_series'
            - type: 'null'
          external_resource:
            oneOf:
            - $ref: '#/components/schemas/external_resource'
            - type: 'null'
      required:
      - result
      - category
      - family
      - settled_amount
      - pending_amount
      - currency
      - events
      - financial_account_token
      - direction
      - transaction_series
    management_operation_transactions_response:
      title: Management Operation Transactions Response
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/management_operation_transaction'
        has_more:
          type: boolean
      required:
      - data
      - has_more
    management_operation_category:
      title: Management Operation Category
      type: string
      enum:
      - MANAGEMENT_FEE
      - MANAGEMENT_DISPUTE
      - MANAGEMENT_REWARD
      - MANAGEMENT_ADJUSTMENT
      - MANAGEMENT_DISBURSEMENT
    management_operation_event_type:
      title: Management Operation Event Type
      type: string
      enum:
      - LOSS_WRITE_OFF
      - CASH_BACK
      - CASH_BACK_REVERSAL
      - CURRENCY_CONVERSION
      - CURRENCY_CONVERSION_REVERSAL
      - INTEREST
      - INTEREST_REVERSAL
      - LATE_PAYMENT
      - LATE_PAYMENT_REVERSAL
      - BILLING_ERROR
      - BILLING_ERROR_REVERSAL
      - PROVISIONAL_CREDIT
      - PROVISIONAL_CREDIT_REVERSAL
      - RETURNED_PAYMENT
      - RETURNED_PAYMENT_REVERSAL
      - DISPUTE_WON
      - DISPUTE_WON_REVERSAL
      - DISBURSE
      - DISBURSE_REVERSAL
      - ANNUAL
      - ANNUAL_REVERSAL
      - QUARTERLY
      - QUARTERLY_REVERSAL
      - MONTHLY
      - MONTHLY_REVERSAL
    external_resource_type:
      title: ExternalResourceType
      type: string
      enum:
      - STATEMENT
      - COLLECTION
      - DISPUTE
      - UNKNOWN
      description: Type of external resource associated with the management operation
    external_resource:
      title: ExternalResource
      type: object
      required:
      - external_resource_type
      - external_resource_token
      properties:
        external_resource_type:
          $ref: '#/components/schemas/external_resource_type'
        external_resource_token:
          type: string
          description: Token identifying the external resource
        external_resource_sub_token:
          type: string
          description: Token identifying the external resource sub-resource
      description: External resource associated with the management operation
      additionalProperties: false
    transaction_status:
      title: Transaction Status
      type: string
      enum:
      - PENDING
      - SETTLED
      - DECLINED
      - REVERSED
      - CANCELED
      - RETURNED
    detailed_results:
      title: Detailed Results
      type: string
      enum:
      - APPROVED
      - INSUFFICIENT_FUNDS
    create_management_operation_request:
      title: Create Management Operation Request
      type: object
      properties:
        category:
          $ref: '#/components/schemas/management_operation_category'
        event_type:
          $ref: '#/components/schemas/management_operation_event_type'
        subtype:
          type: string
        financial_account_token:
          type: string
          format: uuid
        amount:
          type: integer
          minimum: 1
        memo:
          type: string
        user_defined_id:
          type: string
        effective_date:
          type: string
          format: date
        token:
          description: Customer-provided token that will serve as an idempotency token. This token will become the transaction token.
          type: string
          format: uuid
        direction:
          $ref: '#/components/schemas/management_operation_direction'
        on_closed_account:
          $ref: '#/components/schemas/on_closed_account'
      required:
      - category
      - event_type
      - financial_account_token
      - amount
      - effective_date
      - direction
    on_closed_account:
      title: On Closed Account
      description: What to do if the financial account is closed when posting an operation
      type: string
      enum:
      - FAIL
      - USE_SUSPENSE
      default: FAIL
    transaction_result:
      title: Transaction Result
      type: string
      enum:
      - APPROVED
      - DECLINED
    transaction_series:
      title: Transaction Series
      type: object
      properties:
        type:
          type: string
          example: FEE
        related_transaction_token:
          oneOf:
          - type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
          - type: 'null'
        related_transaction_event_token:
          oneOf:
          - type: string
            format: uuid
            example: 123e4567-e89b-12d3-a456-426614174000
          - type: 'null'
      required:
      - type
      - related_transaction_token
      - related_transaction_event_token
    management_operation_direction:
      title: Management Operation Direction
      type: string
      enum:
      - CREDIT
      - DEBIT
    error:
      type: object
      properties:
        debugging_request_id:
          type: string
          format: uuid
          description: Identifier to help debug an error.
        message:
          type: string
          description: Explanation of error response.
      required:
      - debugging_request_id
      - message
    management_operation_action_request:
      title: Management Operation Action Request
      type: object
      properties:
        memo:
          type: string
        effective_date:
          type: string
          format: date
      required:
      - effective_date
    management_operation_event:
      title: Management Operation Event
      type: object
      properties:
        amount:
          type: integer
        type:
          $ref: '#/components/schemas/management_operation_event_type'
        subtype:
          type:
          - string
          - 'null'
        result:
          $ref: '#/components/schemas/transaction_result'
        detailed_results:
          type: array
          items:
            $ref: '#/components/schemas/detailed_results'
        created:
          type: string
          format: date-time
        token:
          type: string
          format: uuid
        memo:
          type: string
        effective_date:
          type: string
          format: date
      required:
      - amount
      - type
      - result
      - detailed_results
      - created
      - token
      - memo
      - effective_date
  responses:
    BadRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: A parameter in the query given in the request does not match the valid queries for the endpoint.
    NotFound:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: The specified resource was not found.
    Unauthorized:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: '|   |   |

        |---|---|

        | User has not been authenticated | Invalid or missing API key |

        | API key is not active | The API key used is no longer active |

        | Could not find API key | The API key provided is not associated with any user |

        | Please provide API key in Authorization header | The Authorization header is not in the request |

        | Please provide API key in the form Authorization: [api-key] | The Authorization header is not formatted properly |

        | Insufficient privileges. Issuing API key required | Write access requires an Issuing API key. Reach out at [lithic.com/contact](https://lithic.com/contact) |

        | Insufficient privileges to create virtual cards. | Creating virtual cards requires an additional privilege | Reach out at [lithic.com/contact](https://lithic.com/contact) |

        '
    TooManyRequests:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/error'
      description: 'Client has exceeded the number of allowed requests in a given time period.


        |   |   |

        |---|---|

        | Rate limited, too many requests per second | User has exceeded their per second rate limit |

        | Rate limited, reached daily limit | User has exceeded their daily rate limit |

        | Rate limited, too many keys tried | One IP has queried too many different API keys |

        '
  parameters:
    startingAfter:
      description: A cursor representing an item's token after which a page of results should begin. Used to retrieve the next page of results after this item.
      in: query
      name: starting_after
      required: false
      schema:
        type: string
    endTime:
      description: Date string in RFC 3339 format. Only entries created before the specified time will be included. UTC time zone.
      in: query
      name: end
      schema:
        format: date-time
        type: string
    beginTime:
      description: Date string in RFC 3339 format. Only entries created after the specified time will be included. UTC time zone.
      in: query
      name: begin
      schema:
        format: date-time
        type: string
    endingBefore:
      description: A cursor representing an item's token before which a page of results should end. Used to retrieve the previous page of results before this item.
      in: query
      name: ending_before
      required: false
      schema:
        type: string
    pageSize:
      description: Page size (for pagination).
      in: query
      name: page_size
      schema:
        default: 50
        maximum: 100
        minimum: 1
        type: integer
  securitySchemes:
    ApiKeyAuth:
      in: header
      name: Authorization
      type: apiKey