JustiFi Payout Holds API

openapi: 3.2.0
info:
  description: '## Introduction


    The JustiFi API is a REST-based payment processing API.'
  title: JustiFi API Documentation Payout Holds 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: Payout Holds
  description: 'A payout hold is a resource that temporarily hold or pause payouts for a sub account.

    This feature is used for risk management, compliance, or business rule enforcement.

    Holds can be created automatically by the system (e.g., for first payments) or manually by JustiFi staff..'
paths:
  /payout_holds:
    get:
      summary: List Payout Holds
      description: List the payout holds that belong to this account. This endpoint supports pagination.
      operationId: ListPayoutHolds
      tags:
      - Payout Holds
      parameters:
      - $ref: '#/components/parameters/authorization-header'
      - $ref: '#/components/parameters/created-before'
      - $ref: '#/components/parameters/created-after'
      - $ref: '#/components/parameters/start-date-before'
      - $ref: '#/components/parameters/start-date-after'
      - $ref: '#/components/parameters/end-date-before'
      - $ref: '#/components/parameters/end-date-after'
      responses:
        '200':
          description: Successfully list payout holds
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope-list'
                - properties:
                    type:
                      example: array
                    data:
                      items:
                        $ref: '#/components/schemas/PayoutHold'
  /payout_holds/{payout_hold_id}:
    get:
      summary: Get a Payout Hold
      description: Retrieve a specific payout hold by ID.
      operationId: GetPayoutHold
      tags:
      - Payout Holds
      parameters:
      - $ref: '#/components/parameters/payout-hold-id-path'
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '200':
          description: Successfully get a payout hold
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: payout_hold
                    data:
                      $ref: '#/components/schemas/PayoutHold'
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
    PayoutHold:
      type: object
      properties:
        id:
          type: string
          example: poh_abc123xyz
        account_id:
          type: string
          example: acc_sub123
        hold_type:
          type: string
          enum:
          - first_payment
          - manual
          example: manual
        issued_by:
          type: string
          enum:
          - system
          - platform
          example: platform
        start_date:
          type: string
          format: date
          example: '2024-01-01'
        end_date:
          type:
          - string
          - 'null'
          format: date
          example: '2024-01-31'
        active:
          type: boolean
          example: true
        created_at:
          type: string
          format: date-time
          example: '2024-01-01T10:00:00Z'
        updated_at:
          type: string
          format: date-time
          example: '2024-01-01T10:00:00Z'
  parameters:
    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)
    start-date-after:
      in: query
      name: start_date_after
      schema:
        type: string
        format: date
      required: false
      example: '2024-01-01'
      description: Filter by start date after the specified date (ISO 8601 format)
    start-date-before:
      in: query
      name: start_date_before
      schema:
        type: string
        format: date
      required: false
      example: '2024-01-31'
      description: Filter by start date before the specified date (ISO 8601 format)
    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

        '
    end-date-before:
      in: query
      name: end_date_before
      schema:
        type: string
        format: date
      required: false
      example: '2024-01-31'
      description: Filter by end date before the specified date (ISO 8601 format)
    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

        '
    end-date-after:
      in: query
      name: end_date_after
      schema:
        type: string
        format: date
      required: false
      example: '2024-01-01'
      description: Filter by end date after the specified date (ISO 8601 format)
    payout-hold-id-path:
      in: path
      name: payout_hold_id
      schema:
        type: string
      required: true
      example: poh_abc123xyz
      description: Payout hold public ID with poh_ prefix
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