openapi: 3.0.2
info:
  title: Finix Authorizations Onboarding Forms API
  description:
    $ref: api-descriptions/main.md
  contact:
    name: Finix
    url: https://finix.com
    email: support@finixpayments.com
  version: '2022-02-01'
servers:
- description: Sandbox server to be used for testing and development
  url: https://finix.sandbox-payments-api.com
security:
- BasicAuth: []
tags:
- name: Onboarding Forms
  description:
    $ref: api-descriptions/tags/onboarding-forms.md
paths:
  /onboarding_forms:
    parameters: []
    post:
      summary: Create an Onboarding Form
      operationId: createOnboardingForm
      responses:
        '200':
          $ref: '#/components/responses/OnboardingForm'
        '401':
          $ref: '#/components/responses/ErrorUnauthorized'
        '403':
          $ref: '#/components/responses/ErrorForbidden403'
        '404':
          $ref: '#/components/responses/ErrorNotFound'
        '406':
          $ref: '#/components/responses/Error406NotAcceptable'
        '422':
          $ref: '#/components/responses/Error422InvalidField'
      description: 'Create an `onboarding_form` with the name of the processor you plan to onboard users to and the links they` get redirected to when completing or moving away from the Finix Onboarding Form.


        Only **ROLE_PARTNER** credentials can be used to create an `onboarding_form`.'
      requestBody:
        $ref: '#/components/requestBodies/CreateOnboardingFormRequest'
      tags:
      - Onboarding Forms
      x-java-method-name: create
      x-codeSamples:
      - lang: cURL
        label: curl
        source:
          $ref: xcode/curl/onboarding-form/create-onboarding-form.md
      x-python-method-name: create
  /onboarding_forms/{onboarding_form_id}:
    parameters:
    - schema:
        type: string
      name: onboarding_form_id
      description: The id of the `onboarding_form`.
      in: path
      required: true
    get:
      summary: Fetch an Onboarding Form
      operationId: getOnboardingForm
      responses:
        '200':
          $ref: '#/components/responses/OnboardingForm'
        '401':
          $ref: '#/components/responses/ErrorUnauthorized'
        '403':
          $ref: '#/components/responses/ErrorForbidden403'
        '404':
          $ref: '#/components/responses/ErrorNotFound'
        '406':
          $ref: '#/components/responses/Error406NotAcceptable'
        '422':
          $ref: '#/components/responses/Error422InvalidField'
      description: Retrieve the details of an `onboarding_form`.
      tags:
      - Onboarding Forms
      x-java-method-name: get
      x-codeSamples:
      - lang: cURL
        label: curl
        source:
          $ref: xcode/curl/onboarding-form/fetch-onboarding-form.md
      x-python-method-name: get
  /onboarding_forms/{onboarding_form_id}/links:
    parameters:
    - schema:
        type: string
      name: onboarding_form_id
      in: path
      required: true
      description: The ID of the `onboarding_form` resource.
    post:
      summary: Create an Onboarding Form Link
      operationId: createOnboardingFormLink
      responses:
        '200':
          $ref: '#/components/responses/OnboardingFormLink'
        '401':
          $ref: '#/components/responses/ErrorUnauthorized'
        '403':
          $ref: '#/components/responses/ErrorForbidden403'
        '404':
          $ref: '#/components/responses/ErrorNotFound'
        '406':
          $ref: '#/components/responses/Error406NotAcceptable'
        '422':
          $ref: '#/components/responses/Error422InvalidField'
      description: Use the `onboarding_forms` API to create a link that can return users to where they left off completing their Finix Onboarding Form.
      requestBody:
        $ref: '#/components/requestBodies/CreateOnboardingFormLinkRequest'
      tags:
      - Onboarding Forms
      x-java-method-name: createLink
      x-codeSamples:
      - lang: cURL
        label: curl
        source:
          $ref: xcode/curl/onboarding-form/onboarding-form-link.md
      x-python-method-name: create_link
components:
  schemas:
    Error422InvalidFieldList:
      type: object
      description: Invalid field
      title: ''
      properties:
        total:
          type: integer
        _embedded:
          type: object
          properties:
            errors:
              type: array
              items:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                    - INVALID_FIELD
                  field:
                    type: string
                  logref:
                    $ref: '#/components/schemas/LogRef'
                  message:
                    type: string
                  _links:
                    type: object
                    properties:
                      source:
                        type: object
                        properties:
                          href:
                            type: string
    Error403ForbiddenList:
      type: object
      properties:
        total:
          type: integer
        _embedded:
          type: object
          properties:
            errors:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  code:
                    type: string
                    enum:
                    - FORBIDDEN
                  logref:
                    $ref: '#/components/schemas/LogRef'
                  message:
                    type: string
                  _links:
                    type: object
                    properties:
                      source:
                        type: object
                        properties:
                          href:
                            type: string
      description: ''
      title: ''
    UpdatedAt:
      type: string
      title: UpdatedAt
      format: date-time
      description: Timestamp of when the object was last updated.
    OnboardingForm:
      type: object
      x-examples: {}
      title: OnboardingForm
      properties:
        id:
          type: string
          description: The ID of the `onboarding_form` resource.
        created_at:
          $ref: '#/components/schemas/CreatedAt'
        updated_at:
          $ref: '#/components/schemas/UpdatedAt'
        merchant_processors:
          type: array
          description: An array of objects with the processors and gateways users will be onboarded to.
          items:
            type: object
            properties:
              processor:
                type: string
                description: The name of the processor you plan to onboard users to.
        onboarding_data:
          $ref: '#/components/schemas/OnboardingFormOnboardingData'
        onboarding_link:
          type: object
          description: The information of the initial onboarding link. This is only provided when creating an `onboarding_form`.
          properties:
            expires_at:
              type: string
              description: A UTC timestamp detailing when the onboarding form expires and will no longer be available via `link_url`. To generate a new link to the same form, see [Get an Onboarding Form URL](/guides/onboarding/onboarding-form/#get-an-onboarding-form-url).
            link_url:
              type: string
              description: The URL of the user's Finix Onboarding Form. Users can use the `link_url` to return to the form until the link expires.
        status:
          type: string
          description: Status of the `onboarding_from`.
          enum:
          - IN_PROGRESS
          - COMPLETED
        tags:
          $ref: '#/components/schemas/Tags'
    Error404NotFoundList:
      type: object
      properties:
        total:
          type: integer
        _embedded:
          type: object
          properties:
            errors:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  code:
                    type: string
                    enum:
                    - NOT_FOUND
                  logref:
                    $ref: '#/components/schemas/LogRef'
                  message:
                    type: string
                  _links:
                    type: object
                    properties:
                      source:
                        type: object
                        properties:
                          href:
                            type: string
    LogRef:
      title: LogRef
      type: object
      properties:
        logref:
          type: string
    OnboardingFormOnboardingData:
      title: OnboardingFormOnboardingData
      x-stoplight:
        id: lu5e8v4djdyv7
      type: object
      description: The prefilled information of the user that's being onboarded. For more information, see [Prefilling Fields](/guides/onboarding/onboarding-forms/#prefilling-fields).
      properties:
        additional_underwriting_data:
          type: object
          description: Additional underwriting data about the user.
          properties:
            annual_ach_volume:
              type: integer
              description: The approximate annual ACH sales expected to be processed (in cents) by this merchant (max 10 characters).
            average_ach_transfer_amount:
              type: integer
              description: The approximate average ACH sale amount (in cents) for this merchant.
            average_card_transfer_amount:
              type: integer
              description: The average credit card sale amount (in cents) for this merchant.
            business_description:
              type: string
              minLength: 1
              description: Description of this merchant's business (max 200 characters).
            card_volume_distribution:
              type: object
              description: The distribution of the merchant's credit card volume The sum of `card_volume_distribution` must be 100.
              nullable: true
              properties:
                card_present_percentage:
                  type: integer
                  description: The percentage of the merchant's volume that's card present (between 0 and 100).
                ecommerce_percentage:
                  type: integer
                  description: The percentage of the merchant's business that is eCommerce (between 0 and 100).
                mail_order_telephone_order_percentage:
                  type: integer
                  description: The percentage of the merchant's business that is a mail or telephone order (between 0 and 100).
            credit_check_allowed:
              type: boolean
              description: Sets if this merchant has consented and accepted to a credit check.
            credit_check_ip_address:
              type: string
              minLength: 1
              description: The IP address of the merchant when they consented to a credit check (e.g., 42.1.1.112 ).
            credit_check_timestamp:
              type: string
              minLength: 1
              description: A timestamp of when this merchant consented to a credit check (e.g., 2021-04-28T16:42:55Z).
            credit_check_user_agent:
              type: string
              minLength: 1
              description: The details of the browser that was used when this merchant consented to a credit check (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)).
            merchant_agreement_accepted:
              type: boolean
              description: Sets whether this merchant has accepted the terms and conditions of the merchant agreement.
            merchant_agreement_ip_address:
              type: string
              minLength: 1
              description: IP address of the merchant when this merchant accepted the merchant agreement (e.g., 42.1.1.113).
            merchant_agreement_timestamp:
              type: string
              minLength: 1
              description: Timestamp of when the merchant accepted Finix's Terms of Service (e.g., 2021-04-28T16:42:55Z).
            merchant_agreement_user_agent:
              type: string
              minLength: 1
              description: The details of the browser that was used when this merchant accepted Finix's Terms of Service (e.g., Mozilla 5.0 (Macintosh; Intel Mac OS X 10 _14_6)).
            refund_policy:
              type: string
              minLength: 1
              description: Include the value that best applies to the merchant's refund policy.
              enum:
              - NO_REFUNDS
              - MERCHANDISE_EXCHANGE_ONLY
              - WITHIN_30_DAYS
              - OTHER
            volume_distribution_by_business_type:
              type: object
              description: Merchant's distribution of credit card volume by business type. Sum of `volume_distribution_by_business_type` must be 100.
              nullable: true
              properties:
                business_to_business_volume_percentage:
                  type: integer
                  description: The percentage of the merchant's volume that's business to business (between 0 and 100).
                business_to_consumer_volume_percentage:
                  type: integer
                  description: The percentage of the merchant's volume that's business to consumer (between 0 and 100).
                consumer_to_consumer_volume_percentage:
                  type: integer
                  description: Merchant's percentage of volume that is consumer to consumer (between 0 and 100).
                other_volume_percentage:
                  type: integer
                  description: The percentage of the merchant's volume that isn't represented by the previous fields (between 0 and 100).
                person_to_person_volume_percentage:
                  type: integer
                  description: The percentage the merchant's volume that's person to person (between 0 and 100).
        associated_entities:
          type: array
          description: The `entities` saved in the `associated_identities` of the user. For more information, see [Create an Associated Identity](/guides/onboarding/onboarding-form/#prefilling-fields).
          items:
            type: object
            description: Underwriting data that's required to verify the `Identity`.
            properties:
              annual_card_volume:
                type: integer
                description: The annual credit card sales (in cents) expected to be processed (max 19 characters).
              business_address:
                type: object
                description: The primary address for the legal entity.
                nullable: true
                properties:
                  city:
                    type: string
                    description: City (max 20 characters).
                    minLength: 1
                  country:
                    type: string
                    minLength: 1
                  line2:
                    type: string
                    minLength: 1
                    description: Second line of the address (max 35 characters).
                  line1:
                    type: string
                    minLength: 1
                    description: First line of the address (max 35 characters).
                  postal_code:
                    type: string
                    minLength: 1
                    description: Zip or Postal code (max 7 characters).
                  region:
                    type: string
                    minLength: 1
                    description: 2-letter state code.
              business_name:
                type: string
                minLength: 1
                description: Abbreviated names of the business. If there are no abbreviated name, leave this field blank.
                nullable: true
              business_phone:
                type: string
                minLength: 1
                description: Customer service phone number where the merchant can be reached (max 10 characters).
              business_tax_id:
                type: string
                minLength: 1
                description: Nine digit Tax Identification Number (TIN), Employer Identification Number (EIN). If the `business_type` is **INDIVIDUAL\_SOLE\_PROPRIETORSHIP** and they do not have an EIN, use the sole proprietor's Social Security Number (SSN).
              business_type:
                type: string
                minLength: 1
                description: Include the value that best applies to the merchant.
                enum:
                - INDIVIDUAL_SOLE_PROPRIETORSHIP
                - CORPORATION
                - LIMITED_LIABILITY_COMPANY
                - PARTNERSHIP
                - ASSOCIATION_ESTATE_TRUST
                - TAX_EXEMPT_ORGANIZATION
                - INTERNATIONAL_ORGANIZATION
                - GOVERNMENT_AGENCY
              default_statement_descriptor:
                type: string
                minLength: 1
                description: The description of the merchant that appears on the buyer's bank or card statement.
              dob:
                type: object
                description: 'The control owner''s date of birth.

                  '
                properties:
                  day:
                    type: integer
                  month:
                    type: integer
                  year:
                    type: integer
              doing_business_as:
                type: string
                minLength: 1
                description: Alternate names of the business. If there are no other names, pass the same value used for `business_name` (max 60 characters).
              email:
                type: string
                minLength: 1
                description: The email address of the principal control owner where they can be reached (max 100 characters).
              first_name:
                type: string
                minLength: 1
                description: The legal first name of the control owner (max 20 characters).
              has_accepted_credit_cards_previously:
                type: boolean
                description: Defaults to **false** if not passed.
              incorporation_date:
                type: object
                description: The date the company was founded and registered.
                nullable: true
                properties:
                  day:
                    type: integer
                    description: Day business was incorporated (between 1 and 31).
                  month:
                    type: integer
                    description: Month business was incorporated (between 1 and 12).
                  year:
                    type: integer
                    description: Year business was incorporated (4-digit).
              last_name:
                type: string
                minLength: 1
                description: The `Identity` owner's legal last name.
              max_transaction_amount:
                type: integer
                description: The maximum amount (in cents) that can be charged for a single transaction (max 12 characters).
              mcc:
                type: string
                minLength: 1
                description: The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card\_x/mcc.pdf)) that this merchant will be classified under. For a list of approved MCCs, see [Approved Merchant Category Codes.](/docs/guides/business/security-and-compliance/approved-merchants/)
              ownership_type:
                type: string
                minLength: 1
                description: 'Values can be either:

                  <ul><li><strong>PUBLIC</strong> to indicate a publicly-traded company.

                  <li><strong>PRIVATE</strong> for privately-held businesses.'
                nullable: true
              personal_address:
                type: object
                description: The home address of the principal control owner. This field is used for identity verification purposes.
                properties:
                  city:
                    type: string
                    minLength: 1
                    description: City (max 20 characters).
                  country:
                    type: string
                    minLength: 1
                    description: 3-Letter country code (e.g. USA).
                  line1:
                    type: string
                    minLength: 1
                    description: First line of the address (max 35 characters).
                  line2:
                    type: string
                    minLength: 1
                    description: Second line of the address (max 35 characters).
                  postal_code:
                    type: string
                    minLength: 1
                    description: Zip or Postal code (max 7 characters).
                  region:
                    type: string
                    minLength: 1
                    description: 2-letter State code.
              phone:
                type: string
                minLength: 1
                description: The principal control owner's phone number (max 10 characters).
              principal_percentage_ownership:
                type: integer
                description: Percentage of the company owned by the principal control owner (min 0; max 100).
              tax_id:
                type: string
                minLength: 1
                description: Details if the `tax_id` was provided.
              title:
                type: string
                minLength: 1
                description: The corporate title of the control owner (e.g. Chief Executive Officer, CFO, etc. Max 60 characters).
              url:
                type: string
                minLength: 1
                description: The URL of the `Identity` owner's public website.
        entity:
          type: object
          description: The `entity` information saved in the `Identity` of the user.
          properties:
            amex_mid:
              type: integer
              description: Assigned amexMid value. If a value is passed, it must be 10 or 11 digits.
              nullable: true
            annual_card_volume:
              type: integer
              description: The annual credit card sales (in cents) expected to be processed by this seller (max 19 characters).
              nullable: true
            business_address:
              type: object
              description: The primary address for the legal entity.
              nullable: true
              properties:
                line1:
                  type: string
                  minLength: 1
                  description: First line of the address (max 35 characters).
                  nullable: true
                line2:
                  type: string
                  minLength: 1
                  description: Second line of the address (max 35 characters).
                  nullable: true
                city:
                  type: string
                  minLength: 1
                  description: City (max 20 characters).
                  nullable: true
                region:
                  type: string
                  minLength: 1
                  description: 2-letter state code.
                  nullable: true
                postal_code:
                  type: string
                  minLength: 1
                  description: Zip or Postal code (max 7 characters).
                  nullable: true
                country:
                  type: string
                  minLength: 1
                  description: 3-Letter Country code (e.g. USA).
                  nullable: true
            business_name:
              type: string
              minLength: 1
              description: The merchant's legal business name (max 120 characters).<ul><li>If <strong>INDIVIDUAL_SOLE_PROPRIETORSHIP</strong>, pass the owner's legal first name, last name and middle initial.
              nullable: true
            business_phone:
              type: string
              minLength: 1
              description: Customer service phone number where the seller can be reached (max 10 characters).
              nullable: true
            business_tax_id_provided:
              type: boolean
              description: Details if the `business_tax_id` was provided.
            business_type:
              description: Include the value that best applies to the seller.
              type: string
              nullable: true
            default_statement_descriptor:
              type: string
              minLength: 1
              description: The description of the seller that appears on the buyer's bank or card statement.
              nullable: true
            discover_mid:
              description: Assigned discoverMid value.
              type: integer
              nullable: true
            dob:
              type: object
              description: The control owner's date of birth.
              nullable: true
              properties:
                day:
                  type: integer
                  description: Day of birth (between 1 and 31).
                  minimum: 1
                month:
                  type: integer
                  description: Month of birth (between 1 and 12).
                  minimum: 1
                year:
                  type: integer
                  description: Year of birth (4-digit). Year must be greater than 1900.
                  minimum: 1900
            doing_business_as:
              type: string
              minLength: 1
              description: Alternate names of the business. If there are no other names, pass the same value used for `business_name` (max 60 characters).
              nullable: true
            email:
              type: string
              minLength: 1
              description: The email address of the principal control owner where they can be reached (max 100 characters).
              nullable: true
            first_name:
              type: string
              minLength: 1
              description: The legal first name of the merchant's control owner (max 20 characters).
              nullable: true
            has_accepted_credit_cards_previously:
              type: boolean
              description: Defaults to **false** if not passed.
            incorporation_date:
              type: object
              description: The date the company was founded and registered with the US.
              nullable: true
              properties:
                day:
                  type: integer
                  description: Day business was incorporated (between 1 and 31).
                month:
                  type: integer
                  description: Month of birth (between 1 and 12).
                year:
                  type: integer
                  description: Year business was incorporated (4-digit).
            last_name:
              type: string
              minLength: 1
              description: The legal last name of the merchant's control owner (max 20 characters).
              nullable: true
            max_transaction_amount:
              type: integer
              description: The maximum amount (in cents) that can be charged for a single transaction (max 12 characters).
              nullable: true
            mcc:
              type: string
              minLength: 1
              description: The Merchant Category Code ([MCC](http://www.dm.usda.gov/procurement/card/card\_x/mcc.pdf)) that this merchant will be classified under. For a list of approved MCCs, see [Approved Merchant Category Codes.](/docs/guides/business/security-and-compliance/approved-merchants/)
              nullable: true
            ownership_type:
              type: string
              minLength: 1
              description: 'Values can be either: <ul><li><strong>PUBLIC</strong> to indicate a publicly-traded company.<li><strong>PRIVATE</strong> for privately-held businesses.'
              enum:
              - PUBLIC
              - PRIVATE
              nullable: true
            personal_address:
              type: object
              description: The home address of the merchant's principal control owner. This field is used for identity verification purposes.
              nullable: true
              properties:
                line1:
                  type: string
                  minLength: 1
                  description: First line of the address (max 35 characters).
                  nullable: true
                line2:
                  type: string
                  minLength: 1
                  description: Second line of the address (max 35 characters).
                  nullable: true
                city:
                  type: string
                  minLength: 1
                  description: City (max 20 characters).
                  nullable: true
                region:
                  type: string
                  minLength: 1
                  description: 2-letter State code.
                  nullable: true
                postal_code:
                  type: string
                  minLength: 1
                  description: Zip or Postal code (max 7 characters).
                  nullable: true
                country:
                  type: string
                  minLength: 1
                  description: 3-Letter country code (e.g. USA).
                  nullable: true
            phone:
              type: string
              minLength: 1
              description: The principal control owner's phone number (max 10 characters).
              nullable: true
            principal_percentage_ownership:
              type: integer
              description: Percentage of the company owned by the principal control owner (min 0; max 100).
              nullable: true
            short_business_name:
              type: string
              description: Abbreviated names of the business. If there are no abbreviated name, leave this field blank.
              nullable: true
            tax_authority:
              type: string
              description: <ul><li>Only required when onboarding a seller with a <tt>MCC</tt> of <strong>9311</strong>.<li> The <tt>tax_authority</tt> is the tax gathering entity (e.g San Francisco Water Authority).
              nullable: true
            tax_id_provided:
              type: boolean
              description: Details if the `tax_id` was provided.
            title:
              type: string
              minLength: 1
              description: The corporate title of the control owner (e.g. Chief Executive Officer, CFO, etc. Max 60 characters).
              nullable: true
            url:
              type: string
              minLength: 1
              description: The URL of the merchant's public website.
              nullable: true
        payment_instruments:
          type: object
          description: The `Payment Instrument` that'll be used to payout the seller. For more information, see [Payouts](/guides/payouts/).
          properties:
            account_number:
              type: string
              description: The bank account number (no dashes in between numbers).
            acount_type:
              type: string
              description: 'The type of bank account. Use the following respective enum when creating a `Payment Instrument` for:<ul><li><strong>CHECKING: </strong>The checking account of your buyer.</li><li><strong>SAVINGS: </strong>The savings account of your buyer.</li><li><strong>CORPORATE: </strong>A corporate checking account.</li><li><strong>CORP_SAVINGS: </strong>A corporate savings account.</li><li><strong>BUSINESS_CHECKING: </strong>A checking account primarily owned by a business.</li><li><strong>BUSINESS_SAVINGS: </strong>A savings account primarily owned by a business</li><li><strong>PERSONAL_CHECKING: </strong>Seller''s using their personal checking account.</li><li><strong>PERSONAL_SAVINGS: </strong>Seller''s using their personal savings account.</li></ul>'
            attempt_bank_account_validation_check:
              enum:
              - CHECKING
              - SAVINGS
              - PERSONAL_CHECKING
              - PERSONAL_SAVINGS
              - BUSINESS_CHECKING
              - BUSINESS_SAVINGS
              - CORPORATE
              - CORP_SAVINGS
            bank_code:
              type: string
              description: The routing number of the bank account.
            name:
              type: string
              description: The name of the bank account owner.
            type:
              type: string
              description: Type of `Payment Instrument`.
              enum:
              - BANK_ACCOUNT
        max_transaction_amount:
          type: integer
          description: Maximum amount that can be transacted for a single transaction in cents (max 12 characters). Must be equal to or less than your `max_transaction_amount`.
    CreateOnboardingFormRequest:
      type: object
      x-examples: {}
      title: CreateOnboardingFormRequest
      properties:
        onboarding_data:
          $ref: '#/components/schemas/OnboardingFormOnboardingData'
        merchant_processors:
          type: array
          description: An array of objects with the processors and gateways users will be onboarded to.
          items:
            type: object
            properties:
              processor:
                type: string
                description: The name of the processor you plan to onboard users to.
        onboarding_link_details:
          type: object
          description: The information of the initial onboarding link. This is only provided when creating an `onboarding_form`.
          properties:
            expiration_in_minutes:
              type: string
              description: How long (in minutes) the link should be valid for. Defaults to 60 minutes.
            expired_session_url:
              type: string
              description: The URL users get sent to if the bearer token expires.
            fee_details_url:
              type: string
              description: The URL of the page where you display the fees related to processing payments (for more info, see [Displaying Processing Fees](/guides/onboarding/onboarding-form/#displaying-processing-fees)).
            return_url:
              type: string
              description: The URL users get sent to after completing the onboarding flow.
            terms_of_service_url:
              type: string
              description: Your Terms of Service URL. The URL is provided to users for consent along with [Finix's Terms of Service](https://finix-hosted-content.s3.amazonaws.com/flex/v2/finix-terms-of-service.html).
        tags:
          $ref: '#/components/schemas/Tags'
    CreateOnboardingFormLinkRequest:
      type: object
      x-examples: {}
      title: CreateOnboardingFormLinkRequest
      properties:
        expiration_in_minutes:
          type: integer
          description: How long (in minutes) the link should be valid for. Defaults to 60 minutes.
        expired_session_url:
          type: string
          description: The URL users get sent to if the bearer token expires.
        fee_details_url:
          type: string
          description: The URL of the page where you display the fees related to processing payments (for more info, see [Displaying Processing Fees](/guides/onboarding/onboarding-form/#displaying-processing-fees)).
        return_url:
          type: string
          description: The URL users get sent to after completing the onboarding flow.
        terms_of_service_url:
          type: string
          description: Your Terms of Service URL. The URL is provided to users for consent along with Finix's Terms of Service.
    Error406NotAcceptable:
      type: object
      properties:
        total:
          type: integer
        _embedded:
          type: object
          properties:
            errors:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  code:
                    type: string
                    enum:
                    - NOT_FOUND
                  logref:
                    $ref: '#/components/schemas/LogRef'
                  message:
                    type: string
                  _links:
                    type: object
                    properties:
                      source:
                        type: object
                        properties:
                          href:
                            type: string
      title: ''
    OnboardingFormLink:
      type: object
      x-examples:
        example-1:
          expires_at: '2022-07-11T22:39:55.469Z'
          link_url: https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_bXQj8iSgYwXf432yJcWbKv&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfYlhRajhpU2dZd1hmNDMyeUpjV2JLdiIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmZpbml4LmNvbS9kb2NzIiwiZXhwaXJlZF9zZXNzaW9uX3VybCI6Imh0dHBzOi8vd3d3LmZpbml4LmNvbS8iLCJpc3MiOiJodHRwczovL3d3dy5maW5peC5jb20iLCJyZXR1cm5fdXJsIjoiaHR0cHM6Ly93d3cuZmluaXguY29tL2RvY3MiLCJleHAiOjE2NTc1NzkxOTUsImFwcGxpY2F0aW9uX2lkIjoiQVBnUERRckxENTJUWXZxYXpqSEpKY2hNIiwiaWF0IjoxNjU3NTc3Mzk1LCJtZXJjaGFudF9tYXhfdHJhbnNhY3Rpb25fYW1vdW50IjoxMDAwMDAsInRlcm1zX29mX3NlcnZpY2VfdXJsIjoiaHR0cHM6Ly93d3cuZmluaXguY29tL3Rlcm1zLWFuZC1wb2xpY2llcyJ9.uQvwqhOxSmpX4zMSVn891ClNB_cWHmXhLfyOzRiKRoyn7VAqVOWrO8dJiY-OvN4venPWnPOxM0r3NiIyfgQv6g
      properties:
        expires_at:
          type: string
          description: A UTC timestamp detailing when the onboarding form expires and will no longer be available via `link_url`. To generate a new link to the same form, see [Get an Onboarding Form URL](/guides/onboarding/onboarding-form/#get-an-onboarding-form-url).
        link_url:
          type: string
          description: The URL of the user's Finix Onboarding Form. Users can use the `link_url` to return to the form at any time.
      title: OnboardingFormLink
    Error401Unauthorized:
      type: object
      properties:
        total:
          type: integer
        _embedded:
          type: object
          properties:
            errors:
              type: array
              items:
                type: object
                additionalProperties: true
                properties:
                  code:
                    type: string
                    enum:
                    - UNKNOWN
                  logref:
                    $ref: '#/components/schemas/LogRef'
                  message:
                    type: string
                  _links:
                    type: object
                    additionalProperties: true
                    properties:
                      self:
                        type: object
                        properties:
                          href:
                            type: string
                      source:
                        type: object
                        properties:
                          href:
                            type: string
    CreatedAt:
      type: string
      title: CreatedAt
      format: date-time
      description: Timestamp of when the object was created.
    Tags:
      type: object
      title: tags
      additionalProperties:
        type: string
      description: 'Include up to 50 `key`: **value** pairs to annotate requests with custom metadata.

        - Maximum character length for individual `keys` is 40.

        - Maximum character length for individual **values** is 500.


        (e.g., `order number`: **25**, `item_type`: **produce**, `department`: **sales**, etc.)'
      nullable: true
  requestBodies:
    CreateOnboardingFormRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateOnboardingFormRequest'
          examples:
            Create an Onboarding Form:
              value:
                onboarding_data:
                  entity:
                    title: CEO
                    first_name: John
                    last_name: Smith
                    email: john.smith@finix.com
                    business_name: Finix Flowers
                    business_type: CORPORATION
                    doing_business_as: Finix Flowers
                    phone: '14158885080'
                    business_phone: '14158885080'
                    personal_address:
                      city: Seattle
                      country: USA
                      line1: 123 Boren Ave
                      postal_code: '98040'
                      region: WA
                    business_address:
                      city: Bellevue
                      country: USA
                      line1: 123 Bellevue Way
                      postal_code: '98039'
                      region: WA
                    dob:
                      day: 13
                      month: 4
                      year: 1982
                    incorporation_date:
                      day: 9
                      month: 3
                      year: 2018
                    mcc: '4900'
                    url: https://www.finix.com
                    ownership_type: PRIVATE
                    default_statement_descriptor: DEMOCOMPANY
                    max_transaction_amount: 100000
                    annual_card_volume: 1000000
                    principal_percentage_ownership: 75
                    tax_id: '123456789'
                    business_tax_id: '123456789'
                    has_accepted_credit_cards_previously: false
                  additional_underwriting_data:
                    refund_policy: NO_REFUNDS
                    card_volume_distribution:
                      ecommerce_percentage: 100
                      card_present_percentage: 0
                      mail_order_telephone_order_percentage: 0
                    average_ach_transfer_amount: 200000
                    average_card_transfer_amount: 20000
                    annual_ach_volume: 2000000
                    business_description: CONSUMER
                    volume_distribution_by_business_type:
                      other_volume_percentage: 0
                      person_to_person_volume_percentage: 0
                      business_to_business_volume_percentage: 90
                      business_to_consumer_volume_percentage: 10
                      consumer_to_consumer_volume_percentage: 0
                  associated_entities:
                  - title: CFO
                    first_name: Alex
                    last_name: Smith
                    email: alex.smith@finix.com
                    phone: '14158885080'
                    personal_address:
                      city: Bellevue
                      country: USA
                      line1: 4848 84th St
                      postal_code: '98032'
                      region: WA
                    dob:
                      day: 13
                      month: 4
                      year: 1985
                    principal_percentage_ownership: 25
                    tax_id: '123456789'
                  payment_instruments:
                    name: SARAH BANKER
                    bank_code: '123456789'
                    account_number: '123456789'
                    account_type: CHECKING
                    type: BANK_ACCOUNT
                  max_transaction_amount: 100000
                merchant_processors:
                - processor: LITLE_V1
                onboarding_link_details:
                  return_url: https://www.finixflowers.com/
                  expired_session_url: https://www.finixflowers.com/login
                  terms_of_service_url: https://www.finixflowers.com/ToS
                  fee_details_url: https://www.finixflowers.com/fee_details
                  expiration_in_minutes: 10080
    CreateOnboardingFormLinkRequest:
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/CreateOnboardingFormLinkRequest'
          examples:
            Create an Onboarding Form Link:
              value:
                expiration_in_minutes: 10080
                expired_session_url: https://www.finix.com/
                fee_details_url: https://www.finix.com/docs
                return_url: https://www.finix.com/docs
                terms_of_service_url: https://www.finix.com/terms-and-policies
  responses:
    Error406NotAcceptable:
      description: Not Acceptable
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error406NotAcceptable'
          examples: {}
    Error422InvalidField:
      description: Invalid field
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error422InvalidFieldList'
    OnboardingForm:
      description: A single `onboarding_from` objext.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OnboardingForm'
          examples:
            Onboarding Form:
              value:
                id: obf_cJUfiz97L8de54EwkC3Hiu
                onboarding_data:
                  entity:
                    title: CEO
                    first_name: John
                    last_name: Smith
                    email: john.smith@finix.com
                    business_name: Finix Flowers
                    business_type: CORPORATION
                    doing_business_as: Finix Flowers
                    phone: '14158885080'
                    business_phone: '14158885080'
                    mcc: '4900'
                    url: https://www.finix.com
                    ownership_type: PRIVATE
                    default_statement_descriptor: DEMOCOMPANY
                    max_transaction_amount: 100000
                    annual_card_volume: '1000000'
                    principal_percentage_ownership: '75'
                    tax_id: '*****6789'
                    business_tax_id: '*****6789'
                    has_accepted_credit_cards_previously: false
                    personal_address:
                      line1: 123 Boren Ave
                      city: Seattle
                      region: WA
                      postal_code: '98040'
                      country: USA
                    business_address:
                      line1: 123 Bellevue Way
                      city: Bellevue
                      region: WA
                      postal_code: '98039'
                      country: USA
                    dob:
                      day: 13
                      month: 4
                      year: 1982
                    incorporation_date:
                      day: 9
                      month: 3
                      year: 2018
                  associated_entities:
                  - title: CFO
                    first_name: Alex
                    last_name: Smith
                    email: alex.smith@finix.com
                    phone: '14158885080'
                    personal_address:
                      line1: 4848 84th St
                      city: Bellevue
                      region: WA
                      postal_code: '98032'
                      country: USA
                    dob:
                      day: 13
                      month: 4
                      year: 1985
                    principal_percentage_ownership: 25
                    tax_id: '*****6789'
                  payment_instruments:
                    name: SARAH BANKER
                    bank_code: '123456789'
                    account_number: '*****6789'
                    account_type: CHECKING
                    type: BANK_ACCOUNT
                  additional_underwriting_data:
                    refund_policy: NO_REFUNDS
                    average_ach_transfer_amount: 2000000
                    average_card_transfer_amount: 20000
                    annual_ach_volume: 2000000
                    business_description: CONSUMER
                    volume_distribution_by_business_type:
                      other_volume_percentage: 0
                      person_to_person_volume_percentage: 0
                      business_to_business_volume_percentage: 90
                      business_to_consumer_volume_percentage: 10
                      consumer_to_consumer_volume_percentage: 0
                    card_volume_distribution:
                      ecommerce_percentage: 100
                      card_present_percentage: 0
                      mail_order_telephone_order_percentage: 0
                  max_transaction_amount: 100000
                merchant_processors:
                - processor: LITLE_V1
                onboarding_link_details:
                  return_url: https://www.finixflowers.com/
                  expired_session_url: https://www.finixflowers.com/login
                  fee_details_url: https://www.finixflowers.com/fee_details
                  terms_of_service_url: https://www.finixflowers.com/ToS
                  expiration_in_minutes: 10080
                onboarding_link:
                  expires_at: '2023-04-06T19:16:28.387Z'
                  link_url: https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_cJUfiz97L8de54EwkC3Hiu&applicationId=APgPDQrLD52TYvqazjHJJchM...
                status: IN_PROGRESS
                identity_id: null
                application_id: APgPDQrLD52TYvqazjHJJchM
                created_at: '2023-03-30T19:16:28.377022Z'
                updated_at: '2023-03-30T19:16:28.377022Z'
                tags: {}
    ErrorForbidden403:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error403ForbiddenList'
    ErrorNotFound:
      description: Object does not exist
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error404NotFoundList'
    OnboardingFormLink:
      description: A link for users to return to their `onboarding_form` at any time.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/OnboardingFormLink'
          examples:
            Onboarding Form Link:
              value:
                expires_at: '2022-07-11T22:39:55.469Z'
                link_url: https://sandbox.payments-dashboard.com/merchant-onboarding?formId=obf_bXQj8iSgYwXf432yJcWbKv&applicationId=APgPDQrLD52TYvqazjHJJchM&bearerToken=eyJhbGciOiJIUzUxMiJ9.eyJvbmJvYXJkaW5nX2Zvcm1faWQiOiJvYmZfYlhRajhpU2dZd1hmNDMyeUpjV2JLdiIsImZlZV9kZXRhaWxzX3VybCI6Imh0dHBzOi8vd3d3LmZpbml4LmNvbS9kb2NzIiwiZXhwaXJlZF9zZXNzaW9uX3VybCI6Imh0dHBzOi8vd3d3LmZpbml4LmNvbS8iLCJpc3MiOiJodHRwczovL3d3dy5maW5peC5jb20iLCJyZXR1cm5fdXJsIjoiaHR0cHM6Ly93d3cuZmluaXguY29tL2RvY3MiLCJleHAiOjE2NTc1NzkxOTUsImFwcGxpY2F0aW9uX2lkIjoiQVBnUERRckxENTJUWXZxYXpqSEpKY2hNIiwiaWF0IjoxNjU3NTc3Mzk1LCJtZXJjaGFudF9tYXhfdHJhbnNhY3Rpb25fYW1vdW50IjoxMDAwMDAsInRlcm1zX29mX3NlcnZpY2VfdXJsIjoiaHR0cHM6Ly93d3cuZmluaXguY29tL3Rlcm1zLWFuZC1wb2xpY2llcyJ9.uQvwqhOxSmpX4zMSVn891ClNB_cWHmXhLfyOzRiKRoyn7VAqVOWrO8dJiY-OvN4venPWnPOxM0r3NiIyfgQv6g
    ErrorUnauthorized:
      description: Authentication information is missing or invalid
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error401Unauthorized'
  securitySchemes:
    BasicAuth:
      type: http
      scheme: basic
      description: ''
x-stoplight:
  id: c6861590dda46
x-ignoredHeaderParameters:
- Accept
- finix-apiuser-role
- date
- x-request-id
x-tagGroups:
- name: MAIN RESOURCES
  tags:
  - Authorizations
  - Compliance Forms
  - Devices
  - Disputes
  - Fee Profiles
  - Files
  - Identities
  - Instrument Updates
  - Merchants
  - Onboarding Forms
  - Payment Instruments
  - Settlements
  - Split Transfers
  - Transfers
  - Users
  - Webhooks
- name: CORE-PAYFAC RESOURCES
  tags:
  - Application Profiles
  - Applications
  - Balance Transfers
  - Merchant Profiles
  - Payout Profiles
  - Verifications
- name: SUBSCRIPTION BILLING
  tags:
  - Subscription Schedules
  - Subscription Amounts
  - Subscription Enrollments
x-exclude-tags-from-libraries:
- Applications
- Application Profiles
- Fees
- Payment Instruments P2C
- Processors
- Review Queue
- Subscription Schedules
- Subscription Amounts
- Subscription Enrollments
- Users