When you onboard a Recipient, Finix runs global sanctions checks to comply with regulatory requirements for bank and card payouts. Use Finix's APIs, webhooks, or dashboard to listen and respond to updates during the onboarding process.
Onboarding States
When you first create your Recipient's Merchant account, their information will be sent to Finix's underwriting systems. Their Merchant account will start in the PROVISIONING
state, and transition to either APPROVED
or REJECTED
after underwriting. Typically, this happens within seconds of the Merchant account.
State | Description |
---|---|
PROVISIONING |
The request is pending and being processed by Finix's system. |
APPROVED |
The Merchant was successfully onboarded. The Recipient is ready to receive payouts. |
REJECTED |
The Merchant was rejected and you need to handle the rejection. |
When these events happen, you'll receive Merchant Created
and Merchant Updated
webhook events. Use the webhook's onboarding_state
to understand the results and determine next steps.
Approved Merchants
When your Merchant
is APPROVED
, you will receive a Merchant Underwritten
webhook. An approved Merchant
means your seller is ready to receive bank payouts and card payouts.
{
"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": "APPROVED",
"processing_enabled": true,
"processor": "DUMMY_V1",
"ready_to_settle_upon": null,
"settlement_enabled": true,
"settlement_funding_identifier": "UNSET",
"surcharges_enabled": false,
"verification": "VItYKnaucfcaRNdb48y1kr3F"
}
Rejected Merchants
Should your Merchant
get REJECTED
, you will receive a Merchant Updated
webhook with onboarding_state: REJECTED
. Rejections happen in rare cases when Finix isn't able to approve your Merchant as-is. Typically, this means that your Merchant has invalid data (for example, an incorrect address), or is missing data.
{
"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,
"verification": "VItYKnaucfcaRNdb48y1kr3F"
}
To learn why Finix rejected your Merchant, and how you can resolve the issue, use the Merchant's verification
ID to fetch the Verification
.
curl https://finix.sandbox-payments-api.com/verifications/VItYKnaucfcaRNdb48y1kr3F \
-H "Content-Type: application/json" \
-H 'Finix-Version: 2022-02-01' \
-u "USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041"
The Verification's messages
and raw
fields will have codes explaining the rejection:
{
"id": "VItYKnaucfcaRNdb48y1kr3F",
"created_at": "2024-09-13T19:25:31.60Z",
"updated_at": "2024-09-13T19:25:31.68Z",
"application": "APrMqXwT4CE9sRjtGaHcYJN7",
"identity": null,
"merchant": "MU9KBbc3MWNwcDgF78PAh92b",
"merchant_identity": "ID5kBwNdEVcdaFcksHSEVfJu",
"messages": [
"INVALID_OWNER_DATA"
],
"outcome_summary": null,
"outcomes": null,
"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": "INVALID_OWNER_DATA",
"description": "Business Tax ID Number could not be verified.",
"remediation_item": "Ensure a valid EIN or Tax ID is supplied by updating Identity and submitting a new Merchant Verification."
}
],
"state": "FAILED",
"tags": {},
"trace_id": "FNXjmWCgqrQ23hFDfRhEyC4Nr",
"type": "MERCHANT",
"_links": {
"self": {
"href": "https://finix.sandbox-payments-api.com/verifications/VItYKnaucfcaRNdb48y1kr3F"
},
"application": {
"href": "https://finix.sandbox-payments-api.com/applications/APrMqXwT4CE9sRjtGaHcYJN7"
},
"merchant": {
"href": "https://finix.sandbox-payments-api.com/merchants/MU9KBbc3MWNwcDgF78PAh92b"
}
}
}
Soft Rejections
In most cases, Finix will send "soft rejections" that do not block onboarding. When you receive these codes, you can re-submit your Merchant to Finix's underwriting system after resolving the issue. Typically, the most common soft rejection outcome_code
is INVALID_OWNER_DATA
, which happens when your Recipient has invalid or missing data.
outcome_code |
description |
remediation_item |
---|---|---|
BANK_VERIFICATION_NEEDED |
Bank account requires verification. | Provide three months of bank statements showing bank account number, account holder name, and bank logo. This statement must verify that the bank account details belong to the business or control owner. Email Customer Service with the Merchant Resource (MUxx). Customer Service will follow up with a secure link to upload three months of bank statements. |
ID_VERIFICATION_NEEDED |
ID Verification needed on owner(s). | Submit a valid Driver's License, State ID, or Passport. To submit these file(s), use our File Upload feature. |
INSUFFICIENT_BUSINESS_HISTORY |
Business does not have sufficient history. Additional verification needed. | Email Customer Service with the Merchant Resource (MUxxx). Customer Service will follow up with a secure link and required information and/or documentation. |
INVALID_BANK_ACCOUNT_DETAILS |
Bank account details could not be verified. | Verify the bank account details and resubmit by creating a new Payment Instrument and submitting a new Merchant Verification. |
INVALID_BANK_ACCOUNT_NUMBER |
Bank account provided does not belong to the owner and/or business. | Verify the bank account details and resubmit by creating a new Payment Instrument and submitting a new Merchant Verification. |
INVALID_BANK_ROUTING_NUMBER |
The routing number is incorrect. | Provide the correct routing number associated with the bank account by creating new Payment Instrument and submitting a new Merchant Verification. |
INVALID_OWNER_DATA |
The owner(s) information could not be verified. | Verify and resubmit the information by updating the Identity and submitting a new Merchant Verification. |
PO_BOX_ADDRESS_NOT_SUPPORTED |
PO Boxes are not supported for business and/or personal addresses. | Provide a different address by updating Identity and submitting a new Merchant Verification. |
Most steps to resolve rejections involve updating the information of the recipient's Identity
. After updating the Identity
, create a new Verification
to send the Merchant back to Finix's underwriting systems:
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 '{}'
This will place your Merchant back in the PROVISIONING
state, at which point they will go through the underwriting process again.
{
"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": "PROVISIONING",
"processing_enabled": true,
"processor": "DUMMY_V1",
"ready_to_settle_upon": null,
"settlement_enabled": true,
"settlement_funding_identifier": "UNSET",
"surcharges_enabled": false,
"verification": "VItYKnaucfcaRNdb48y1kr3F"
}
Hard Rejections
In some cases, Finix will assign hard rejection codes when we cannot board your Merchant. If you have any questions, please reach out to your Finix point of contact or the Finix Support team.
outcome_code |
description |
remediation_item |
---|---|---|
BANK_NOT_SUPPORTED |
This bank is not supported. | Use another bank. Create a new Payment Instrument and submit a new Merchant Verification. |
BANK_VERIFICATION_FAILED |
Bank statement could not be verified. | Ensure the account number, account holder name, and bank logo are clearly visible in the statement. Resubmit Bank Verification to the link provided by Customer Service for the Merchant Resource (MUxx). |
DECLINED_DO_NOT_SUBMIT_AGAIN |
This merchant will not be underwritten. Please do not submit again. | We can not board this user. If you think this is in error, reach out to Customer Service. |
GENERIC_DECLINE |
This merchant application was declined. | We can not board this user. If you think this is in error, reach out to Customer Service. |
HIGH_RISK |
The business and/or owners have an unacceptable level of risk. | We can not board this user. If you think this is in error, reach out to Customer Service. |
INVALID_BANK_ACCOUNT_OWNERSHIP |
Owner of the bank account does not match the business or owner(s) provided. | Verify the bank account details and resubmit by creating a new Payment Instrument and submitting a new Merchant Verification. |
MULTIPLE_FACTORS |
The business and/or owners have an unacceptable level of risk. | We can not board this user. If you think this is in error, reach out to Customer Service. |
OFAC_DECLINE |
One or more owner(s) were found to be in the OFAC List. | If you believe this is an error, email Customer Service with the Merchant Resource (MUxx). Customer Service will follow up with a secure link to upload a photo for ID Verification. |
POTENTIAL_FRAUD |
The business and/or owners have an unacceptable level of risk. | We can not board this user. If you think this is in error, reach out to Customer Service. |
Onboarding Webhooks
Finix recommends integrating into our webhooks to learn about your Merchant's onboarding progress. See our Webhooks guide for instructions on using our webhooks.
Webhook properties | |||
---|---|---|---|
Lifecycle event
|
entity |
type |
_embedded |
Merchant is created | merchant |
created |
merchants[0].onboarding_state: PROVISIONING |
verification |
created |
verifications[0].state: PENDING |
|
Merchant is approved | merchant |
underwritten |
merchants[0].onboarding_state: APPROVED |
merchant |
updated |
merchants[0].onboarding_state: APPROVED |
|
verification |
updated |
verifications[0].state: SUCCEEDED |
|
Merchant is rejected | merchant |
updated |
merchants[0].onboarding_state: REJECTED |
verification |
updated |
verifications[0].state: FAILED |