Onboarding Process

During onboarding, your seller or service provider's information has to be verified (commonly called Know Your Customer or Know Your Business guidelines) and underwritten. This is a key initial experience for your seller and it is important you build out the happy and unhappy flows.

Since onboarding is an asynchronous process, a successful onboarding integration requires:

Key Onboarding Steps

Whether you build your own onboarding experience or use Finix's Hosted Onboarding solution, you need to understand the key steps and resources used for the onboarding process:

  1. Collect information and consent to the Finix Terms of Service. This is represented in our system as an Identity .
  2. Collect information about all owners who have 25% or more ownership. These are represented in our system as Associated Identities.
  3. Add the bank account for the business, this is a payment_instrument .
  4. Create a Merchant account and have Finix verify the Merchant . A Merchant resource and each verification attempt is a verification .
  5. If necessary, resolve rejected verifications and reattempt verification.

When using our Hosted Onboarding Form, these various resources get created on your behalf.

Here is a diagram that visualizes this flow.

onboarding flow

You'll also need to know the processor your account is using. Your Finix point of contact will inform you of which processor you should use. You can also email Finix Support if you have any questions about what processor to use.

Onboarding Webhooks

Accepting and handling webhooks is essential since the verification process can take some time. Follow our webhook guide on creating webhooks.

We'll send webhooks during the onboarding process. The events we send and when are communicated throughout our guides, but we also provide a list of webhook events.

Once you start receiving webhooks, you need to build logic based on the onboarding states.

Onboarding States and Flow Diagram

After you created the merchant, either from the manual onboarding or our Hosted Onboarding Form, the Merchant will be in a PROVISIONING state until approved or rejected.

When the merchant has been updated, we send a webhook event of entity = merchant and type = updated. Use the onboarding_state to understand the result and next steps:

  • PROVISIONING: The request is still pending.
  • APPROVED: The merchant was successfully onboarded.
  • REJECTED: The merchant was rejected and you need to handle the unsuccessful verification .

This diagram shows the onboarding states, and more detail on how to handling unsuccessful verifications is managed.

onboarding states flow

attention

A webhook event of entity = merchant and type = underwritten indicates the Merchant was successfully onboarded and can start processing payments. This correlates to the APPROVED onboarding_state.

Approved Merchant

Verification and underwriting is an asynchronous process and will take several minutes to complete. Once a Merchant has successfully be provisioned, you will receive a webhook event with entity of merchant and the type of underwritten.

An approved merchant means your seller is ready to process payments.

Merchant Underwritten Webhook Event
Copy
Copied
{
    "type":"underwritten",
    "entity":"merchant",
    "occured_at":"2021-11-14T19:20:29.48Z",
    "_embedded":{
        "merchants":[
            {
                "id" : "MUoBGzwPdFxb397BKM3bHUvf",
                "application" : "APcVnXxyWotD6TGRWV2bRWuD",
                "identity" : "IDgXNAaoy5d4TLkp5ze6gScA",
                "verification" : "VIeZ3gBoRemaDimjp6qS58An",
                "merchant_profile" : "MP9e916zYUTTqHUDe4F9ZQvp",
                "processor" : "DUMMY_V1",
                "processing_enabled" : true,
                "settlement_enabled" : true,
                "gross_settlement_enabled" : false,
                "creating_transfer_from_report_enabled" : false,
                "card_expiration_date_required" : true,
                "card_cvv_required" : false,
                "tags" : {
                    "key_2" : "value_2"
                },
                "mcc" : "0742",
                "mid" : "FNXqtgiZAvNPz44hT67Ai632W",
                "merchant_name" : "Finix Flowers",
                "settlement_funding_identifier" : "UNSET",
                "ready_to_settle_upon" : null,
                "fee_ready_to_settle_upon" : "RECONCILIATION",
                "level_two_level_three_data_enabled" : false,
                "created_at" : "2021-11-14T19:20:29.15Z",
                "updated_at" : "2021-11-14T19:20:29.48Z",
                "onboarding_state" : "APPROVED"
            }
        ]
    }
}

Handling Unsuccessful Verifications

There are some cases where a seller does not pass verification and the onboarding_state of the Merchant gets set as REJECTED. Usually, a REJECTED state means Finix requires more information to verify the user's identity and enable processing.

Here is an example of a rejected Merchant:

Copy
Copied
{
  "id" : "MUoBGzwPdFxb397BKM3bHUvf",
  "application" : "APcVnXxyWotD6TGRWV2bRWuD",
  "identity" : "IDgXNAaoy5d4TLkp5ze6gScA",
  "verification" : "VIeZ3gBoRemaDimjp6qS58An",
  "merchant_profile" : "MP9e916zYUTTqHUDe4F9ZQvp",
  "processor" : "DUMMY_V1",
  "processing_enabled" : true,
  "settlement_enabled" : true,
  "gross_settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "card_expiration_date_required" : true,
  "card_cvv_required" : false,
  "tags" : {
    "key_2" : "value_2"
  },
  "mcc" : "0742",
  "mid" : "FNXqtgiZAvNPz44hT67Ai632W",
  "merchant_name" : "Finix Flowers",
  "settlement_funding_identifier" : "UNSET",
  "ready_to_settle_upon" : null,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "level_two_level_three_data_enabled" : false,
  "created_at" : "2021-11-14T19:20:29.15Z",
  "updated_at" : "2021-11-14T19:20:29.48Z",
  "onboarding_state" : "REJECTED"
}

To understand what the rejection is, you need to look up the verification that was created for the merchant.

shelljson
Copy
Copied
curl https://finix.sandbox-payments-api.com/verifications/VIeZ3gBoRemaDimjp6qS58An \
-H "Content-Type: application/vnd.json+api" \
-H 'Finix-Version:2022-02-01' \
-u "USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e " \
-d '{}'
Copy
Copied
{
  "id" : "VIeZ3gBoRemaDimjp6qS58An",
  "application" : "APcVnXxyWotD6TGRWV2bRWuD",
  "tags" : {
    "underwriting_tag" : "underwriting_6rlNN"
  },
  "messages" : [ "INVALID_OWNER_DATA" ],
  "raw" : [ {
    "outcome_code" : "INVALID_OWNER_DATA",
    "description" : "The owner(s) information could not be verified.",
    "remediation" : "Verify and resubmit the information by updating the Identity and submitting a new Merchant Verification."
  } ],
  "processor" : "DUMMY_V1",
  "state" : "FAILED",
  "created_at" : "2021-11-14T19:20:29.48Z",
  "updated_at" : "2021-11-14T19:20:29.48Z",
  "trace_id" : "FNX4rcQDMx8mRF9MXp7fZDLuA",
  "payment_instrument" : null,
  "merchant" : "MUoBGzwPdFxb397BKM3bHUvf",
  "merchant_identity": "IDgXNAaoy5d4TLkp5ze6gScA", 
  "identity" : null,
  "_links" : {}
}

The raw field will contain an array of the rejection response and suggestions to get the Merchant approved. Though we recommend building your system to handle every reject code.

attention

We may add new reject codes over time to help improve the onboarding process

Most reject code's remediation is to updated the information on the Identity. Once you've resolved the rejection issues, reattempt verifying the Merchant. Some reject codes are hard rejections which means the Identity can not be onboarded to Finix.

Reverify a Merchant

There are two main reasons to reverify a Merchant:

  • The Merchant initially failed onboarding. You would need to update the Identity and attempt boarding again (also called reattempting Merchant provisioning ).
  • Your user needs to update their information, which requires reverifying their new updated information.

If more information is requested, update the Identityand then resubmit the information to Finix. To resubmit the information to Finix, create a new Verification on the Merchant:

Copy
Copied
curl https://finix.sandbox-payments-api.com/merchants/MUucec6fHeaWo3VHYoSkUySM/verifications \
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '{}'

A successful response returns a 200 and a PENDING verification resource.

Copy
Copied
{
  "id" : "VImYZaUoPXkVr3DKWNNwV4ch",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "tags" : { },
  "messages" : [ ],
  "raw" : null,
  "processor" : "DUMMY_V1",
  "state" : "PENDING",
  "created_at" : "2022-01-27T07:42:47.97Z",
  "updated_at" : "2022-01-27T07:42:48.04Z",
  "trace_id" : "4a0571f3-6a5b-4000-92e9-b90336c6d6d0",
  "payment_instrument" : null,
  "merchant" : "MUucec6fHeaWo3VHYoSkUySM",
  "merchant_identity": "IDTiyTks118XhKcxSLsArzu",
  "identity" : null,
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VImYZaUoPXkVr3DKWNNwV4ch"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
    },
    "merchant" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUucec6fHeaWo3VHYoSkUySM"
    }
  }
}

The Merchant resource will update back to a PROVISIONING stage and you will be notified via webhook of the Merchant's onboarding status.

Associated Identities

You must also create an Associated Identity for any owners of the the business that has a stake that's 25% or greater. If there are no other owners with at least 25% ownership, then you may skip this step.

To add an associated identity, create an associated_identity on the merchant Identity.

Copy
Copied
curl https://finix.sandbox-payments-api.com/identities/IDgXNAaoy5d4TLkp5ze6gScA/associated_identities \
    -H "Content-Type: application/vnd.json+api" \
    -u  USpbnPYf1MMaYYtBqNsNzD6T:fb5493a2-21c4-46b8-be48-65e987c70a53 \
    -d '
    {
        "entity": {
            "first_name": "John", 
            "last_name": "Smith", 
            "title": "Founder", 
            "dob": {
                "month": 1, 
                "day": 1, 
                "year": 2013
            }, 
            "principal_percentage_ownership": 25, 
            "phone": "1234567890", 
            "personal_address": {
                "city": "San Francisco", 
                "region": "CA", 
                "postal_code": "90650", 
                "line1": "123 Main Street", 
                "country": "USA"
            }, 
            "email": "john.smith@company1.com", 
            "tax_id": "123456789"
        }
    }'

A successful request will return 201 and a new Identity resource.

Copy
Copied
{
  "id" : "IDcCTpaLiiPu9kZ6kejwwVnW",
  "application" : "APcVnXxyWotD6TGRWV2bRWuD",
  "entity" : {
    "title" : "Founder",
    "first_name" : "John",
    "last_name" : "Smith",
    "email" : "john.smith@company1.com",
    "business_name" : null,
    "business_type" : null,
    "doing_business_as" : null,
    "phone" : "1234567890",
    "business_phone" : null,
    "personal_address" : {
      "line1" : "123 Main Street",
      "line2" : null,
      "city" : "San Francisco",
      "region" : "CA",
      "postal_code" : "90650",
      "country" : "USA"
    },
    "business_address" : null,
    "mcc" : null,
    "dob" : {
      "day" : 1,
      "month" : 1,
      "year" : 2013
    },
    "max_transaction_amount" : 0,
    "amex_mid" : null,
    "discover_mid" : null,
    "url" : null,
    "annual_card_volume" : 0,
    "has_accepted_credit_cards_previously" : false,
    "incorporation_date" : null,
    "principal_percentage_ownership" : 25,
    "short_business_name" : null,
    "ownership_type" : null,
    "tax_authority" : null,
    "tax_id_provided" : true,
    "business_tax_id_provided" : false,
    "default_statement_descriptor" : null
  },
  "tags" : { },
  "created_at" : "2022-08-30T00:20:42.78Z",
  "updated_at" : "2022-08-30T00:20:42.78Z",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcCTpaLiiPu9kZ6kejwwVnW"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcCTpaLiiPu9kZ6kejwwVnW/verifications"
    },
    "merchants" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcCTpaLiiPu9kZ6kejwwVnW/merchants"
    },
    "settlements" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcCTpaLiiPu9kZ6kejwwVnW/settlements"
    },
    "authorizations" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcCTpaLiiPu9kZ6kejwwVnW/authorizations"
    },
    "transfers" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcCTpaLiiPu9kZ6kejwwVnW/transfers"
    },
    "payment_instruments" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcCTpaLiiPu9kZ6kejwwVnW/payment_instruments"
    },
    "associated_identities" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcCTpaLiiPu9kZ6kejwwVnW/associated_identities"
    },
    "disputes" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDcCTpaLiiPu9kZ6kejwwVnW/disputes"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APcVnXxyWotD6TGRWV2bRWuD"
    }
  }
}

Initial Settings and Profiles

Finix allows you to define a root set of settings in an Application Profile that are copied down to each Merchant that gets created.

When a Merchant gets created, the profiles on the Application Profile is copied into a new merchant profile that is then associated to the newly created Merchant.

The fee profile contains the fee settings for the merchant.

You can't directly edit the root Application Profile or the Merchant Profile. Reach out to Finix Support to get your Application Profile set up correctly or if you want to make specific customizations for a single Merchant. The fees you collect from sellers are controlled by the fee profile on Merchants.

Communicating Fees

Regulations require you to specify the payment processing fees you are going to charge the seller clearly and prominently on the final application screen.

When using our Hosted Onboarding Form, you need to specify a URL that points to a public page with the fee information.

When Onboarding with the API, it is up to you how to show the fees.

Additionally, you need to communicate any fee changes to your sellers with prior notice.

Card Present Merchant Provisioning

When provisioning a card present Merchant, you need to provide the appropriate processor and gateway:

Copy
Copied
curl https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR/merchants \
        -H "Content-Type: application/vnd.json+api" \
        -H 'Finix-Version:2022-02-01' \
        -u  USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
        -d '
        {
            "processor": "VANTIV_V1",
            "gateway": "TRIPOS_CLOUD_V1"
        }'

The response will be a PROVISIONING Merchant.

Copy
Copied
{
  "id" : "MUu56ZGx3Xb6U9gAqKfgNisd",
  "application" : "APeUbTUjvYb1CdPXvNcwW1wP",
  "identity" : "IDsbTBawhnLBAVeinRb84vFR",
  "verification" : "VIhjGSJCnvXLzFQZUsUaeHxb",
  "merchant_profile" : "MPgDcdhXsdcJ9MVeJrZRNp79",
  "processor" : "VANTIV_V1",
  "processing_enabled" : false,
  "settlement_enabled" : false,
  "creating_transfer_from_report_enabled" : false,
  "tags" : { },
  "created_at" : "2019-03-01T00:49:02.47Z",
  "updated_at" : "2019-03-01T00:49:02.47Z",
  "onboarding_state" : "PROVISIONING",
  "processor_details" : { },
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd"
    },
    "identity" : {
      "href" : "https://finix.sandbox-payments-api.com/identities/IDsbTBawhnLBAVeinRb84vFR"
    },
    "verifications" : {
      "href" : "https://finix.sandbox-payments-api.com/merchants/MUu56ZGx3Xb6U9gAqKfgNisd/verifications"
    },
    "merchant_profile" : {
      "href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPgDcdhXsdcJ9MVeJrZRNp79"
    },
    "application" : {
      "href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
    },
    "verification" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VIhjGSJCnvXLzFQZUsUaeHxb"
    }
  }
}