Finix Payments Onboarding Forms API

openapi: 3.2.0
info:
  title: Finix 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:
    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'
    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
    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: ''
    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
    UpdatedAt:
      type: string
      title: UpdatedAt
      format: date-time
      description: Timestamp of when the object was last updated.
    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
    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'
    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
    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: ''
    LogRef:
      title: LogRef
      type: object
      properties:
        logref:
          type: string
    Tags:
      type:
      - object
      - 'null'
      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.)'
    CreatedAt:
      type: string
      title: CreatedAt
      format: date-time
      description: Timestamp of when the object was created.
    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
              - 'null'
              description: The distribution of the merchant's credit card volume The sum of `card_volume_distribution` must be 100.
              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
              - 'null'
              description: Merchant's distribution of credit card volume by business type. Sum of `volume_distribution_by_business_type` must be 100.
              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
                - 'null'
                description: The primary address for the legal entity.
                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
                - 'null'
                minLength: 1
                description: Abbreviated names of the business. If there are no abbreviated name, leave this field blank.
              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
                - 'null'
                description: The date the company was founded and registered.
                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
                - 'null'
                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.'
              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
              - 'null'
              description: Assigned amexMid value. If a value is passed, it must be 10 or 11 digits.
            annual_card_volume:
              type:
              - integer
              - 'null'
              description: The annual credit card sales (in cents) expected to be processed by this seller (max 19 characters).
            business_address:
              type:
              - object
              - 'null'
              description: The primary address for the legal entity.
              properties:
                line1:
                  type:
                  - string
                  - 'null'
                  minLength: 1
                  description: First line of the address (max 35 characters).
                line2:
                  type:
                  - string
                  - 'null'
                  minLength: 1
                  description: Second line of the address (max 35 characters).
                city:
                  type:
                  - string
                  - 'null'
                  minLength: 1
                  description: City (max 20 characters).
                region:
                  type:
                  - string
                  - 'null'
                  minLength: 1
                  description: 2-letter state code.
                postal_code:
                  type:
                  - string
                  - 'null'
                  minLength: 1
                  description: Zip or Postal code (max 7 characters).
                country:
                  type:
                  - string
                  - 'null'
                  minLength: 1
                  description: 3-Letter Country code (e.g. USA).
            business_name:
              type:
              - string
              - 'null'
              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.
            business_phone:
              type:
              - string
              - 'null'
              minLength: 1
              description: Customer service phone number where the seller can be reached (max 10 characters).
            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
              - 'null'
            default_statement_descriptor:
              type:
              - string
              - 'null'
              minLength: 1
              description: The description of the seller that appears on the buyer's bank or card statement.
            discover_mid:
              description: Assigned discoverMid value.
              type:
              - integer
              - 'null'
            dob:
              type:
              - object
              - 'null'
              description: The control owner's date of birth.
              properties:
                day:
                  type: integer
                  description: Day of birth (between 1 and 31).
                  minimum: 1
                month:
                  type: integer
                  description: Month of

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/finix-payments/refs/heads/main/openapi/finix-payments-onboarding-forms-api-openapi.yml