JustiFi Payouts API

openapi: 3.2.0
info:
  description: '## Introduction


    The JustiFi API is a REST-based payment processing API.'
  title: JustiFi API Documentation Payouts 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: Payouts
  description: 'Each day, a payout containing that day''s funds is automatically created for the

    purpose of distributing those funds to the active bank account.'
paths:
  /payouts:
    get:
      summary: List Payouts
      operationId: ListPayouts
      tags:
      - Payouts
      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 payouts
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope-list'
                - properties:
                    type:
                      example: array
                    data:
                      items:
                        $ref: '#/components/schemas/Payout'
  /payouts/{id}:
    get:
      summary: Get a Payout
      description: Get information about a payout.
      operationId: GetPayout
      tags:
      - Payouts
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '200':
          description: Successfully get a payout
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: payout
                    data:
                      $ref: '#/components/schemas/Payout'
    patch:
      summary: Update a Payout
      description: Change a payout's metadata.
      operationId: UpdatePayout
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/idempotency-key-header'
      - $ref: '#/components/parameters/authorization-header'
      tags:
      - Payouts
      requestBody:
        required: true
        content:
          application/json:
            schema:
              properties:
                metadata:
                  type: object
                  format: json
                  description: any useful information you'd like to store alongside this payout; when you update metadata, any previous metadata will be overwritten
                  example:
                    customer_payout_id: cp_12345
      responses:
        '200':
          description: Payout update was successful
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: payout
                    data:
                      $ref: '#/components/schemas/Payout'
  /reports/payouts/{id}:
    get:
      deprecated: true
      summary: Get a Payout CSV Report
      description: '[DEPRECATION WARNING] This endpoint will be deprecated, please use Reports API.'
      operationId: GetPayoutCsvReport
      tags:
      - Payouts
      parameters:
      - $ref: '#/components/parameters/id-path'
      - $ref: '#/components/parameters/authorization-header'
      responses:
        '200':
          description: Successfully get a link to a csv report for a payout
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/Envelope'
                - properties:
                    type:
                      example: payout
                    data:
                      $ref: '#/components/schemas/PayoutCsvReport'
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
    Payout:
      type: object
      properties:
        id:
          description: unique payout id
          type: string
          example: po_xyz
        account_id:
          description: id of the account associated with the payout
          type: string
          format: uuid
        amount:
          description: 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 payout is delivered
          type: string
          enum:
          - standard
        description:
          type:
          - string
          - 'null'
        deposits_at:
          description: in UTC, the estimated date and time of the payout deposit (or in rare cases, withdrawal)
          type: string
          format: date-time
          example: '2021-01-01T12:00:00Z'
        fees_total:
          description: sum of fees in the payout, in cents
          type: number
          example: 5000
        refunds_count:
          description: number of refunds in the payout
          type: number
          example: 5
        refunds_total:
          description: sum of refunds in the payout, in cents
          type: number
          example: 10000
        payments_count:
          description: number of payments in the payout
          type: number
          example: 50
        payments_total:
          description: sum of payments in the payout, in cents
          type: number
          example: 110000
        payout_type:
          description: type of payment method used for the payments in the payout (funds from different types of payment methods settle at different intervals; in order to pay out your funds ASAP, we batch separate payouts for each payment method type)
          type: string
          enum:
          - ach cc
        other_total:
          description: sum of other less common transactions in the payout, in cents
          type: number
          example: 100
        status:
          description: status of the payout
          type: string
          example: paid
          enum:
          - paid failed forwarded scheduled in_transit canceled
        settlement_priority:
          description: settlement priority of the payout, either standard or expedited.
          type: string
          example: standard
          enum:
          - standard expedited
        metadata:
          type: object
          format: json
          description: any useful information you'd like to store alongside this payout
          example:
            customer_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'
    PayoutCsvReport:
      type: object
      properties:
        id:
          description: unique payout id
          type: string
          example: po_xyz
        csv_url:
          description: url that links to downloadable CSV report for payout.
          type: string
          example: https://justifi-test-payouts-reports.s3.amazonaws.com/acc_1234lkj/po_23jdfi36dqhj.csv?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=test
    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
    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

        '
    idempotency-key-header:
      in: header
      name: Idempotency-Key
      schema:
        type: string
        format: uuid
      required: true
      example: my-request-123abc
      description: a string to identify your request (we recommend using a generated uuid, but you may use any unique string) see [Idempotent Requests](https://docs.justifi.tech/api-spec#section/Idempotent-Requests)
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