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:
- Understanding the key onboarding steps .
- Receiving onboarding webhooks .
- Handling onboarding states .
-
Resubmitting
Merchant
for verification.
Key Onboarding Steps
Whether you build your own onboarding experience or use Finix's Onboarding Forms solution, you need to understand the key steps and resources used for the onboarding process:
-
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 the bank account for the business, this is a
Payment Instrument
. -
Create a
Merchant
account and have Finix verify theMerchant
. AMerchant
resource and each verification attempt is aVerification
. - If necessary, resolve rejected verifications and reattempt verification.
When using Finix's Onboarding Form, these various resources get created on your behalf.
Here is a diagram that visualizes this 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 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:
- 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.
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
{
"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
:
{
"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" : "0742",
"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",
"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.
curl https://finix.sandbox-payments-api.com/verifications/VIpdSnQwTNeWgMHXvFDCPVsx \
-H "Content-Type: application/vnd.json+api" \
-H 'Finix-Version:2022-02-01' \
-u "USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041"
{
"id" : "VIpdSnQwTNeWgMHXvFDCPVsx",
"created_at" : "2020-04-26T22:30:41.50Z",
"updated_at" : "2020-04-26T22:31:15.23Z",
"application" : "APkBUdiWzBjUAkfnbkirXs6d",
"identity" : null,
"merchant" : "MUeLemkwC6WSaaZLUUB1Y7mr",
"merchant_identity" : null,
"messages" : [ "Error(errorCode=null, errorMessage=Original response had no body. Please check Vantiv credentials or health status of Vantiv service, target=null)" ],
"payment_instrument" : null,
"processor" : "VANTIV_V1",
"raw" : "MerchantResponse(correlationId=null, httpStatusCode=500, httpStatusMessage=Original response had no body, id=null, mid=null, acceptedCards=null, expressSubAccount=null, errors=[Error(errorCode=null, errorMessage=Original response had no body. Please check Vantiv credentials or health status of Vantiv service, target=null)])",
"state" : "FAILED",
"tags" : { },
"trace_id" : "FNX4YG8ut4zJQekpQGZbtZL2a",
"_links" : {
"self" : {
"href" : "https://finix.sandbox-payments-api.com/verifications/VIpdSnQwTNeWgMHXvFDCPVsx"
},
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APkBUdiWzBjUAkfnbkirXs6d"
},
"merchant" : {
"href" : "https://finix.sandbox-payments-api.com/merchants/MUeLemkwC6WSaaZLUUB1Y7mr"
}
}
}
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 theIdentity
and attempt boarding again (also called reattemptingMerchant
provisioning ). - Your user needs to update their information, which requires reverifying their new updated information.
If more information is requested, update the Identity
and then resubmit the information to Finix. To resubmit the information to Finix, create a new Verification
on the Merchant
:
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.
{
"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 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
.
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 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.
{
"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"
}
}
}
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 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.
Card Present Merchant Provisioning
When provisioning a card present Merchant
, you need to provide the appropriate rocessor
and gateway
:
curl https://finix.sandbox-payments-api.com/identities/IDuWtgdP9VERb4FiLeYatWy/merchants \
-H "Content-Type: application/vnd.json+api" \
-H 'Finix-Version:2022-02-01' \
-u USjHFGYvecE4LBitYG8KDE2g:b698f403-d9b7-4157-82d8-162cea8c8cc3 \
-d '
{
"gateway": "TRIPOS_CLOUD_V1",
"processor": "VANTIV_V1"
}'
The response will be a PROVISIONING Merchant
.
{
"id" : "MUpqCXSqrR4qo85P5rZfJkou",
"created_at" : "2022-10-10T05:12:48.99Z",
"updated_at" : "2022-10-10T05:12:48.99Z",
"application" : "APeUbTUjvYb1CdPXvNcwW1wP",
"card_cvv_required" : false,
"card_expiration_date_required" : true,
"convenience_charges_enabled" : false,
"creating_transfer_from_report_enabled" : false,
"default_partial_authorization_enabled" : false,
"fee_ready_to_settle_upon" : "RECONCILIATION",
"gross_settlement_enabled" : false,
"identity" : "IDuWtgdP9VERb4FiLeYatWy",
"level_two_level_three_data_enabled" : false,
"mcc" : null,
"merchant_name" : null,
"merchant_profile" : "MPqLfHpt1nGE5bryfcU6io1Z",
"mid" : null,
"onboarding_state" : "PROVISIONING",
"processing_enabled" : false,
"processor" : "VANTIV_V1",
"processor_details" : { },
"ready_to_settle_upon" : "RECONCILIATION",
"rent_surcharges_enabled" : false,
"settlement_enabled" : false,
"settlement_funding_identifier" : "UNSET",
"tags" : { },
"verification" : "VIkHXrDG6TbrJDex175EQ8Lr",
"_links" : {
"self" : {
"href" : "https://finix.sandbox-payments-api.com/merchants/MUpqCXSqrR4qo85P5rZfJkou"
},
"identity" : {
"href" : "https://finix.sandbox-payments-api.com/identities/IDuWtgdP9VERb4FiLeYatWy"
},
"verifications" : {
"href" : "https://finix.sandbox-payments-api.com/merchants/MUpqCXSqrR4qo85P5rZfJkou/verifications"
},
"merchant_profile" : {
"href" : "https://finix.sandbox-payments-api.com/merchant_profiles/MPqLfHpt1nGE5bryfcU6io1Z"
},
"application" : {
"href" : "https://finix.sandbox-payments-api.com/applications/APeUbTUjvYb1CdPXvNcwW1wP"
},
"verification" : {
"href" : "https://finix.sandbox-payments-api.com/verifications/VIkHXrDG6TbrJDex175EQ8Lr"
}
}
}