Chariot inboundTransfers API

openapi: 3.0.0
info:
  title: Chariot FDX Accounts inboundTransfers 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: inboundTransfers
paths:
  /v1/inbound_transfers:
    post:
      summary: Create an Inbound transfer
      description: 'Create an inbound transfer to fund your financial account

        from an externally linked bank account.

        In Production, this requires that an external bank account has been setup

        and verified for your account through the Chariot Dashboard.'
      operationId: createInboundTransfer
      tags:
      - inboundTransfers
      security:
      - bearerAuth: []
      parameters:
      - name: Idempotency-Key
        in: header
        description: The idempotency key for the request
        required: false
        schema:
          type: string
      requestBody:
        $ref: '#/components/requestBodies/CreateInboundTransferRequest'
      responses:
        '201':
          description: The inbound transfer was created
          headers:
            Location:
              $ref: '#/components/headers/Location'
            Idempotency-Key:
              $ref: '#/components/headers/Idempotency-Key'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundTransfer'
        '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 Inbound Transfers
      description: List inbound transfers for your account.
      operationId: listInboundTransfers
      tags:
      - inboundTransfers
      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: pageToken
        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
      responses:
        '200':
          $ref: '#/components/responses/ListInboundTransfersResponse'
        '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/inbound_transfers/{id}:
    get:
      summary: Get an Inbound Transfer
      description: Get an inbound transfer by its unique identifier.
      operationId: getInboundTransfer
      tags:
      - inboundTransfers
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: The unique identifier for the inbound transfer
        required: true
        schema:
          type: string
        example: inbound_transfer_01j8rs605a4gctmbm58d87mvsj
      responses:
        '200':
          description: The inbound transfer was retrieved
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundTransfer'
        '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/inbound_transfers/{id}/cancel:
    post:
      summary: Cancel an Inbound Transfer
      description: 'Cancel an inbound transfer.

        Returns the Inbound Transfer object if the cancelation succeeded.

        Returns a 412 Precondition Failed if the Inbound Transfer has already been canceled or cannot be canceled.'
      operationId: cancelInboundTransfer
      tags:
      - inboundTransfers
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: The unique identifier for the inbound transfer
        required: true
        schema:
          type: string
        example: inbound_transfer_01j8rs605a4gctmbm58d87mvsj
      responses:
        '200':
          description: The inbound transfer was canceled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InboundTransfer'
        '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'
        '412':
          $ref: '#/components/responses/PreconditionFailedError'
        '500':
          $ref: '#/components/responses/InternalServerError'
  /v1/simulations/inbound_transfers/{id}/fail:
    post:
      summary: 'Sandbox: Fail an Inbound Transfer'
      description: 'Simulate an inbound transfer failure.


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

        This API is only available in the sandbox environment.

        </Note>'
      operationId: simulateInboundTransferFailure
      tags:
      - inboundTransfers
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: The unique identifier for the inbound transfer
        required: true
        schema:
          type: string
        example: inbound_transfer_01j8rs605a4gctmbm58d87mvsj
      responses:
        '202':
          description: The inbound transfer failure 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/inbound_transfers/{id}/complete:
    post:
      summary: 'Sandbox: Complete an Inbound Transfer'
      description: 'Simulate an inbound transfer completion.


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

        This API is only available in the sandbox environment.

        </Note>'
      operationId: simulateInboundTransferCompletion
      tags:
      - inboundTransfers
      security:
      - bearerAuth: []
      parameters:
      - name: id
        in: path
        description: The unique identifier for the inbound transfer
        required: true
        schema:
          type: string
        example: inbound_transfer_01j8rs605a4gctmbm58d87mvsj
      responses:
        '202':
          description: The inbound transfer 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'
components:
  responses:
    PreconditionFailedError:
      description: Precondition Failed
      headers:
        X-Request-Id:
          $ref: '#/components/headers/X-Request-Id'
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/ProblemDetails'
          examples:
            PreconditionFailed:
              value:
                type: about:blank
                title: API Error
                status: 412
                detail: A precondition for the request was not met.
    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.
    ListInboundTransfersResponse:
      description: The response for InboundTransfers.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/InboundTransfer'
              nextPageToken:
                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.
    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.
    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.
    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.
  schemas:
    InboundTransfer:
      type: object
      description: An inbound transfer represents a transfer of funds from an external bank account to a financial account.
      required:
      - id
      - amount
      - created_at
      properties:
        id:
          type: string
          description: The unique identifier for the inbound transfer
          example: inbound_transfer_01j8rs605a4gctmbm58d87mvsj
          readOnly: true
        amount:
          type: integer
          format: int64
          description: 'The amount of the inbound transfer in minor currency units (cents).

            This amount must be positive.'
          example: 10000
        description:
          type: string
          description: An arbitrary string attached to the object. Often useful for displaying to users.
          example: InboundTransfer from my bank account
        status:
          type: string
          description: 'The status of the inbound transfer.

            An Inbound Transfer is `pending` if it created and the funds haven''t been received yet.

            The status changes to `completed` when the funds have been received and the balance of the financial account has been updated.

            The status changes to `canceled` if the transfer is canceled.

            The status changes to `failed` if the transfer fails.'
          example: pending
          enum:
          - pending
          - completed
          - canceled
          - failed
        created_at:
          type: string
          format: date-time
          description: The date and time the inbound transfer was created
          example: '2020-01-31T23:00:00Z'
          readOnly: true
        updated_at:
          type: string
          format: date-time
          description: The date and time the inbound transfer was last updated
          example: '2020-01-31T23:00:00Z'
          readOnly: true
    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.
  requestBodies:
    CreateInboundTransferRequest:
      description: The request body for originating an inbound transfer from an external bank account
      required: true
      content:
        application/json:
          schema:
            type: object
            required:
            - amount
            - account_id
            properties:
              amount:
                type: number
                description: 'The amount of the transfer in cents.

                  This amount must be positive.'
                example: 10000
              account_id:
                type: string
                description: The identifier of the financial account that will receive the transfer.
                example: account_01jpjenf5q6cawy43yxfcrxhct
              description:
                type: string
                description: An arbitrary string attached to the object. Often useful for displaying to users.
                example: Inbound ACH Transfer from my bank account
  headers:
    X-Request-Id:
      description: The unique identifier for the request
      schema:
        type: string
    Idempotency-Key:
      description: Idempotency key for the request
      schema:
        type: string
    Location:
      description: The URI of the created object
      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