Onboarding and Verification Process

Learn about Finix's onboarding process.

Whether you build your own onboarding experience or use Finix's Onboarding Forms solution, the following steps below apply:

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

When using Finix's Onboarding Form, these resources get created on your behalf. During onboarding, your seller or service provider's information is verified by Finix's underwriting team.

Onboarding Webhooks

Accepting and handling webhooks is recommended since the verification process is asynchronous. Several webhook events are sent during the onboarding process. Follow our webhook guide for details on how to setup webhooks.

Onboarding States

After you created the merchant, either from the API Onboarding or Finix's 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:

State	Description
PROVISIONING	The request is pending and being processed by Finix's system.
APPROVED	The `Merchant` was successfully onboarded. Your seller is ready to process payments.
REJECTED	The `Merchant` was rejected and you need to handle the unsuccessful verification.

Approved Merchants

When a Merchant is APPROVED, you receive a webhook event with entity = merchant and type = underwritten.

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

The following details the different onboarding states, and how to handling unsuccessful verifications.

onboarding states flow

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" : "4900",
                "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"
            }
        ]
    }
}

Rejected Merchants

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",
  "created_at" : "2021-11-14T19:20:29.15Z",
  "updated_at" : "2021-11-14T19:20:29.48Z",
  "application" : "APcVnXxyWotD6TGRWV2bRWuD",
  "card_cvv_required" : false,
  "card_expiration_date_required" : true,
  "creating_transfer_from_report_enabled" : false,
  "fee_ready_to_settle_upon" : "RECONCILIATION",
  "gross_settlement_enabled" : false,
  "identity" : "IDgXNAaoy5d4TLkp5ze6gScA",
  "level_two_level_three_data_enabled" : false,
  "mcc" : "4900",
  "merchant_name" : "Finix Flowers",
  "merchant_profile" : "MP9e916zYUTTqHUDe4F9ZQvp",
  "mid" : "FNXqtgiZAvNPz44hT67Ai632W",
  "onboarding_state" : "REJECTED"
  "processing_enabled" : true,
  "processor" : "DUMMY_V1",
  "ready_to_settle_upon" : null,
  "settlement_enabled" : true,
  "settlement_funding_identifier" : "UNSET",
  "surcharges_enabled": false,
  "tags" : {
    "key_2" : "value_2"
  },
  "verification" : "VIeZ3gBoRemaDimjp6qS58An",
}

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/VIpdSnQwTNeWgMHXvFDCPVsx \
-H "Content-Type: application/json" \
-H 'Finix-Version: 2022-02-01' \
-u "USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041"

Copy

Copied

{
  "id": "VIvyMuSk9EdyVUrCw2JcXq4r",
  "created_at": "2023-09-12T16:08:17.03Z",
  "updated_at": "2023-09-12T16:08:17.10Z",
  "application": "AP7sqs8G9eTwcLPpjEHLgfUq",
  "identity": null,
  "merchant": "MUno35MtzSMr61mUvY7qCayR",
  "merchant_identity": "IDbM99DS8MaYXyqynqB7z1mR",
  "messages": [
    "ID_VERIFICATION_NEEDED",
    "ID_VERIFICATION_FAILED"
  ],
  "payment_instrument": null,
  "payment_instrument_verification_details": {
    "push_to_card_domestic": null,
    "push_to_card_cross_border": null,
    "card_type": null,
    "billing_currency": null,
    "issuer_country": null
  },
  "processor": "LITLE_V1",
  "raw": [
    {
      "outcome_code": "ID_VERIFICATION_NEEDED",
      "description": "ID Verification needed on owner(s).",
      "remediation_item": "Submit a valid Driver's License, State ID, or Passport. To submit these file(s), use our File Upload feature. "
    },
    {
      "outcome_code": "ID_VERIFICATION_FAILED",
      "description": "ID Verification was unsuccessful.",
      "remediation_item": "Ensure ID Verification matches the owner's full name, is readable, and is not expired. Resubmit ID Verification to the link provided by Customer Service for the Merchant Resource (MUxx)."
    }
  ],
  "state": "FAILED",
  "tags": {},
  "trace_id": "FNXboZb9r4P8TRKXluF2udGEv",
  "type": "MERCHANT",
  "_links": {
    "self": {
      "href": "https://finix.live-payments-api.com/verifications/VIvyMuSk9EdyVUrCw2JcXq4r"
    },
    "application": {
      "href": "https://finix.live-payments-api.com/applications/AP7sqs8G9eTwcLPpjEHLgfUq"
    },
    "merchant": {
      "href": "https://finix.live-payments-api.com/merchants/MUno35MtzSMr61mUvY7qCayR"
    }
  }
}

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 update 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.

Reverifying 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/json" \
    -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" : "VI4zELwvT6beu2bJpwG24zLF",
  "created_at" : "2022-10-10T05:06:04.88Z",
  "updated_at" : "2022-10-10T05:06:04.93Z",
  "application" : "APgPDQrLD52TYvqazjHJJchM",
  "identity" : null,
  "merchant" : "MUucec6fHeaWo3VHYoSkUySM",
  "merchant_identity" : "IDpYDM7J9n57q849o9E9yNrG",
  "messages" : [ ],
  "payment_instrument" : null,
  "processor" : "DUMMY_V1",
  "raw" : null,
  "state" : "PENDING",
  "tags" : { },
  "trace_id" : "002ef04f-9227-4179-8232-3dc2df8fa8a0",
  "_links" : {
    "self" : {
      "href" : "https://finix.sandbox-payments-api.com/verifications/VI4zELwvT6beu2bJpwG24zLF"
    },
    "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 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/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u  USpbnPYf1MMaYYtBqNsNzD6T:fb5493a2-21c4-46b8-be48-65e987c70a53 \
    -d '
    {
        "entity": {
            "dob": {
                "day": 1, 
                "month": 1, 
                "year": 2013
            }, 
            "email": "john.smith@company1.com", 
            "first_name": "John", 
            "last_name": "Smith", 
            "personal_address": {
                "city": "San Francisco", 
                "country": "USA",
                "line1": "123 Main Street", 
                "postal_code": "90650", 
                "region": "CA"
            }, 
            "phone": "1234567890", 
            "principal_percentage_ownership": 25, 
            "tax_id": "123456789",
            "title": "Founder"
        }
    }'

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

Copy

Copied

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

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 Finix's 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.