Finicity Connect Components API

openapi: 3.2.0
info:
  title: Open Finance Connect Components API
  description: 'OpenAPI specification for Finicity APIs.


    Open Finance (formerly Open Banking) solutions in the US are provided by

    Finicity, a Mastercard company.'
  contact:
    name: API Support
    email: apisupport@mastercard.com
    url: https://developer.mastercard.com/open-finance-us/documentation/support/
  version: 1.43.0
servers:
- url: https://api.finicity.com
  description: Production
security:
- FinicityAppKey: []
  FinicityAppToken: []
tags:
- name: Connect Components
  description: Allow customers to log into their financial institutions and grant Finicity authorization
paths:
  /connect-components/institutions/{institution_id}/oauth-urls:
    parameters:
    - $ref: '#/components/parameters/InstitutionIdPathParameter'
    post:
      summary: Create OAuth URL
      operationId: post-institutions-institutionId-oauth-urls
      tags:
      - Connect Components
      responses:
        '201':
          $ref: '#/components/responses/GenerateOAuthUrl'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
      description: Generates a new OAuth URL that can be used to connect an end-user into their direct-connection institution. The `redirectURI` will be called when the oauth session has completed. An optional configuration object can be applied by including a valid `configurationId` in the request body.
      requestBody:
        $ref: '#/components/requestBodies/OauthUrl'
  /connect-components/institutions/{institution_id}/login-forms:
    parameters:
    - $ref: '#/components/parameters/InstitutionIdPathParameter'
    post:
      summary: Create Login Form
      operationId: post-institutions-institutionId-login-forms
      tags:
      - Connect Components
      responses:
        '201':
          $ref: '#/components/responses/LoginForms'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
      description: Generate a new login form for a given institution, customer, and language.
      requestBody:
        $ref: '#/components/requestBodies/LoginForm'
  /connect-components/customers/{customer_id}/institution-login-ids/{institution_login_id}/reconnections:
    parameters:
    - $ref: '#/components/parameters/CustomerIdPathParameter'
    - $ref: '#/components/parameters/InstitutionLoginIdPathParam'
    post:
      summary: Initiate Reconnection
      operationId: post-reconnections
      tags:
      - Connect Components
      responses:
        '201':
          $ref: '#/components/responses/LoginForms'
        '203':
          $ref: '#/components/responses/MfaChallenge'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      description: "Use the Data Connect Fix API when the following conditions occur:\n  * The connection to the user's financial institution is lost.\n  * The user's credentials were updated (for any number of reasons).\n  * The user's MFA challenge has expired."
      requestBody:
        $ref: '#/components/requestBodies/NoBody'
  /connect-components/configurations:
    post:
      summary: Create Components Configuration
      operationId: post-configurations
      tags:
      - Connect Components
      responses:
        '201':
          $ref: '#/components/responses/Configuration'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
      description: Optional endpoint. This endpoint is use to generate a configuration  object, which an then be passed in during the login flow. If used, the ID provided will need to be passed in the Create Login  Form or Create OAuth URL.
      requestBody:
        $ref: '#/components/requestBodies/CreateConfiguration'
    get:
      summary: Get All Configurations for Current Partner
      description: Get all previously saved Data Connect Component configurations.
      operationId: get-configurations
      tags:
      - Connect Components
      responses:
        '200':
          $ref: '#/components/responses/Configurations'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /connect-components/configurations/{configuration_id}:
    parameters:
    - $ref: '#/components/parameters/ConfigurationIdPathParameter'
    get:
      summary: Get Configuration Details
      tags:
      - Connect Components
      responses:
        '200':
          $ref: '#/components/responses/Configuration'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
      operationId: get-configurations-configurationId
      description: Returns the configuration with the specified id if the configuration exists and belongs to the partner calling this endpoint
    delete:
      summary: Delete Configuration
      tags:
      - Connect Components
      operationId: delete-configurations-configurationId
      responses:
        '204':
          $ref: '#/components/responses/NoBody'
        '401':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/ResourceNotFound'
      description: Removes the configuration from the database
components:
  responses:
    ResourceNotFound:
      description: The resource doesn't exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GoldStandardErrorMessage'
          examples:
            ResourceNotFoundExample:
              $ref: '#/components/examples/GoldStandardResourceNotFound'
    BadRequest:
      description: The request was rejected
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GoldStandardErrorMessage'
          examples:
            InvalidFieldExample:
              $ref: '#/components/examples/GoldStandardInvalidField'
    GenerateOAuthUrl:
      description: The returned oauth url, as well as a reference back to this resource in case modifications are needed
      content:
        application/json:
          schema:
            type: object
            description: The response object for requests to generate OAuth URLs
            required:
            - id
            - url
            - eventStreamId
            example:
              id: 8d9d8f5e-2c5f-4f49-bf9b-276a7df0367f
              url: https://example.com
              eventStreamId: 208a1170-875e-4656-85d0-27dfc3ee7137
            properties:
              id:
                type: string
                format: uuid
                example: 8d9d8f5e-2c5f-4f49-bf9b-276a7df0367f
                minLength: 36
                maxLength: 36
                description: Unique reference to the login session
              url:
                type: string
                format: uri
                example: https://example.com
                minLength: 1
                maxLength: 1024
                description: The oauth url to direct the user to
              eventStreamId:
                $ref: '#/components/schemas/EventStreamId'
    Configuration:
      description: An object used to modify the login behavior
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Configuration'
    LoginForms:
      description: Generate a new login form entry
      content:
        application/json:
          schema:
            type: object
            description: The data used by the calling application to render a login form
            example:
              id: 8d9d8f5e-2c5f-4f49-bf9b-276a7df0367f
              eventStreamId: 208a1170-875e-4656-85d0-27dfc3ee7137
              elements:
              - id: 26410b1f-0347-4d57-bb03-f44d00e785e2
                label: username
                sortOrder: 0
              - id: f2ce62c2-877f-4c26-9935-d1ab6084e6d0
                label: password
                sortOrder: 1
            properties:
              id:
                type: string
                minLength: 36
                maxLength: 36
                example: 8d9d8f5e-2c5f-4f49-bf9b-276a7df0367f
                format: uuid
                description: The unique identifier associated with this session'ed form
              eventStreamId:
                $ref: '#/components/schemas/EventStreamId'
              elements:
                type: array
                description: An array of elements that is to be rendered
                items:
                  type: object
                  minProperties: 1
                  maxProperties: 10
                  properties:
                    id:
                      type: string
                      format: uuid
                      minLength: 36
                      maxLength: 36
                      example: 26410b1f-0347-4d57-bb03-f44d00e785e2
                      description: The session specific identifier for the login form element
                    label:
                      type: string
                      description: The human-readable name of the element
                      example: Username
                      minLength: 1
                      maxLength: 512
                    sortOrder:
                      type: integer
                      default: 0
                      example: 0
                      minimum: 0
                      maximum: 10
                      description: A hint to indicate what order to render the elements in
                  required:
                  - id
                  - label
                  - sortOrder
            required:
            - id
            - elements
            - eventStreamId
    Unauthorized:
      description: The request lacks valid authentication credentials. Check "Finicity-App-Key" or "Finicity-App-Token".
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/GoldStandardErrorMessage'
          examples:
            ExpiredTokenExample:
              $ref: '#/components/examples/GoldStandardExpiredToken'
            MissingFinicityAppKeyExample:
              $ref: '#/components/examples/GoldStandardMissingFinicityAppKey'
    NoBody:
      description: Empty Response Body
    MfaChallenge:
      description: MFA challenges required to log in
      content:
        application/json:
          schema:
            type: array
            items:
              type: object
              properties:
                mfaChallenges:
                  type: array
                  minItems: 1
                  description: The required MFA Challenges required in order to log in.
                  items:
                    type: object
                    required:
                    - id
                    - prompt
                    - mfaType
                    - choiceIds
                    - eventStreamId
                    properties:
                      id:
                        type: string
                        description: The unique identifier for the MFA challenge
                        format: uuid
                        example: 9082affa-d965-40be-a3ed-a320bb3467ff
                        minLength: 36
                        maxLength: 36
                      mfaType:
                        type: string
                        description: "The type of MFA challenge:\n  * TFA_TEXT:  This challenge type will present a\nsingle input box to the customer and is commonly used for things like One-Time Passwords.\n  * TFA_CHOICE: The TFA_CHOICE object represents a\nmultiple choice question and answer selection.\n  * TFA_MULTI: The TFA_MULTI challenge type will\npresent the customer with multiple images to select from.\n  * TFA_IMAGE: A TFA_IMAGE challenge will present a\ncaptcha-style image the customer will need to decipher."
                        example: TFA_TEXT
                      prompt:
                        type: string
                        description: The MFA prompt text
                        example: Which high school did you attend
                      choiceIds:
                        type: array
                        description: An array of unique identifiers for the MFA choices
                        items:
                          type: string
                          description: The unique identifier for the MFA choice
                          format: uuid
                          example: 9082affa-d965-40be-a3ed-a320bb3467ff
                          minLength: 36
                          maxLength: 36
    Configurations:
      description: Array of available configurations
      content:
        application/json:
          schema:
            type: array
            description: The array of configuration objects associated with this partner
            items:
              $ref: '#/components/schemas/Configuration'
  parameters:
    InstitutionIdPathParameter:
      name: institution_id
      in: path
      description: The financial institution id at Mastercard.
      required: true
      schema:
        type: integer
      example: 170716
    CustomerIdPathParameter:
      description: Unique identifier of the customer
      name: customer_id
      in: path
      required: true
      schema:
        $ref: '#/components/schemas/CustomerId'
      example: '1005061234'
    InstitutionLoginIdPathParam:
      name: institution_login_id
      description: Institution login id of the customer.
      in: path
      required: true
      schema:
        type: integer
        format: int64
        example: 7008461438
    ConfigurationIdPathParameter:
      name: configuration_id
      in: path
      required: true
      schema:
        type: string
        format: uuid
        example: 9082affa-d965-40be-a3ed-a320bb3467ff
        minLength: 36
        maxLength: 36
      description: The unique identifier for a configuration object
  schemas:
    ServiceAgreement:
      description: An object that contains the language the terms and conditions were present in and the date the customer accepted the terms and conditions.
      type: object
      required:
      - language
      - acceptedDate
      properties:
        language:
          description: The language translation of the terms and conditions as presented to the customer.
          type: string
          example: en
        acceptedDate:
          description: The date the customer accepted the terms and conditions. Must be a valid ISO-8601 date time.
          type: string
          format: date-time
          example: '2024-11-28T18:25:32+00:00'
    FilterAccounts:
      type: array
      description: An optional filter to apply during account activation with institutions that support legacy login forms.
      items:
        type: string
        example: Checking
        minLength: 1
        maxLength: 512
    AccountClassificationType:
      type: array
      example:
      - personal
      - business
      description: 'An optional filter to apply during account activation with institutions that support Oauth integration. Supported filters are: `personal`, `business`, and `unknown`.'
      items:
        type: string
        example: personal
    GoldStandardErrorMessage:
      required:
      - Errors
      type: object
      properties:
        Errors:
          type: object
          required:
          - Error
          properties:
            Error:
              description: Mastercard standard error message.
              type: array
              items:
                type: object
                properties:
                  Source:
                    type: string
                    description: The applications that generated the error.
                  ReasonCode:
                    type: string
                    description: A unique constant identifying the error case encountered during processing.
                  Description:
                    type: string
                    description: Short description of the ReasonCode field.
                  Recoverable:
                    type: boolean
                    description: Indicates whether this error will always be returned for this request, or retrying could change the outcome.
                  Details:
                    type: string
                    description: Where appropriate, indicates detailed information about data received and calculated during request processing, to help the user with diagnosing errors.
    Configuration:
      title: Configuration
      type: object
      description: Used to modify behavior during the login flow
      properties:
        id:
          $ref: '#/components/schemas/ConfigurationId'
        filterAccounts:
          $ref: '#/components/schemas/FilterAccounts'
        accountClassificationType:
          $ref: '#/components/schemas/AccountClassificationType'
        aoRequired:
          $ref: '#/components/schemas/AoRequired'
    ConfigurationId:
      description: Unique identifier of the configuration object
      type: string
      format: uuid
      example: 605543e1-f507-48ad-8127-95c40566597b
      minLength: 36
      maxLength: 36
    CustomerId:
      type: string
      description: A customer ID. See Add Customer API for how to create a customer ID.
      example: '1005061234'
    AoRequired:
      type: boolean
      description: When set to true, the user must explicitly permission Account Owner details at OAuth-supported institutions. If they do not, a [239] error is returned, and the login attempt is blocked. Partners are responsible for handling user re-attempt flows to ensure proper permissions are granted
      default: false
      example: true
    EventStreamId:
      type: string
      format: uuid
      description: Unique reference to the event stream used to send events to the SDK
      minLength: 36
      maxLength: 36
      example: 208a1170-875e-4656-85d0-27dfc3ee7137
  examples:
    GoldStandardInvalidField:
      value:
        Errors:
          Error:
          - Source: Connect-Components,
            ReasonCode: 10010,
            Description: All request parameters could not be validated. Ensure you are sending the correct data in your headers, query parameters, and request body.
            Recoverable: false,
            Details: One or more of the fields could not be validated. Please ensure you have entered the correct data.
    GoldStandardResourceNotFound:
      value:
        Errors:
          Error:
          - Source: Connect-Components,
            ReasonCode: 4041,
            Description: The requested entity was not found,
            Recoverable: false,
            Details: The requested entity was not found
    GoldStandardExpiredToken:
      value:
        Errors:
          Error:
          - Source: Connect-Components,
            ReasonCode: 10023,
            Description: Expired (Finicity-App-Token),
            Recoverable: false,
            Details: Expired (Finicity-App-Token)
    GoldStandardMissingFinicityAppKey:
      value:
        Errors:
          Error:
          - Source: Connect-Components,
            ReasonCode: 10026,
            Description: Missing parameter (Finicity-App-Key)
            Recoverable: false,
            Details: Missing parameter (Finicity-App-Key)
  requestBodies:
    OauthUrl:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: Used to request an oauth url for a given a given institution and customer.
            required:
            - customerId
            - serviceAgreement
            - redirectURI
            properties:
              redirectURI:
                description: The `redirectURI` will be called when the oauth session has completed.
                type: string
                format: uri
                example: https://oauth.example.com/redirect
                minLength: 1
                maxLength: 1024
              customerId:
                $ref: '#/components/schemas/CustomerId'
              configurationId:
                $ref: '#/components/schemas/ConfigurationId'
              serviceAgreement:
                $ref: '#/components/schemas/ServiceAgreement'
    CreateConfiguration:
      required: true
      content:
        application/json:
          schema:
            type: object
            description: Used to generate a new configuration, which can be used during the login flow
            properties:
              filterAccounts:
                $ref: '#/components/schemas/FilterAccounts'
              accountClassificationType:
                $ref: '#/components/schemas/AccountClassificationType'
              aoRequired:
                $ref: '#/components/schemas/AoRequired'
    LoginForm:
      required: true
      description: "An optional configuration object can be applied by including a valid `configurationId` in the request body. <br><br> The preferred language translation for the login form is request with the `language` property in the request body. Supported languages are:\n  * English: `en`\n  * English-United States:'en-us`\n  * Spanish: `es`\n  * Spanish-United States: `es-us`\n  * French: `fr`\n  * French-Canada: `fr-ca`"
      content:
        application/json:
          schema:
            type: object
            description: Object used to generate a new session'ed login form.
            required:
            - language
            - customerId
            - serviceAgreement
            properties:
              language:
                type: string
                description: The preferred language translation of the requested login form. Supported languages are English:'en', English-United States:'en-us', Spanish:'es', Spanish-United States:'es-us', French:'fr', French-Canada:'fr-ca'
                example: en
              customerId:
                $ref: '#/components/schemas/CustomerId'
              configurationId:
                $ref: '#/components/schemas/ConfigurationId'
              serviceAgreement:
                $ref: '#/components/schemas/ServiceAgreement'
    NoBody:
      required: true
      content:
        application/json:
          schema:
            type:
            - object
            - 'null'
  securitySchemes:
    FinicityAppKey:
      name: Finicity-App-Key
      type: apiKey
      in: header
      description: The "Finicity-App-Key" from the developer dashboard
    FinicityAppToken:
      name: Finicity-App-Token
      type: apiKey
      in: header
      description: A token returned by the `/authentication` API