Onboarding

To begin processing payments, your users need to go through the onboarding process. Onboarding includes collecting information about your users, ensuring users agree to the Finix Terms of Service, and successfully verifying them.

The onboarding process is as follows:

  1. Collect information and consent to the Finix Terms of Service from your user.
  2. Create a Merchant Identity.
  3. Create Associated Identities on the Merchant Identity .
  4. Add a bank account.
  5. Verify the Merchant Identity .

Check out our react.js example for a complete example of how to create an onboarding flow.

Step 1: Collect information and consent from your user

To enable processing for your user, you need to:

  • Collect the identifying information of your user, this includes information about the business and associated peoples.
  • Obtain acceptance of the Finix Terms of Service
  • Communicate payment processing fees

Once you've completed these steps, you will create a Merchant Identity with your user's information.

Identifying information

Identifying information is collected to verify the identities of the user's business entity, the Control Person (The person authorized to sign up the business), and any addiitonal owners with at least 25% ownership in the business.

This information you need to collect includes data such as names, addresses, tax identification numbers, and expected processing volumes.

For a full list of applicable fields, please visit the Getting Started Guide.

Informing users that their identity will be verified

You must inform your users that they are applying for payment processing services and that their identity will be verified. You must add the following text at the beginning of the user application:

The information you provide will be used to verify your identity. Additional information may be requested.

Finix Terms of Service

You must have each user accept the Finix Terms of Service.

Showing the Finix Terms of Service

You must present your users a link to the Finix Terms of Service and they must explicitly consent to it prior to submitting the Merchant Identity to Finix.

Prior to submitting an Identity to Finix, you must present the following text to users:

By continuing, you agree to our Terms of Service and the Finix Terms of Service.

A link to both Finix and your platform’s terms of service needs to be included in this text.

You represent to Finix that you've received your user's consent by providing the following fields to Finix when creating an Identity:

Field Type Description
merchant_agreement_accepted boolean, required Sets whether this merchant has accepted the terms and conditions of the Finix Terms of Service
merchant_agreement_ip_address string, required IP address of the merchant when this merchant accepted the Finix Terms of Service (e.g., 42.1.1.113 )
merchant_agreement_timestamp string, required Timestamp of the merchant when this merchant accepted to the Finix Terms of Service (e.g., 2021-04-28T16:42:55Z)
merchant_agreement_user_agent string, required The user agent of the browser when this merchant accepted the Finix Terms of Service (e.g., Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6))

Communicating Payment Processing Fees

You must present the payment processing fees clearly and prominently on the final application screen. Additionally, you need to communicate fee changes to your users with prior notice.

Collecting Bank Account Information

You must explicitly communicate to users that bank accounts submitted for a merchant application are only to be used for business purposes..

The following text must be used on the bank account information collection page:

You agree to use this account for legitimate business purposes and not for personal, family, or household purposes.

Step 2: Create a Merchant Identity

To provide the information collected in the previous step, create an Identity.

The Identity is the container for all the identifying information and is the root representation of your user and their business. It is used to associate other resources for your user as shown in the following steps.

When you create an Identity, you need to provide information about the primary controlling owner, called a Control Person, which includes their name, date of birth, personal address, and social security number.

When onboarding sole proprietorships, provide the person's information on the identity itself, you do not need to create a beneficial owner. For all other business_types, you must collect beneficial owners.

Copy
Copied
curl https://finix.sandbox-payments-api.com/identities \
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
    {
        "additional_underwriting_data": {
            "merchant_agreement_accepted": true,
            "merchant_agreement_ip_address": "42.1.1.113",
            "volume_distribution_by_business_type": {
                "other_volume_percentage": 0,
                "consumer_to_consumer_volume_percentage": 0,
                "business_to_consumer_volume_percentage": 0,
                "business_to_business_volume_percentage": 100,
                "person_to_person_volume_percentage": 0
            },
            "average_ach_transfer_amount": 200000,
            "annual_ach_volume": 200000,
            "credit_check_user_agent": "Mozilla 5.0(Macintosh; IntelMac OS X 10 _14_6)",
            "refund_policy": "MERCHANDISE_EXCHANGE_ONLY",
            "credit_check_timestamp": "2021-04-28T16:42:55Z",
            "credit_check_allowed": true,
            "merchant_agreement_timestamp": "2021-04-28T16:42:55Z",
            "business_description": "SB3 vegan cafe",
            "average_card_transfer_amount": 200000,
            "credit_check_ip_address": "42.1.1.113",
            "merchant_agreement_user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_6)",
            "card_volume_distribution": {
                "card_present_percentage": 30,
                "mail_order_telephone_order_percentage": 10,
                "ecommerce_percentage": 60
            }
        },
        "tags": {
            "Studio Rating": "4.7"
        },
        "entity": {
            "last_name": "Sunkhronos",
            "max_transaction_amount": 12000000,
            "has_accepted_credit_cards_previously": true,
            "default_statement_descriptor": "Petes Coffee",
            "personal_address": {
                "city": "San Mateo",
                "country": "USA",
                "region": "CA",
                "line2": "Apartment 7",
                "line1": "741 Douglass St",
                "postal_code": "94114"
            },
            "incorporation_date": {
                "year": 1978,
                "day": 27,
                "month": 6
            },
            "business_address": {
                "city": "San Mateo",
                "country": "USA",
                "region": "CA",
                "line2": "Apartment 8",
                "line1": "741 Douglass St",
                "postal_code": "94114"
            },
            "ownership_type": "PRIVATE",
            "first_name": "dwayne",
            "title": "CEO",
            "business_tax_id": "123456789",
            "doing_business_as": "Petes Coffee",
            "principal_percentage_ownership": 50,
            "email": "user@example.org",
            "mcc": "0742",
            "phone": "1234567890",
            "business_name": "Petes Coffee",
            "tax_id": "123456789",
            "business_type": "INDIVIDUAL_SOLE_PROPRIETORSHIP",
            "business_phone": "+1 (408) 756-4497",
            "dob": {
                "year": 1978,
                "day": 27,
                "month": 6
            },
            "url": "www.PetesCoffee.com",
            "annual_card_volume": 12000000
        }
    }'

Step 3: Add Associated Identities

For owners with 25% or more ownership, you need to add Associated Identities. If there are no owners with at least 25% ownership, then you may skip this step.

To provide business owner information, 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" \
    -H 'Finix-Version:2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -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"
        }
    }'

Step 4: Add a bank account

To create bank account details, create a payment_instrument, providing the Identity Id created in the previous step:

Note: Certain consumer banks will not accept deposits from Finix. In the event that a bank does not accept deposits, we will request you to create a new payment_instrument.

The bank account will be verified in the next step (Verify the User).

Copy
Copied
curl https://finix.sandbox-payments-api.com/payment_instruments \
    -H "Content-Type: application/vnd.json+api" \
    -H 'Finix-Version:2022-02-01' \
    -u  USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
    -d '
    {
        "account_type": "SAVINGS",
        "name": "Alice",
        "tags": {
            "Bank Account": "Company Account"
        },
        "country": "USA",
        "bank_code": "123123123",
        "account_number": "123123123",
        "type": "BANK_ACCOUNT",
        "identity": "IDgXNAaoy5d4TLkp5ze6gScA"
    }'

Step 5: Verify the User

Once all the information has been collected and submitted to Finix, you need to finish onboarding by successfully verifying (also known as provisioning) the user. To provision the user, create a Merchant. You will use the Merchant, to create payments and reconcile settlements and payouts. For more information, see Provision Merchant Account.

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

Creating a Merchant Resource

To verify a user, create a Merchant on the identity you created in Step 2.

The verification process may take some time and the Merchant will be in a PROVISIONING state until approved or rejected.

Once Finix reviews the user, it will switch to either an APPROVED or REJECTED state. A webhook is sent with a type of underwritten and the entity of the Merchant.

A successful verification shows a successful Merchant state and your user is ready to start processing payments.

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" : "Petes Coffee",
  "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" : "PROVISIONING"
}
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" : "Petes Coffee",
  "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"
}

To understand why a user was declined, please see Finix's Reject Codes for more information.

The Merchant is the entity used for processing and managing payments. Payments, refunds, and settlements are performed against a user.

Handling Unsuccessful Verifications

There are some cases where Finix will need more information to verify the user's identity and enable processing.

An unsuccessful verification will place the Merchant with a REJECTED state.

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" : "Petes Coffee",
  "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"
}

Submitting another Verification after updating the Merchant Identity

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

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

Next Steps

With an approved user, your user can process payments using the Merchant Resource. Refer to the Getting Started Guide to learn how to process a Sale using an approved Merchant.

Re-Verifying Already Approved Merchants

If the information of a merchant changes, you need to update the info saved for the merchant in Finix (e.g. change in address, name, ownership, etc.). To update a merchant in Finix:

  1. Update the merchant's Identity .
    • Update the information saved in an Identity resource with a PUT call on /identities and any associated identities. For more info, see Update an Identity .
  2. Submit a new Merchant Verification Request.

Once the provision request is submitted, we re-verify the information saved with the new information provided.

Updating Tax ID Approved Merchants

To update the tax ID information saved for an already approved merchant, submit a new merchant application to Finix. This includes creating a new identity for the merchant and submitting another provision request.

For detailed steps, see Getting Started.