Chariot donations API

openapi: 3.0.0
info:
  title: Chariot FDX Accounts donations 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: donations
paths:
  /v1/donations:
    get:
      summary: List Donations
      description: List donations for your account.
      operationId: listDonations
      tags:
      - donations
      security:
      - bearerAuth: []
      parameters:
      - name: 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: page_token
        in: query
        description: The cursor to use for pagination. If not set, the first page of results will be returned.
        required: false
        schema:
          type: string
      - name: payment_source_id
        in: query
        description: The unique identifier for the payment sources to filter donations by. Comma separated list of payment source IDs.
        required: false
        schema:
          type: string
        example: payment_source_01j8rs605a4gctmbm58d87mvsj
      - name: deposit_id
        in: query
        description: The unique identifier for the deposit to filter donations by.
        required: false
        schema:
          type: string
        example: deposit_01j8rs605a4gctmbm58d87mvsj
      - name: created_at.after
        in: query
        description: Return donations created after the given date and time.
        required: false
        schema:
          type: string
          format: date-time
      - name: created_at.before
        in: query
        description: Return donations created before the given date and time.
        required: false
        schema:
          type: string
          format: date-time
      responses:
        '200':
          $ref: '#/components/responses/ListDonationsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/donations/{id}:
    get:
      summary: Get a Donation
      description: Get a donation by its unique identifier.
      operationId: getDonation
      tags:
      - donations
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: The unique identifier for the donation
        required: true
        schema:
          type: string
        example: donation_01j8rs605a4gctmbm58d87mvsj
      responses:
        '200':
          description: The donation was retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Donation'
        '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:
    PropertyAssignment:
      type: object
      description: A property assignment is a key-value pair that is associated with a donation.
      properties:
        property_id:
          type: string
          description: The unique identifier for the property.
          example: prop_01j8rs605a4gctmbm58d87mvsj
        value:
          $ref: '#/components/schemas/PropertyValue'
    DonationInitiation:
      type: object
      description: 'If the donation was initiated through a Chariot Connect instance (DAFpay), this object will contain additional information

        about the initiation of the donation.'
      required:
      - initiated_at
      - frequency
      properties:
        initiated_at:
          type: string
          readOnly: true
          format: date-time
          description: Time when the donation was initiated. Expressed in RFC 3339 format.
          example: '2020-01-31T23:59:59Z'
        channel:
          type: string
          description: "The DAFpay integration channel used to initiate the donation.\n- `INTEGRATED` - The donation was initiated through an integrated DAFpay instance where the DAF sponsor\n  processes the grant electronically via the DAFpay network.\n- `UNINTEGRATED` - The donation was initiated through an unintegrated DAFpay flow where the donor\n  completes the grant manually on the DAF sponsor's website (e.g., Luminate Online, standalone embeds)."
          example: INTEGRATED
          enum:
          - INTEGRATED
          - UNINTEGRATED
        web_location_url:
          type: string
          description: The URL of the web location where the donation was initiated.
          example: https://www.example.com/donation/1234567890
        fundraising_platform_name:
          type: string
          description: The name of the fundraising platform that initiated the donation.
          example: Classy
        dafpay_form:
          type: string
          description: The DAFpay form where the donation was initiated.
          example: DAF day
        dafpay_tracking_id:
          type: string
          description: The tracking ID for the donation as generated by DAFpay.
          example: L9E182VBGP
        dafpay_metadata:
          type: object
          description: Additional key value pairs that were passed to DAFpay during the donation initiation.
          additionalProperties:
            type: string
          example:
            funding_source: DAF
            funding_source_id: daf_01j8rs605a4gctmbm58d87mvsj
            funding_source_name: DAF day
        frequency:
          type: string
          description: The frequency of the donation.
          example: ONE_TIME
          enum:
          - ONE_TIME
          - MONTHLY
    Platform:
      type: object
      description: A subhash containing information about the platform that facilitated the donation.
      properties:
        name:
          type: string
          description: The name of the platform.
          example: PayPal Grant Payments
        platform_grant_id:
          type: string
          description: The identifier for the grant within the platform's system.
          example: 93492947-7894-4663-a944-f2469d0027ca
        metadata:
          type: object
          description: Additional key value pairs that were passed to the platform during the donation initiation.
          additionalProperties:
            type: string
        acceptance:
          description: 'A subhash containing information about the acceptance of the grant from the platform.

            This is only present if the platform requires grant acceptance before disbursing funds.'
          allOf:
          - $ref: '#/components/schemas/PlatformAcceptance'
    DonationAttribution:
      type: object
      description: A subhash containing information about how the donation is attributed.
      properties:
        primary_donor:
          description: A subhash containing information about the primary donor of the donation.
          allOf:
          - $ref: '#/components/schemas/Donor'
        joint_donor:
          description: A subhash containing information about the joint donor of the donation.
          allOf:
          - $ref: '#/components/schemas/Donor'
    Artifact:
      type: object
      description: An artifact is a source file that was used to create the donation.
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier for the artifact.
          example: artifact_01j8rs605a4gctmbm58d87mvsj
        name:
          type: string
          description: The name of the artifact.
          example: donation_receipt.pdf
        file_id:
          type: string
          description: The unique identifier for the file that the artifact is associated with.
          example: file_01j8rs605a4gctmbm58d87mvsj
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: The date and time when the artifact was created.
          example: '2020-01-31T23:59:59Z'
    DafGrant:
      type: object
      description: A subhash containing information grant details from a Donor-Advised Fund sponsor.
      required:
      - organization_name
      properties:
        organization_name:
          type: string
          description: The name of the Donor Advised Fund sponsor.
          readOnly: true
          example: Daffy Charitable Fund
        donor_fund_name:
          type: string
          description: The name of the donor's fund at the Donor Advised Fund sponsor.
          example: The Smith Family Fund
        program_name:
          type: string
          description: The name of the program at the Donor Advised Fund sponsor.
        sponsor_grant_id:
          type: string
          description: The identifier for the grant at the Donor Advised Fund sponsor.
          example: 93492947-7894-4663-a944-f2469d0027ca
    PlatformAcceptance:
      type: object
      description: A subhash containing information about the acceptance of the grant from the platform.
      properties:
        accepted:
          type: boolean
          description: Whether the grant was accepted from the platform.
          example: true
        expires_at:
          type: string
          format: date-time
          description: The date and time when the acceptance of the grant will expire.
          example: '2020-01-31T23:59:59Z'
    DonationSettlement:
      type: object
      description: 'If the payment for the donation was received by Chariot, this object will contain additional information

        about the settlement of the donation.'
      required:
      - deposit_id
      - received_at
      properties:
        deposit_id:
          type: string
          description: The unique identifier for the deposit that contains the money for the donation.
          example: deposit_01kewb5vgsryzaajza5ynr06kz
        received_at:
          type: string
          readOnly: true
          format: date-time
          description: 'The date and time when the transfer of money for the donation was received by Chariot.

            Received at indicates when the data for the transfer was received, which is different from the settled_at timestamp.

            Expressed in RFC 3339 format.'
          example: '2020-01-31T23:59:59Z'
        settled_at:
          type: string
          readOnly: true
          format: date-time
          description: 'The date and time when the money for the donation was settled by Chariot.

            Indicates when the funds become available to the nonprofit.

            Expressed in RFC 3339 format.'
          example: '2020-01-31T23:59:59Z'
    Donor:
      type: object
      description: The donor information for the transaction
      properties:
        full_name:
          type: string
          description: 'The full name of the donor. Maximum length: 255 characters.'
          example: John Doe
        first_name:
          type: string
          description: 'The first name of the donor. Maximum length: 255 characters.'
          example: John
        last_name:
          type: string
          description: 'The last name of the donor. Maximum length: 255 characters.'
          example: Doe
        email:
          type: string
          description: 'The email address of the donor. Maximum length: 255 characters.'
          example: bob@me.com
        phone:
          type: string
          description: 'The phone number of the donor. Maximum length: 20 characters.'
          example: 415-555-1212
        address:
          $ref: '#/components/schemas/Address'
    PropertyValue:
      type: object
      required:
      - type
      properties:
        type:
          $ref: '#/components/schemas/PropertyType'
        text_value:
          type: string
          description: The text value of the property.
        enum_value_id:
          type: string
          description: The unique identifier for the enum value.
        user_value_id:
          type: string
          description: The unique identifier for the user.
        boolean_value:
          type: boolean
          description: The boolean value of the property.
        date_value:
          type: string
          format: date-time
          description: The date value of the property.
        empty:
          type: boolean
          description: 'Whether the property value is empty.

            Can use this to unset property values when assigning a property.'
    Donation:
      type: object
      description: A Donation is a gift of money to a nonprofit organization.
      required:
      - id
      - payment_source_id
      - amount_gross
      - amount_net
      - amount_fee
      - currency
      - purpose
      - note
      - created_at
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier for the donation
          example: donation_01j8rs605a4gctmbm58d87mvsj
        payment_source_id:
          type: string
          description: The unique identifier for the payment source used to segregate deposits between various DAFs and platforms.
          example: payment_source_01kew60ks7w0epkvp2bgqxrt8z
        amount_gross:
          type: integer
          format: int64
          description: 'The original amount of the donation as intended by the donor in minor units of the currency.

            For dollars, for example, this is cents.'
        amount_net:
          type: integer
          format: int64
          description: 'The amount of the donation that the nonprofit will receive after DAF and/or

            platform processing fees are deducted in minor units of the currency.

            For dollars, for example, this is cents.'
        amount_fee:
          type: integer
          format: int64
          description: 'The amount of the fee that was deducted by the DAF or processing platform from the donation in minor units of the currency.

            For dollars, for example, this is cents.'
        individual_gift_amount:
          type: integer
          format: int64
          description: The amount contributed by the individual donor in minor units of the currency.
        currency:
          type: string
          description: The [ISO 4217 code](https://en.wikipedia.org/wiki/ISO_4217) for the Transaction's currency.
          example: USD
        purpose:
          type: string
          description: 'A description of the donor''s intent for the donation.

            This is useful to understand how the donor intended the donation to be used.

            For example, "Where needed most" or "General Operating Support" or "Specific Campaign".'
          example: Where needed most
        note:
          type: string
          description: 'An informational note from the donor to the nonprofit about the donation.

            This may contain a message or other useful information that the donor wants to share with the nonprofit.'
          example: Please dedicate in memory of grandma
        attribution:
          description: A subhash containing information about how the donation is attributed.
          allOf:
          - $ref: '#/components/schemas/DonationAttribution'
        initiation:
          description: A subhash containing information about how the donation was initiated by DAFpay.
          allOf:
          - $ref: '#/components/schemas/DonationInitiation'
        settlement:
          description: A subhash containing information about how the donation was settled by Chariot.
          allOf:
          - $ref: '#/components/schemas/DonationSettlement'
        donor_advised_fund_grant:
          description: A subhash containing information about the grant from a Donor-Advised Fund sponsor.
          allOf:
          - $ref: '#/components/schemas/DafGrant'
        platform:
          description: 'A subhash containing information about the platform that facilitated the donation.

            If this is empty, then the donation was not facilitated by a platform.'
          allOf:
          - $ref: '#/components/schemas/Platform'
        corporate_match:
          description: 'A subhash containing information about the corporate match for the donation.

            If this is empty, then the donation was not matched by a corporate sponsor.'
          allOf:
          - $ref: '#/components/schemas/CorporateMatch'
        properties:
          type: array
          description: A list of custom properties for the donation.
          items:
            $ref: '#/components/schemas/PropertyAssignment'
        artifacts:
          type: array
          description: 'A list of source artifacts that were used to create the donation.

            These can include the raw source files (PDFs, CSVs, etc.) that were received from upstream platforms or systems.'
          items:
            $ref: '#/components/schemas/Artifact'
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: The date and time when the donation was created.
          example: '2020-01-31T23:59:59Z'
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: The date and time when the donation was last updated.
          example: '2020-01-31T23:59:59Z'
        canceled_at:
          type: string
          readOnly: true
          format: date-time
          nullable: true
          description: 'The date and time when the donation was canceled.

            A non-null value indicates the donation is tied to a canceled grant initiation

            and the gift was not received. Expressed in RFC 3339 format.'
          example: '2020-01-31T23:59:59Z'
        payment_status:
          type: string
          readOnly: true
          description: The payment status of the donation. Indicates the current state of the payment lifecycle.
          example: INCOMING_TO_CHARIOT
          enum:
          - INCOMING_TO_CHARIOT
          - INCOMING_OUTSIDE_CHARIOT
          - RECEIVED_IN_CHARIOT
          - RECEIVED_OUTSIDE_CHARIOT
          - CANCELED
    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
    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.
    CorporateMatch:
      type: object
      description: A subhash containing information about the corporate match for the donation.
      properties:
        match_amount:
          type: integer
          format: int64
          description: The amount of the corporate match for the donation in minor units of the donation currency.
        company_name:
          type: string
          description: The name of the company that matched the donation.
          example: Google
        program_name:
          type: string
          description: The name of the program that matched the donation.
          example: Google Matching Grant Program
        source:
          type: string
          description: The source of the corporate match.
          example: Payroll
    PropertyType:
      type: string
      description: The data type of a property.
      enum:
      - text
      - enum
      - user
      - boolean
      - date
      example: text
  responses:
    BadRequestError:
      description: The request is invalid or contains invalid parameters
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            BadRequest:
              value:
                type: about:blank
                title: API Error
                status: 400
                detail: The request is invalid or contains invalid parameters.
    ForbiddenError:
      description: Access denied
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            Forbidden:
              value:
                type: about:blank
                title: API Error
                status: 403
                detail: You do not have permission to access this resource.
    NotFoundError:
      description: Resource Not Found
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            NotFound:
              value:
                type: about:blank
                title: API Error
                status: 404
                detail: The requested resource was not found.
    ListDonationsResponse:
      description: The response for Donations.list
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/json:
          schema:
            type: object
            properties:
              results:
                type: array
                items:
                  $ref: '#/components/schemas/Donation'
              next_page_token:
                type: string
                description: "A cursor token to use to retrieve the next page of results by making another API call\n to the same endpoint with the same parameters (only changing the pageToken). If\n specified, then more results exist on the server that were not returned, otherwise\n no more results exist on the server."
    InternalServerError:
      description: Internal Server Error
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            InternalServerError:
              value:
                type: about:blank
                title: API Error
                status: 500
                detail: The server encountered an error processing your request.
    AuthenticationError:
      description: Unauthorized. The request is missing the security (OAuth2 Bearer token) requirements and the server is unable to verify the identify of the caller.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            Unauthorized:
              value:
                type: about:blank
                title: API Error
                status: 401
                detail: Authentication credentials were missing or invalid.
  headers:
    X-Request-Id:
      description: The unique identifier for the request
      schema:
        type: string
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 Bearer token. A client may hold both scopes, but each FDX authorization must contain exactly one — they are mutually exclusive per authorization. An authorization containing both will be rejected. See the Authentication page for token exchange details.
      flows:
        authorizationCode:
          authorizationUrl: https://dashboard.givechariot.com/oauth/authorize
          tokenUrl: https://api.givechariot.com/auth/oauth/token
          scopes:
            read:bank_accounts: Read access to bank account data
            sync:connected_accounts: Sync access to connected account data