Chariot disbursements API
The disbursements API from Chariot — 9 operation(s) for disbursements.
OpenAPI Specification
openapi: 3.2.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:
ProblemDetails:
type: object
description: RFC 7807 problem-details error (media type application/problem+json). The `status` field is an integer HTTP status code.
required:
- type
- title
- status
- detail
properties:
type:
type: string
description: A URI reference identifying the problem type.
example: about:blank
title:
type: string
description: A short, human-readable summary of the problem type.
example: API Error
status:
type: integer
description: The HTTP status code for this error.
example: 400
detail:
type: string
description: A human-readable explanation specific to this occurrence.
example: The request is invalid or contains invalid parameters.
example:
type: about:blank
title: API Error
status: 400
detail: The request is invalid or contains invalid parameters.
AchTransfer:
type: object
description: An ACH transfer represents an electronic transfer of funds via the Automated Clearing House (ACH) payment network.
required:
- transfer_id
- amount
- status
- created_at
properties:
transfer_id:
type: string
description: The unique identifier for the ACH transfer
example: ach_transfer_01j8rs605a4gctmbm58d87mvsj
readOnly: true
amount:
type: integer
format: int64
description: 'The amount of the ACH transfer in minor currency units (cents).
For ACH debits, this is a negative number.'
example: 10000
status:
type: string
description: "The lifecycle status of the ACH transfer.\nPossible values include:\n - `initiated`: The ACH transfer has been initiated and is pending submission to the Federal Reserve.\n - `submitted`: The ACH transfer has been submitted to the Federal Reserve.\n - `completed`: The ACH transfer has been completed. Funds should be settled.\n - `rejected`: The ACH transfer was rejected.\n - `returned`: The ACH transfer was returned by the receiving organization."
example: initiated
enum:
- initiated
- submitted
- completed
- rejected
- returned
direction:
type: string
description: The direction of the ACH transfer.
example: credit
enum:
- credit
- debit
standard_entry_class_code:
type: string
description: The Standard Entry Class (SEC) code for the ACH transfer.
example: corporate_credit_or_debit
enum:
- corporate_credit_or_debit
- prearranged_payments_and_deposit
- internet_initiated
company_entry_description:
type: string
description: 'The company entry description for the ACH transfer.
This is included in the transfer data sent to the receiving bank.'
example: Disbursement to nonprofit
trace_number:
type: string
description: 'A 15 digit number recorded in the Nacha file and transmitted to the receiving bank.
Along with the amount, date, and originating routing number, this can be used to identify the ACH transfer at the receiving bank.
ACH trace numbers are not unique, but are used to correlate returns.'
example: 012345678901234
effective_date:
type: string
format: date-time
description: 'The ACH transfer''s effective date as sent to the Federal Reserve.
This is the date the funds will be available to the receiving organization.'
example: '2020-01-31T23:00:00Z'
submitted_at:
type: string
format: date-time
description: The date and time the ACH transfer was submitted to the Federal Reserve.
example: '2020-01-31T23:00:00Z'
settled_at:
type: string
format: date-time
description: 'The date and time at which the ACH transfer was settled.
If the transfer is not settled, this will be null.'
example: '2020-07-12 15:00:00.000'
rejected_at:
type: string
format: date-time
description: 'The date and time at which the ACH transfer was rejected.
If the transfer is not rejected, this will be null.'
example: '2020-07-12 15:00:00.000'
returned_at:
type: string
format: date-time
description: 'The date and time at which the ACH transfer was returned.
If the transfer is not returned, this will be null.'
example: '2020-07-12 15:00:00.000'
created_at:
type: string
format: date-time
description: The date and time the ACH transfer was created
example: '2020-01-31T23:00:00Z'
readOnly: true
updated_at:
type: string
format: date-time
description: The date and time the ACH transfer was last updated
example: '2020-01-31T23:00:00Z'
readOnly: true
DisbursementStatus:
type: string
description: "The lifecycle status of the disbursement.\nPossible values include:\n - `pending_approval`: The disbursement is awaiting approval from the grantmaker\n - `canceled`: The disbursement was canceled by the grantmaker\n - `awaiting_verification`: The disbursement is awaiting verification from Chariot\n - `rejected`: The disbursement was rejected by Chariot before being submitted\n - `validating_organization`: Validating recipient organization's payment and contact information before submission.\n - `awaiting_account_claim`: The disbursement is awaiting account claim by the nonprofit or check delay expiration\n - `awaiting_balance`: The disbursement is awaiting sufficient grantmaker balance\n - `submitted`: The disbursement payment has been submitted to the payment network and is being processed\n - `stopped`: The disbursement payment was stopped after it was submitted\n - `completed`: The disbursement payment has been completed and funds have been received by the receiving organization\n - `failed`: The disbursement payment failed or the receiving organization did not receive the payment\n\nTo see a description of each status, see the \"Disbursement Lifecycle\" section of the Chariot documentation."
example: pending_approval
enum:
- pending_approval
- canceled
- awaiting_verification
- rejected
- validating_organization
- awaiting_account_claim
- awaiting_balance
- submitted
- stopped
- completed
- failed
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
TransactionDafGrant:
type:
- object
- 'null'
description: A simplified DAF grant object containing the fund name.
properties:
fund_name:
type: string
description: 'The name of the DAF fund that made the grant. Maximum length: 255 characters.'
maxLength: 255
example: Smith Family Fund
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'
Address:
type: object
required:
- city
- country
- line1
- postal_code
- state
properties:
city:
type: string
description: 'City, district, suburb, town, or village. Maximum length: 255 characters.'
example: New York
country:
type: string
description: Two-letter country code (https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2)
example: US
line1:
type: string
description: 'Address line 1 (e.g. street, PO Box, or company name). Maximum length: 255 characters.'
example: 123 Main St.
line2:
type: string
description: 'Address line 2 (e.g. apartment, suite, unit, or building). Maximum length: 255 characters.'
postal_code:
type: string
description: 'ZIP or postal code. Maximum length: 40 characters.'
example: '12345'
state:
type: string
description: State, county, province, or region
example: NY
NteeCode:
type: object
description: A code that is used to classify the nonprofit entity as defined by the IRS.
required:
- code
- description
properties:
code:
type: string
description: The code of the NTEE code
example: A
description:
type: string
description: The description of the NTEE code
example: Animal Welfare
parent_code:
type: string
description: The parent code of the NTEE code
example: A
parent_description:
type: string
description: The description of the parent NTEE code
example: Animal Welfare
WebDomain:
type: object
description: 'A web domain is a unique identifier for a website or web application that is associated with an organization.
Domains are important identity constructs that underpin the web and online interactions.
The domain can be used as an identifier and its validity can be asserted via DNS.'
required:
- domain
properties:
domain:
type: string
description: The DNS domain name
example: redcross.org
Disbursement:
type: object
description: A disbursement moves funds to a verified organization.
required:
- id
- organization_id
- program_id
- amount
properties:
id:
type: string
description: The unique identifier for the disbursement
example: disbursement_01jpjen1s23s29kkmnjsb6fzga
readOnly: true
organization_id:
type: string
description: The unique identifier for the organization that will receive the payment
example: org_01jpjenf5q6cawy43yxfcrxhct
organization:
$ref: '#/components/schemas/Organization'
program_id:
type: string
description: The unique identifier for the program that the disbursement belongs to
example: program_01jpjenf5q6cawy43yxfcrxhct
amount:
type: integer
format: int64
description: The payment amount in USD cents. Must be a positive amount.
example: 10000
description:
type: string
description: A description for the disbursement
example: Annual grant to Acme Inc.
auto_fund:
type: boolean
description: Whether just-in-time (JIT) funding is enabled for this disbursement. When true, Chariot automatically creates an inbound transfer for the disbursement amount when it is approved.
example: false
readOnly: true
created_at:
type: string
format: date-time
description: The date and time the disbursement was created
example: '2020-01-31T23:00:00Z'
readOnly: true
updated_at:
type: string
format: date-time
description: The date and time the disbursement was last updated
example: '2020-01-31T23:00:00Z'
readOnly: true
status:
$ref: '#/components/schemas/DisbursementStatus'
cancelation:
$ref: '#/components/schemas/DisbursementCancelation'
approval:
$ref: '#/components/schemas/DisbursementApproval'
rejection:
$ref: '#/components/schemas/DisbursementRejection'
verification:
$ref: '#/components/schemas/DisbursementVerification'
stop:
$ref: '#/components/schemas/DisbursementStop'
program_details:
$ref: '#/components/schemas/ProgramDetails'
transfers:
type: array
description: 'The list of transfers for the disbursement.
This can have multiple items if the disbursement''s underlying payment was retried multiple times.
For example, if a check was returned or stopped and the disbursement was retried as an ACH transfer.
If the disbursement was not retried, this will have a single item.'
items:
$ref: '#/components/schemas/DisbursementTransfer'
bypass_chariot_organization_verification:
type: boolean
description: 'Whether the disbursement bypasses Chariot''s organization verification.
When true, the disbursement proceeds without waiting for Chariot to verify the organization.'
example: false
transactions:
type: array
description: The list of transactions for the disbursement
items:
$ref: '#/components/schemas/Transaction'
idempotency_key:
type: string
description: The `Idempotency-Key` header value the disbursement was created with. Only set for single-create disbursements; bulk-created disbursements omit this field.
example: 8e91b2f3-d7c4-4a59-9a91-72a40b1f2c3d
readOnly: true
DisbursementTransfer:
type: object
description: 'After a disbursement is submitted, this object contains additional details about the transfer.
This is useful if you want to track the disbursement over the specific payment rails/networks.
An account transfer is the preferred transfer method when the receiving organization has a Chariot account at the same bank as the grantmaker.
An ACH transfer is used when the receiving organization has a Chariot account at a different bank than the grantmaker.
A check transfer is used when the receiving organization does not have a Chariot account.'
properties:
account_transfer:
$ref: '#/components/schemas/AccountTransfer'
ach_transfer:
$ref: '#/components/schemas/AchTransfer'
check_transfer:
$ref: '#/components/schemas/CheckTransfer'
real_time_payments_transfer:
$ref: '#/components/schemas/RealTimePaymentsTransfer'
StopDisbursementPaymentReason:
type: string
description: "The reason for stopping a disbursement payment.\nPossible values include:\n - `mail_delivery_failure`: The check could not be delivered.\n - `not_authorized`: The check was not authorized.\n - `voided`: The check was stopped and voided.\n - `unknown`: The reason for stopping the disbursement payment is unknown."
example: mail_delivery_failure
enum:
- mail_delivery_failure
# --- 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