Chariot recurring_grants API

openapi: 3.0.0
info:
  title: Chariot FDX Accounts recurring_grants 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: recurring_grants
paths:
  /v1/recurring_grants:
    get:
      summary: List Recurring Grants
      description: Returns a list of all recurring grants for a given Connect. This API allows for paginating over many results.
      operationId: list-recurring-grants
      tags:
      - recurring_grants
      security:
      - bearerAuth: []
      parameters:
      - name: connect_id
        in: query
        description: the `id` of the Connect object. This can be used to filter the recurring grants by a specific Connect if you have more than one.
        schema:
          type: string
        required: false
        example: live_2d821da0ed8bc7256e260f4eb5244f2d8f06c576342f922ba2f0a416d8c98002
      - name: pageLimit
        in: query
        description: the number of results to return; defaults to 10, max is 100
        schema:
          type: integer
          default: 10
      - name: pageToken
        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.
        schema:
          type: string
      responses:
        '200':
          $ref: '#/components/responses/ListRecurringGrantsResponse'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '500':
          $ref: '#/components/responses/InternalServerError'
    post:
      summary: Create Recurring Grant
      description: 'Create and submit a new recurring grant. This should be used to capture a recurring grant intent from an authorized DAFpay workflow session and submit the recurring grant request to the DAF sponsor.


        <Warning>

        Error handling:

        - The recurring grant must be captured within 15 minutes of authorization otherwise the request will return status `410 Gone`.

        - A recurring grant can only be captured once from any given workflow session so any duplicate requests will return status `409 Conflict`.

        - The amount must be in whole dollar increments (rounded to the nearest hundred) as currently DAFs only accept whole dollar grants otherwise the request will return status `400 Bad Request`.

        - The amount must be greater than or equal to the minimum grant amount for the DAF otherwise the request will return status `400 Bad Request`.

        - The amount must be less than or equal to the user''s DAF account balance otherwise the request will return status `400 Bad Request`.

        - Any inputs exceeding the maximum allowed length will be automatically truncated unless otherwise stated.

        </Warning>'
      operationId: create-recurring-grant
      tags:
      - recurring_grants
      security:
      - bearerAuth: []
      requestBody:
        $ref: '#/components/requestBodies/RecurringGrantCaptureRequest'
      responses:
        '201':
          description: Created recurring grant
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
            Location:
              description: The URI reference of the created recurring grant object.
              schema:
                type: string
                format: uri
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringGrant'
              examples:
                Simple:
                  $ref: '#/components/examples/RecurringGrantOutput'
        '400':
          $ref: '#/components/responses/BadRequestError'
        '401':
          $ref: '#/components/responses/AuthenticationError'
        '403':
          $ref: '#/components/responses/ForbiddenError'
        '404':
          $ref: '#/components/responses/NotFoundError'
        '409':
          $ref: '#/components/responses/ConflictError'
        '410':
          $ref: '#/components/responses/GoneError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/recurring_grants/{id}:
    get:
      summary: Get Recurring Grant
      description: Retrieve a recurring grant with a given ID.
      operationId: get-recurring-grant
      tags:
      - recurring_grants
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: 'The unique id of the recurring grant.

          The format should be a v4 UUID according to RFC 4122.'
        schema:
          type: string
          format: uuid
        required: true
        example: 10229488-08d2-4629-b70c-a2f4f4d25344
      responses:
        '200':
          description: OK
          headers:
            X-Request-Id:
              $ref: '#/components/headers/X-Request-Id'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RecurringGrant'
              examples:
                Simple:
                  $ref: '#/components/examples/RecurringGrantOutput'
        '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:
  responses:
    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.
    GoneError:
      description: Resource Gone or Expired
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            Gone:
              value:
                type: about:blank
                title: API Error
                status: 410
                detail: The resource is no longer available.
    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.
    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.
    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.
    ConflictError:
      description: Resource Conflicts
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            Conflict:
              value:
                type: about:blank
                title: API Error
                status: 409
                detail: The request conflicts with the current state of the resource.
    ListRecurringGrantsResponse:
      description: The response for RecurringGrants.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/RecurringGrant'
              nextPageToken:
                type: string
                description: A cursor token to use to retrieve the next page of results by making another API call to the same endpoint with the same parameters (only changing the pageToken). If specified, then more results exist on the server that were not returned, otherwise no more results exist on the server.
          example:
            results:
            - id: 29650c10-1eb3-4f97-a63e-f2e41c145b53
              workflowSessionId: b76fa69f-c554-43b2-af9a-1d4bb9a02016
              fundId: daf-id
              createdAt: '2021-08-10 15:00:00.000'
              updatedAt: '2021-08-11 15:34:00.000'
              amount: 15000
              frequency: MONTHLY
            nextPageToken: c3f685f2-2dda-4956-815b-39867a5e5638
    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.
  examples:
    RecurringGrantOutput:
      summary: Simple recurring grant output.
      value:
        id: 1e60800e-849b-43d1-870e-57afc8d75473
        workflowSessionId: cfe09e64-6a74-4dab-a565-361185a6f248
        fundId: daf-id
        createdAt: '2021-08-10 15:00:00.000'
        updatedAt: '2021-08-11 15:34:00.000'
        amount: 15000
        frequency: MONTHLY
  schemas:
    GrantAddress:
      type: object
      properties:
        line1:
          type: string
          description: 'Address line 1 (e.g. street, PO Box, or company name). Maximum length: 255 characters.'
        line2:
          type: string
          description: 'Address line 2 (e.g. apartment, suite, unit, or building). Maximum length: 255 characters.'
        city:
          type: string
          description: 'City, district, suburb, town, or village.. Maximum length: 255 characters.'
        state:
          type: string
          description: 'State, county, province, or region. Maximum length: 255 characters.'
        postalCode:
          type: string
          description: 'ZIP or postal code. Maximum length: 255 characters.'
    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.
    RecurringGrant:
      type: object
      description: 'A RecurringGrant represents a successfully initiated recurring grant request with a Donor Advised Fund.

        RecurringGrants are created when a person interacts with an instance of Chariot Connect and successfully submits a recurring grant and completes the workflow.

        On creation, each RecurringGrant object will also have a Grant object created to represent the first grant of the recurring grant.

        There can be many grants associated with the same recurring grant.'
      required:
      - id
      - workflowSessionId
      - fundId
      - amount
      - frequency
      properties:
        id:
          type: string
          readOnly: true
          description: The unique identifier for the object
          format: uuid
          example: cfe09e64-6a74-4dab-a565-361185a6f248
        trackingId:
          type: string
          readOnly: true
          description: The tracking ID for the grant
          example: L9E182VBGP
        workflowSessionId:
          type: string
          readOnly: true
          description: ID of the Connect Workflow Session associated with this grant
          format: uuid
          example: 2d4b2a43-a5b4-4be1-ad1f-f932016ca4a6
        fundId:
          type: string
          readOnly: true
          description: ID of the donor advised fund
          example: daf-id
        frequency:
          type: string
          description: How often the DAF provider will submit the recurring grant. At the moment, monthly is the only supported frequency.
          enum:
          - MONTHLY
          example: MONTHLY
        externalRecurringGrantId:
          type: string
          description: ID of the grant associated with the donor advised fund
          example: 897823sdjf8sfjs
        createdAt:
          type: string
          readOnly: true
          format: date-time
          description: Time when this object was created; expressed in RFC 3339 format
          example: '2020-01-31T23:00:00Z'
        updatedAt:
          type: string
          readOnly: true
          format: date-time
          description: Time when this object was last updated; expressed in RFC 3339 format
          example: '2020-01-31T23:59:59Z'
        amount:
          type: number
          format: integer
          description: The grant amount expressed in units of whole cents
          example: 15000
        firstName:
          type: string
          description: The donor's first name
          example: Warren
        lastName:
          type: string
          description: The donor's last name
          example: Buffet
        phone:
          type: string
          description: The donor's phone number
          example: '1237861020'
        email:
          type: string
          description: The donor's email
          example: warrenBuffet@example.com
        note:
          type: string
          description: An note inputted by the user at submisson
          example: Please dedicate in memory of grandma
        address:
          $ref: '#/components/schemas/GrantAddress'
  requestBodies:
    RecurringGrantCaptureRequest:
      description: 'The request to create and submit a monthly recurring grant. This is useful to capture a recurring grant intent associated with Connect workflow session.

        The request should specify the grant amount. The grant will re-occur according to the scheduled frequency or recurrence of the request.

        The recurring grant will continue indefinitely until the donor runs out of funds or until the donor cancels the recurring grant with their DAF provider.

        Some DAF providers require an end-date or number of payments in order to create a recurring grant.

        In most cases, the recurring grant will continue indefinitely until the donor''s account runs out of funds or until the donor cancels the recurring grant with their DAF provider.

        Some DAF providers require an explicit bound to the time period or the number of payments in which case currently we opt for the longest recurring donation timeline possible.

        For example, if the DAF provider allows recurring donations to continue for up to 10 years we will submit the request as such.

        This is the amount submitted for processing by the DAF.'
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
            - workflowSessionId
            - amount
            - frequency
            properties:
              workflowSessionId:
                type: string
                description: 'The identifier of the donor''s DAFpay Workflow Session.

                  See [Capturing Grant Intents](/guides/dafpay/integrating-dafpay/integration#capturing-grant-intents) for how to get this value from the DAFpay `CHARIOT_SUCCESS` event.'
              frequency:
                type: string
                description: The recurrence interval schedule for the recurring grant. Currently, only `MONTHLY` is supported.
                enum:
                - MONTHLY
                example: MONTHLY
              amount:
                type: number
                example: 15000
                description: 'The final grant amount in cents that will be processed by Chariot and submitted to the DAF for recurring gifts.

                  This amount must be in whole dollar increments (rounded to the nearest hundred) as currently

                  all DAFs only accept whole dollar grants.'
              applicationFeeAmount:
                type: number
                example: 3000
                description: 'This parameter specifies the fee your platform plans to take from the first grant in cents.

                  This is a fee in addition to Chariot''s processing fee. With application fees,

                  Chariot collects the fee you determine from the nonprofit and passes it to your platform.

                  Please note that platform fees are only taken when the grant is successfully received by the nonprofit.

                  The sum of Chariot''s fee and the applicationFeeAmount cannot exceed 5% of the grant''s amount.

                  If the 5% limit is exceeded, a 400 error will be returned.'
              donor:
                type: object
                properties:
                  firstName:
                    type: string
                    description: 'The first name of the donor. Maximum length: 255 characters.'
                  lastName:
                    type: string
                    description: 'The last name of the donor. Maximum length: 255 characters.'
                  email:
                    type: string
                    description: 'The email address of the donor. Maximum length: 255 characters.'
                  phone:
                    type: string
                    description: 'The phone number of the donor. Maximum length: 255 characters.'
                  address:
                    $ref: '#/components/schemas/GrantAddress'
              note:
                type: string
                description: 'A note the donor wants to send to the nonprofit. Maximum length: 400 characters.'
              designation:
                type: string
                description: 'The designation to include on the grant. If this is left blank, "Where needed most" will be used.

                  Note that including a custom designation may cause the grant approval process to take longer.

                  Designations over 100 characters will be truncated.'
  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