JustiFi Balance Transactions API

openapi: 3.2.0
info:
  description: '## Introduction


    The JustiFi API is a REST-based payment processing API.'
  title: JustiFi API Documentation Balance Transactions API
  termsOfService: https://justifi.ai/terms-and-conditions
  x-logo:
    url: https://justifi-brand-assets.s3.us-east-2.amazonaws.com/justifi-light-bg.png
  contact:
    email: api-development@justifi.ai
servers:
- url: https://api.justifi.ai/v1
  description: JustiFi API
tags:
- name: Balance Transactions
  description: 'Balance transactions are the reflection of any movement of funds that affects the balance of an account.

    Oftentimes, a single financial transaction (like a payment) will result in the creation of many balance

    transactions in order to document the flow of funds between multiple accounts. Other financial transactions

    that result in balance transactions include refunds, disputes, and payouts.'
paths:
  /balance_transactions:
    get:
      summary: List Balance Transactions
      description: List the balance transactions for your account. This API is limited to a single sub account or payout. This endpoint supports pagination.
      operationId: ListBalanceTransactions
      tags:
      - Balance Transactions
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/sub-account'
      - in: query
        name: payout_id
        schema:
          type: string
        required: false
        example: po_123xyz
        description: 'Filter records which are part of the payout with the specified id

          '
      - in: query
        name: source_payment_id
        schema:
          type: string
        required: false
        example: py_123xyz
        description: 'Filter records which are associated with the payment with the specified id

          '
      responses:
        '200':
          description: Successfully list balance transactions
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope-list'
                - properties:
                    type:
                      example: array
                    data:
                      items:
                        $ref: '#/components/schemas/BalanceTransaction'
  /balance_transactions/{id}:
    get:
      summary: Get a Balance Transaction
      description: Get information about a balance transaction.
      operationId: GetBalanceTransaction
      tags:
      - Balance Transactions
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '200':
          description: Successfully get a balance transaction
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: balance_transaction
                    data:
                      $ref: '#/components/schemas/BalanceTransaction'
components:
  schemas:
    Envelope:
      type: object
      properties:
        id:
          description: the object id, also found in the data object
          type: string
          format: uuid
          example: prefix_xyz (same as id of data object)
        type:
          description: the object type, or array of objects
          type: string
          example: account
        data:
          description: the attributes for the object
          type: object
        page_info:
          description: information for cursor style pagination, is null for single records
          type: null
    Envelope-list:
      type: object
      properties:
        id:
          description: the object id
          type: number
          example: 1
        type:
          description: the object type, or array of objects
          type: string
          example: account
        data:
          description: the list of objects
          type: array
        page_info:
          description: information for cursor style pagination
          $ref: '#/components/schemas/PageInfo'
    PageInfo:
      type: object
      properties:
        end_cursor:
          description: the encoded id of the last record in the current list
          type: string
          example: WyIyMDIyLTAyLTA4IDE5OjUyOjM3LjEwNDE3MzAwMCIsIjY4MDliYTU5LTYxYjctNDg3MS05YWFiLWE2Y2MyNmY3M2M1ZCJd
        has_next:
          description: true if the collection contains records following the current list
          type: boolean
          default: false
        has_previous:
          description: true if the collection contains records ahead of the current list
          type: boolean
          default: false
        start_cursor:
          description: the encoded id of the first record in the current list
          type: string
          example: WyIyMDIyLTAyLTA4IDIwOjAxOjU4LjEyMDIzMjAwMCIsIjU5ZTFjNGI1LWFlOWQtNDIyZC04MTVkLWNjNzQ5NzdlYmFjYSJd
    BalanceTransaction:
      type: object
      properties:
        id:
          description: unique balance transaction id
          type: string
          example: bt_xyz
        account_id:
          description: id of the account associated with the balance transaction
          type: string
          format: uuid
          example: acc_xyz
        amount:
          description: balance transaction amount, in cents
          type: number
          example: 100000
        available_on:
          type: string
          format: date-time
          example: '2021-01-01T12:00:00Z'
        currency:
          type: string
          enum:
          - usd
          - cad
          example: usd
        description:
          type:
          - string
          - 'null'
        fee:
          description: amount of fees deducted from the balance transaction amount, in cents
          type: number
          example: 5000
        financial_transaction_id:
          description: id of the financial transaction associated with the balance transaction
          type: string
          format: uuid
          example: ft_xyz
        net:
          description: net amount of the balance transaction (after fees are deducted), in cents
          type: number
          example: 600
        payout_id:
          description: id of the payout associated with the balance transaction
          type: string
          format: uuid
          example: po_xyz
        source_id:
          description: id of the source object associated with the balance transaction
          type: string
          format: uuid
          example: py_xyz
        source_type:
          description: type of source object associated with the balance transaction (for example payment, refund, dispute, payout)
          type: string
          example: payment
        source_payment_id:
          description: id of the payment associated with the source of the balance transaction
          type:
          - string
          - 'null'
          example: py_xyz
        txn_type:
          description: 'Type of transaction object associated with the balance transaction.


            Common types include:

            - `seller_payment`: Payment amount credited to merchant

            - `seller_payment_refund`: Payment refund debited from merchant

            - `processing_fee`: Processing fee deducted from merchant

            - `processing_fee_credit`: Processing fee credited to platform

            - `platform_fee`: Platform fee deducted from merchant

            - `platform_fee_credit`: Platform fee credited to platform

            - `processing_fee_return`: Processing fee returned on refund/void

            - `platform_fee_return`: Platform fee returned on refund/void

            - `partner_platform_discount_fee`: JustiFi basis point fee deducted from platform

            - `partner_platform_transaction_fee`: JustiFi per-transaction fee deducted from platform

            - `payout`: Payout to bank account

            - `refund`: Refund transaction


            See [Enhanced Fee Management](#section/Enhanced-Fee-Management) for details on fee-related transaction types.

            '
          type: string
          example: seller_payment
        created_at:
          type: string
          format: date-time
          example: '2021-01-01T12:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2021-01-01T12:00:00Z'
  parameters:
    id-path:
      in: path
      name: id
      schema:
        type: string
        format: uuid
      required: true
    authorization-header:
      in: header
      name: Authorization
      schema:
        type: string
      required: true
      example: Bearer {access_token}
      description: the `access_token` value returned from the JustiFi `oauth/token` endpoint (be sure to append `Bearer` before the token)
    sub-account:
      in: header
      name: Sub-Account
      schema:
        type: string
      required: false
      example: acc_123xyz
      description: 'the id of the [sub account](https://docs.justifi.tech/api-spec#tag/Sub-Accounts) that this request applies to

        '
x-tagGroups:
- name: Authorization
  tags:
  - API Credentials
  - Web Component Tokens
- name: For Platforms
  tags:
  - Sub Accounts
  - Platform Wallet Accounts
  - Onboarding via Component
  - Hosted Onboarding
  - Onboarding via API
  - Fee Configurations
  - Proceeds
  - Reports
- name: Payment Resources
  tags:
  - Payments
  - Payment Methods
  - Tokenize via Component
  - Payment Method Groups
  - Refunds
  - Disputes
  - Payouts
  - Payout Holds
  - Balance Transactions
  - Ach Return Fees
  - Payment Method Migration
- name: Checkout Resources
  tags:
  - Checkouts
  - Checkout via Component
  - Checkout via API
- name: Insurance Resources
  tags:
  - Bind Insurance
- name: Entity Resources
  tags:
  - Business
  - Identity
  - Address
  - Document
  - Bank Account
  - Terms and Conditions
  - Provisioning
- name: Card Present Resources
  tags:
  - Terminals
  - Terminals Orders
- name: Libraries
  tags:
  - JustiFi Web Components
  - JustiFi SDK
- name: Event Publishing
  tags:
  - Events
  - Webhook Delivery