Chariot disbursements API

openapi: 3.0.0
info:
  title: Chariot FDX Accounts disbursements API
  version: '6.0'
  description: Financial Data Exchange (FDX) v6 compatible API for read-only access to Chariot bank account data. Implements the FDX v6 standard for account information, transactions, and statements.
  contact:
    name: Chariot Development Team
    url: https://givechariot.com/contact
    email: developers@givechariot.com
servers:
- url: https://api.givechariot.com/fdx/v6
  description: Production
- url: https://devapi.givechariot.com/fdx/v6
  description: Staging
security:
- oauth2: []
tags:
- name: disbursements
paths:
  /v1/disbursements:
    post:
      summary: Create a disbursement
      description: 'Create a disbursement to send money to an organization.

        '
      operationId: createDisbursement
      tags:
      - disbursements
      security:
      - bearerAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        description: 'A client-generated identifier for the request. Replays with the same key return `409 Conflict`. The successfully created disbursement can later be located via `GET /v1/disbursements?idempotency_key=...`.


          We recommend supplying your own unique identifier for the disbursement in your system, so you can later look it up by an ID you already track.'
        required: false
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/CreateDisbursementRequest'
      responses:
        '201':
          description: The disbursement was created
          headers:
            Location:
              $ref: '#/components/headers/Location'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disbursement'
              examples:
                DafGrantDisbursement:
                  $ref: '#/components/examples/DafGrantDisbursement'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    get:
      summary: List disbursements
      description: 'Returns a list of disbursements.

        '
      operationId: listDisbursements
      tags:
      - disbursements
      security:
      - bearerAuth: []
      parameters:
      - name: organization_id
        in: query
        description: The unique identifier for the organization
        required: false
        schema:
          type: string
        example: org_01jpjenf5q6cawy43yxfcrxhct
      - name: page_limit
        in: query
        description: Limit the size of the list that is returned. The default (and maximum) is 100 objects.
        required: false
        schema:
          type: integer
          format: int32
      - name: next_page_token
        in: query
        description: A token to use to retrieve the next page of results. This is useful for paginating over many pages of results. If set, all other arguments are expected to be kept the same as previous calls and the value of this field should be from the nextPageToken in the previous response.
        required: false
        schema:
          type: string
      - name: includes
        in: query
        description: "A comma separated list of fields to include in the response.\nPossible values include:\n  - `organization`: Include the organization object in the response."
        required: false
        schema:
          type: string
          example: organization
      - name: idempotency_key
        in: query
        description: Filter to the disbursement created with this exact `Idempotency-Key` header on `POST /v1/disbursements`. Useful for recovering the result of a create request when the response was lost (e.g. network timeout). Returns at most one disbursement. Disbursements created via `POST /v1/disbursements/bulk` cannot be looked up this way.
        required: false
        schema:
          type: string
          example: 8e91b2f3-d7c4-4a59-9a91-72a40b1f2c3d
      responses:
        '200':
          $ref: '#/components/responses/ListDisbursementsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/disbursements/bulk:
    post:
      summary: Create multiple disbursements
      description: 'Create multiple disbursements in a single request.

        This is useful for batch operations where you need to create many disbursements at once.


        All disbursements in the request will be created together. If any disbursement fails validation,

        the entire request will fail and no disbursements will be created.


        **Note:** Disbursements created through this endpoint cannot be looked up via `GET /v1/disbursements?idempotency_key=...`. The `idempotency_key` field on the returned disbursements will be `null`.

        '
      operationId: bulkCreateDisbursements
      tags:
      - disbursements
      security:
      - bearerAuth: []
      requestBody:
        $ref: '#/components/requestBodies/BulkCreateDisbursementsRequest'
      responses:
        '201':
          description: The disbursements were created
          content:
            application/json:
              schema:
                type: object
                required:
                - disbursements
                - count
                properties:
                  disbursements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Disbursement'
                  count:
                    type: integer
                    description: The number of disbursements created
                    example: 2
              examples:
                BulkCreateDisbursements:
                  $ref: '#/components/examples/BulkCreateDisbursements'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/disbursements/{id}:
    get:
      summary: Get a disbursement
      description: 'Get a disbursement by its unique identifier.

        '
      operationId: getDisbursement
      tags:
      - disbursements
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: The unique identifier for the disbursement
        required: true
        schema:
          type: string
        example: disbursement_01jpjen1s23s29kkmnjsb6fzga
      responses:
        '200':
          description: The disbursement was retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disbursement'
              examples:
                DafGrantDisbursement:
                  $ref: '#/components/examples/DafGrantDisbursement'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/disbursements/{id}/approve:
    post:
      summary: Approve a disbursement
      description: 'Approve a disbursement in a pending_approval state.

        If the disbursement is in a different state, this will return a 400 error.

        '
      operationId: approveDisbursement
      tags:
      - disbursements
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: The unique identifier for the disbursement
        required: true
        schema:
          type: string
        example: disbursement_01jpjen1s23s29kkmnjsb6fzga
      responses:
        '200':
          description: The disbursement was approved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disbursement'
              examples:
                ApprovedDafGrantDisbursement:
                  $ref: '#/components/examples/ApprovedDafGrantDisbursement'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/disbursements/approve:
    post:
      summary: Approve multiple disbursements
      description: 'Approve multiple disbursements in a single request.

        This is useful for batch approval operations.


        All disbursements must be in the `pending_approval` state. If any disbursement

        cannot be approved, the entire request will fail and no disbursements will be approved.

        '
      operationId: bulkApproveDisbursements
      tags:
      - disbursements
      security:
      - bearerAuth: []
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - disbursement_ids
              properties:
                disbursement_ids:
                  type: array
                  description: Array of disbursement IDs to approve
                  minItems: 1
                  items:
                    type: string
                    example: disbursement_01jpjen1s23s29kkmnjsb6fzga
      responses:
        '200':
          description: The disbursements were approved
          content:
            application/json:
              schema:
                type: object
                required:
                - disbursements
                - count
                properties:
                  disbursements:
                    type: array
                    items:
                      $ref: '#/components/schemas/Disbursement'
                  count:
                    type: integer
                    description: The number of disbursements approved
                    example: 5
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/disbursements/{id}/cancel:
    post:
      summary: Cancel a pending disbursement
      description: 'Cancel a pending disbursement in a pending_approval state.

        If the disbursement is in a different state, this will return a 400 error.

        '
      operationId: cancelDisbursement
      tags:
      - disbursements
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: The unique identifier for the disbursement
        required: true
        schema:
          type: string
        example: disbursement_01jpjen1s23s29kkmnjsb6fzga
      responses:
        '200':
          description: The disbursement was canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Disbursement'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/disbursements/{id}/stop:
    post:
      summary: Stop payment for a disbursement
      description: 'Stop payment for a disbursement sent via check.


        This prevents the recipient from depositing the check. If the check has already been deposited, the stop payment request will fail.


        **Requirements:**

        - Disbursement must be in `submitted` status

        - Disbursement must be sent via check

        - Check must not have already been deposited


        After successfully stopping payment, the disbursement status will be updated to `stopped`.

        '
      operationId: stopDisbursement
      tags:
      - disbursements
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: The unique identifier for the disbursement
        required: true
        schema:
          type: string
        example: disbursement_01jpjen1s23s29kkmnjsb6fzga
      requestBody:
        $ref: '#/components/requestBodies/StopDisbursementRequest'
      responses:
        '202':
          description: The stop payment request was accepted
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '412':
          $ref: '#/components/responses/PreconditionFailedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/simulations/disbursements/{id}/complete:
    post:
      summary: 'Sandbox: Complete a disbursement'
      description: 'Simulates successful disbursement completion for testing purposes.

        The disbursement must have a status of `submitted`.


        After calling this endpoint, the disbursement status will be updated to `completed`.


        <Note title="Sandbox Only" icon="fa-light fa-atom-simple">

        This API is only available in the sandbox environment.

        </Note>

        '
      operationId: simulateDisbursementCompletion
      tags:
      - disbursements
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: The unique identifier for the disbursement
        required: true
        schema:
          type: string
        example: disbursement_01jpjen1s23s29kkmnjsb6fzga
      responses:
        '202':
          description: The disbursement completion request was accepted
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/simulations/disbursements/{id}/fail:
    post:
      summary: 'Sandbox: Fail a disbursement'
      description: 'Simulates a payment failure or return for testing purposes.

        The disbursement must have a status of `submitted`.

        This only applies for disbursements sent via ACH or check.


        - **ACH disbursements**: Status becomes `failed` (payment was returned and cannot be retried)

        - **Check disbursements**: Status becomes `validating_organization` (check was returned). When this happens, Chariot will investigate why the check failed to reach the organization, update any required recipient information (such as mailing address or organization contact details), and automatically reattempt payout once the issue is resolved.


        <Note title="Sandbox Only" icon="fa-light fa-atom-simple">

        This API is only available in the sandbox environment.

        </Note>

        '
      operationId: simulateDisbursementFailure
      tags:
      - disbursements
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: The unique identifier for the disbursement
        required: true
        schema:
          type: string
        example: disbursement_01jpjen1s23s29kkmnjsb6fzga
      responses:
        '202':
          description: The disbursement failure simulation was accepted
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  schemas:
    CheckTransfer:
      type: object
      description: A check transfer represents a paper check that is mailed to the receiving organization.
      required:
      - transfer_id
      - amount
      - status
      - mailing_address
      - memo
      - recipient_name
      - created_at
      properties:
        transfer_id:
          type: string
          description: The unique identifier for the check transfer
          example: check_transfer_01j8rs605a4gctmbm58d87mvsj
          readOnly: true
        amount:
          type: integer
          format: int64
          description: The amount of the check transfer in minor currency units (cents)
          example: 10000
        status:
          type: string
          description: "The lifecycle status of the check.\nThe set of statuses include:\n  - `pending`: The check is pending review by Chariot.\n  - `canceled`: The check has been canceled.\n  - `issued`: The check has been mailed and is pending delivery.\n  - `rejected`: The check was rejected by Chariot.\n  - `deposited`: The check has been deposited by the receiving organization.\n  - `stopped`: A stop payment was requested on the check.\n  - `returned`: The check has been returned by the receiving organization.\n\nTo see a more detailed description of each status and the overall lifecycle of check disbursements,\nsee the \"Transfer Statuses\" section of the Chariot documentation."
          example: issued
          enum:
          - pending
          - canceled
          - issued
          - rejected
          - deposited
          - stopped
          - returned
        memo:
          type: string
          description: The memo on the check. Maximum of 72 characters.
          example: Disbursement to nonprofit
        note:
          type: string
          description: An optional note for the check
          example: Please deposit promptly
        check_number:
          type: string
          description: The check number
          example: '123456789'
        recipient_name:
          type: string
          description: The name that will be printed on the check.
          example: Charity Good
        mailing_address:
          $ref: '#/components/schemas/PostalAddress'
        bank_of_first_deposit_routing_number:
          type: string
          description: The routing number for the bank of first deposit
          example: 021000089
        postal_tracking_updates:
          type: array
          description: The list of tracking updates for the check
          items:
            $ref: '#/components/schemas/PostalTrackingUpdate'
        submitted_at:
          type: string
          format: date-time
          description: The date and time the check was submitted to the carrier.
          example: '2020-01-31T23:00:00Z'
        canceled_at:
          type: string
          format: date-time
          description: The date and time the check was canceled.
          example: '2020-01-31T23:00:00Z'
        stopped_at:
          type: string
          format: date-time
          description: The date and time the check was stopped.
          example: '2020-01-31T23:00:00Z'
        deposited_at:
          type: string
          format: date-time
          description: The date and time the check was deposited.
          example: '2020-01-31T23:00:00Z'
        created_at:
          type: string
          format: date-time
          description: The date and time the check transfer was created
          example: '2020-01-31T23:00:00Z'
        updated_at:
          type: string
          format: date-time
          description: The date and time the check transfer was last updated
          example: '2020-01-31T23:00:00Z'
    DisbursementApproval:
      type: object
      description: If your account requires approvals for disbursements and the disbursement was approved, this will contain the details of the approval.
      properties:
        approved_by:
          type: string
          description: If the disbursement was approved by a user in the dashboard, the email address of that user.
          example: user@example.com
        approved_at:
          type: string
          format: date-time
          description: The RFC 3339 date and time at which the Disbursement was approved.
          example: '2020-01-31T23:00:00Z'
          readOnly: true
    DisbursementVerification:
      type: object
      description: If the disbursement has been verified by Chariot, this will contain the verification details.
      properties:
        verified_at:
          type: string
          format: date-time
          description: The RFC 3339 date and time at which the Disbursement was verified.
          example: '2020-01-31T23:00:00Z'
          readOnly: true
    ProgramDetails:
      type: object
      description: Details about the program that the disbursement belongs to.
      properties:
        id:
          type: string
          description: The unique identifier for the program
          example: program_01jpjenf5q6cawy43yxfcrxhct
        name:
          type: string
          description: The name of the program
          example: Annual Grants
    TransactionCorporateMatch:
      type: object
      description: A corporate matching gift. Required when the transaction type is corporate_match.
      nullable: true
      required:
      - company_name
      properties:
        company_name:
          type: string
          description: 'The name of the company making the matching gift. Maximum length: 255 characters.'
          maxLength: 255
          example: Acme Corporation
    AccountTransfer:
      type: object
      description: An account transfer represents an instant, electronic transfer of funds.
      required:
      - transfer_id
      - amount
      - status
      - created_at
      - updated_at
      properties:
        transfer_id:
          type: string
          description: The unique identifier for the account transfer
          example: account_transfer_01j8rs605a4gctmbm58d87mvsj
          readOnly: true
        amount:
          type: integer
          format: int64
          description: The amount of the account transfer in minor currency units (cents)
          example: 10000
        status:
          type: string
          description: The status of the account transfer
          example: complete
          enum:
          - pending_approval
          - canceled
          - complete
        created_at:
          type: string
          format: date-time
          description: The date and time the account transfer was created
          example: '2020-01-31T23:00:00Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: The date and time the account transfer was last updated
          example: '2020-01-31T23:00:00Z'
          readOnly: true
    Person:
      type: object
      description: A person is an individual who is an officer of a nonprofit.
      required:
      - name
      properties:
        name:
          type: string
          description: The full name of the person
        title:
          type: string
          description: The title or role of the person with respect to the nonprofit entity
          example: Executive Director
    CreateDisbursementInput:
      type: object
      description: 'The request to create a disbursement and its corresponding transactions.

        The organization and amount are required.

        The transactions array should contain the list of transactions associated with the disbursement. The amounts

        in the transactions should sum up to the disbursement amount.'
      required:
      - organization_id
      - amount
      - transactions
      properties:
        organization_id:
          type: string
          description: The ID of the organization that will receive the disbursement.
          example: org_1234567890
        program_id:
          type: string
          description: 'The identifier for the program that the disbursement is associated with.

            The program must have grant_disbursement_status enabled.

            If not provided, your grant_disbursement_status enabled program will be used.

            If your Chariot account has multiple grant_disbursement_status enabled programs, you must specify the program_id to use for the disbursement.'
          example: program_01jpjenf5q6cawy43yxfcrxhct
          nullable: true
        amount:
          type: integer
          format: int64
          description: The disbursement amount in USD cents. Must be a positive amount.
          example: 10000
        auto_fund:
          type: boolean
          description: Enable just-in-time (JIT) funding for this disbursement. When true, Chariot will automatically create an inbound transfer for the disbursement amount when it is approved, eliminating the need to pre-fund your account. This feature must be enabled on your account. Contact Chariot to enable JIT disbursements.
          example: false
          default: false
        bypass_chariot_organization_verification:
          type: boolean
          description: 'By default (`false`), the disbursement will remain in the `awaiting_verification` status until

            Chariot''s compliance team has verified the nonprofit.

            If set to `true`, the disbursement will proceed through its normal lifecycle without waiting for

            Chariot to verify the organization. Only set this if you have independently verified the organization

            and do not want to wait for or rely on Chariot''s verification.

            This field is only relevant when disbursing to an organization that was created via a [verification request](/api/verification-requests/create).'
          default: false
        transactions:
          type: array
          description: 'The list of transactions associated with the disbursement.

            Each transaction is an individual donation to be included in the disbursement.

            Must specify at least one transaction.


            The sum of all transaction net amounts (amount - fee_amount) must equal the disbursement amount.'
          items:
            type: object
            description: 'An individual donation to be included in the disbursement.

              '
            required:
            - amount
            - type
            properties:
              amount:
                type: integer
                format: int64
                description: 'The gross transaction amount in minor currency units (cents) before any fees are deducted.

                  This represents the total amount of the donation.

                  '
                example: 10000
              internal_transaction_id:
                type: string
                description: 'A unique identifier for the transaction within the grantmaker''s internal system. Maximum length: 255 characters.'
                maxLength: 255
                example: GRANT-001
              fee_amount:
                type: integer
                format: int64
                description: 'Optional fee amount in minor currency units (cents) to be deducted from the transaction.

                  If provided, the fee amount must be less than the transaction amount.

                  The net amount (amount - fee_amount) will be used when calculating the disbursement total.

                  '
                example: 500
                nullable: true
              type:
                $ref: '#/components/schemas/DonationType'
              purpose:
                type: string
                description: 'The purpose of the grant. Maximum length: 600 characters.'
                maxLength: 600
                example: General operating support
              note:
                type: string
                description: 'A note to the recipient. Maximum length: 600 characters.'
                maxLength: 600
                example: Allocate to education
              recipient_name:
                type: string
                description: 'The intended recipient of the grant (for example, a fiscal sponsor''s project). Maximum length: 255 characters.'
                maxLength: 255
                example: Clean Water Project
              donors:
                $ref: '#/components/schemas/TransactionDonors'
              daf_grant:
                $ref: '#/components/schemas/TransactionDafGrant'
              corporate_match:
                $ref: '#/components/schemas/TransactionCorporateMatch'
              metadata:
                type: object
                description: Additional metadata for the transaction
                additionalProperties:
                  type: string
    NonprofitClassification:
      type: object
      description: A classification of the nonprofit entity as defined by the IRS.
      properties:
        group_exemption_number:
          type: string
          description: This is a four-digit internal IRS number assigned to central/parent entity holding group exemption letters.
        subsection_code:
          $ref: '#/components/schemas/TaxExemptCode'
        filing_requirement_code:
          $ref: '#/components/schemas/TaxExemptCode'
        foundation_code:
          $ref: '#/components/schemas/TaxExemptCode'
        affiliation_code:
          $ref: '#/components/schemas/TaxExemptCode'
        organization_code:
          $ref: '#/components/schemas/TaxExemptCode'
        exempt_status_code:
          $ref: '#/components/schemas/TaxExemptCode'
        deductibility_code:
          $ref: '#/components/schemas/TaxExemptCode'
        ntee_code:
          $ref: '#/components/schemas/NteeCode'
        naics_code:
          $ref: '#/components/schemas/NaicsCode'
    PostalTrackingUpdate:
      type: object
      description: The postal tracking update for the check
      required:
      - id
      - event_type
      - created_at
      properties:
        id:
          type: integer
          format: int64
          description: The unique identifier for the tracking update
          example: 1
          readOnly: true
        event_type:
          type: string
          description: "The event type of the tracking update.\nThe set of event types include:\n  - `in_transit`: The check has been processed by the origin facility.\n  - `processed_for_delivery`: The check has been greenlit for delivery at the recipient's nearest postal facility. The check should reach the mailbox within 1-2 business days of this tracking update.\n  - `delivered`: The check has been delivered to the recipient's address.\n  - `returned_to_sender`: The check has been returned to the sender due to barcode, ID tag area, or address errors."
          example: in_transit
          enum:
          - in_transit
          - processed_for_delivery
          - delivered
          - returned_to_sender
        created_at:
          type: string
          format: date-time
          description: The date and time the tracking update was created
          example: '2020-01-31T23:00:00Z'
    ComplianceRequirement:
      type: object
      description: A compliance requirement is a requirement that a nonprofit entity must meet in order to be eligible for Chariot services.
      properties:
        compliant:
          type: boolean
          description: Whether the entity is compliant with the requirement
          example: true
        reason:
          type: string
          description: The reason for the compliance requirement
        last_found_at:
          type: string
          format: date-time
          description: The date and time when the compliance requirement was last found
          example: '2020-01-31T23:00:00Z'
   

# --- truncated at 32 KB (106 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/chariot/refs/heads/main/openapi/chariot-disbursements-api-openapi.yml