JustiFi Proceeds API

openapi: 3.2.0
info:
  description: '## Introduction


    The JustiFi API is a REST-based payment processing API.'
  title: JustiFi API Documentation Proceeds 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: Proceeds
  description: 'Proceeds represent your platform''s take-home portion of the fees from your sub account''s financial transactions.

    Proceeds are batched together according to the payout schedule configured on your account, then transferred

    to your active bank account.'
paths:
  /proceeds:
    get:
      summary: List Proceeds
      description: List the proceeds payouts for your account. This endpoint supports pagination.
      operationId: ListProceeds
      tags:
      - Proceeds
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/created-before'
      - $ref: '#/components/parameters/created-after'
      - $ref: '#/components/parameters/deposits-before'
      - $ref: '#/components/parameters/deposits-after'
      responses:
        '200':
          description: Successfully list proceeds
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope-list'
                - properties:
                    type:
                      example: array
                    data:
                      items:
                        $ref: '#/components/schemas/Proceed'
  /proceeds/{id}:
    get:
      summary: Get a Proceeds Payout
      description: Get information about a proceeds payout.
      operationId: GetProceeds
      tags:
      - Proceeds
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '200':
          description: Successfully get a proceeds payout
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope-list'
                - properties:
                    type:
                      example: payout
                    data:
                      items:
                        $ref: '#/components/schemas/Proceed'
  /reports/proceeds/{id}:
    get:
      deprecated: true
      summary: Get a Proceeds Report
      description: '[DEPRECATION WARNING] This endpoint will be deprecated, please use Reports API.'
      operationId: GetProceedsReport
      tags:
      - Proceeds
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '200':
          description: Successfully get a link to a csv and json report for a proceeds payout
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: procceds
                    data:
                      $ref: '#/components/schemas/ProceedsReport'
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
    ProceedsReport:
      type: object
      properties:
        id:
          description: unique proceeds payout id
          type: string
          example: po_xyz
        csv_url:
          description: url that links to downloadable CSV report for proceeds payout
          type: string
          example: https://justifi-test-platform-proceeds-reports.s3.amazonaws.com/acc_1234lkj/po_23jdfi36dqhj.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=test
        report_url:
          description: url that links to downloadable JSON report for proceeds payout
          type: string
          example: https://justifi-test-platform-proceeds-reports.s3.amazonaws.com/acc_1234lkj/po_23jdfi36dqhj.json?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=test
    Proceed:
      type: object
      properties:
        id:
          description: unique proceeds payout id
          type: string
          example: po_xyz
        account_id:
          description: id of the account associated with the proceeds payout
          type: string
          format: uuid
        amount:
          description: proceeds payout amount in cents
          type: number
          example: 100000
        bank_account:
          $ref: '#/components/schemas/PayoutBankAccount'
        currency:
          type: string
          enum:
          - usd
          - cad
          example: usd
        delivery_method:
          description: how the proceeds payout is delivered
          type: string
          enum:
          - standard
        description:
          type:
          - string
          - 'null'
        deposits_at:
          description: in UTC, the date and time of the proceeds payout deposit (or in rare cases, withdrawal)
          type: string
          format: date-time
          example: '2021-01-01T12:00:00Z'
        refunds_count:
          description: number of refunds that impacted the proceeds payout
          type: number
          example: 5
        refunds_total:
          description: sum deducted from the proceeds payout as a result of accounts' refunds, in cents
          type: number
          example: 10000
        payments_count:
          description: number of payments that impacted the proceeds payout
          type: number
          example: 50
        payments_total:
          description: sum added to the proceeds payout as a result of accounts' payments, in cents
          type: number
          example: 110000
        payout_type:
          description: proceeds payouts are always of the type "proceeds" (other types apply only to sub accounts payouts)
          type: string
          enum:
          - proceeds
        other_total:
          description: sum of other less common transactions that impacted the proceeds payout, in cents
          type: number
          example: 100
        status:
          description: status of the proceeds payout
          type: string
          example: scheduled
          enum:
          - scheduled paid failed pending in_transit canceled
        metadata:
          type: object
          format: json
          description: any useful information you'd like to store alongside this proceeds payout
          example:
            platform_payout_id: cp_12345
        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'
    PayoutBankAccount:
      type: object
      properties:
        id:
          description: unique bank account id
          type: string
          format: uuid
        full_name:
          description: account holder's full name
          type: string
        bank_name:
          description: name of bank
          type: string
        account_number_last4:
          description: last 4 digits of the account number
          type: string
          example: 1111
        routing_number:
          type: string
        country:
          type: string
          enum:
          - US
          - CA
          example: US
        currency:
          type: string
          enum:
          - usd
          - cad
          example: usd
        nickname:
          type: string
        account_type:
          type: string
          enum:
          - checking
  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)
    deposits-after:
      in: query
      name: deposits_after
      schema:
        type: string
        format: date-time
      required: false
      example: '2022-01-01T00:00:00Z'
      description: 'filter records which deposit after the date and time (UTC) specified. Dates without time specified will default to 00:00:00

        '
    created-before:
      in: query
      name: created_before
      schema:
        type: string
        format: date-time
      required: false
      example: '2022-01-01T00:00:00Z'
      description: 'filter records which were created before the date and time (UTC) specified. Dates without time specified will default to 00:00:00

        '
    created-after:
      in: query
      name: created_after
      schema:
        type: string
        format: date-time
      required: false
      example: '2022-01-01T00:00:00Z'
      description: 'filter records which were created after the date and time (UTC) specified. Dates without time specified will default to 00:00:00

        '
    deposits-before:
      in: query
      name: deposits_before
      schema:
        type: string
        format: date-time
      required: false
      example: '2022-01-01T00:00:00Z'
      description: 'filter records which deposit before the date and time (UTC) specified. Dates without time specified will default to 00:00:00

        '
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