Onboarding Rejections

Learn what steps to take when a seller gets rejected during onboarding.

If your seller gets rejected during onboarding, the Merchant will have a status of REJECTED.

Handle Rejections With the Dashboard

In the Finix Dashboard, click Merchants > Merchant Accounts. This shows a list of Merchants. Click on the Merchant that failed onboarding and the detail pane at the top shows the reject codes. The dashboard shows the remediation steps you can take.

If you need to update the Identity of your seller with new information, you can click the link at the top of the page labeled Merchant Identity.

When you're ready to reattempt verification, navigate back to the Merchant and click Create Verification then click Create. This reruns verification. Once complete, your seller is ready to process payments.

You can handle onboarding rejections with the dashboard or API. We recommend using the API so you can handle rejections programmatically.

Handle Rejections With the API

Handling seller rejections with the API is the most scalable approach to onboarding sellers.

Use the reject codes to build a UX flow that handles updating a seller's information and provides any documentation that might be needed. The reject codes are listed in the messages field. More information about the reject codes can be found under raw, including:

outcome_code : The reject code used for the decline.
description : A description of what the reject code means and represents.
remediation : The next steps that need to be taken to resolve the reject code.

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"
    }
  }
}

Hosted Onboarding

Onboarding Forms do not allow handling reject flows for onboarding. You will need to update the Identity of the seller with the API.

Most remediations require updating the Identity of the seller. Once you have met the remediations described, reverify the Merchant .

Reject Codes

Finix provides a list of different reject codes with remediation suggestion to make it easy to handle:

Control Owner Verification
Bank Account Verification
Company Verification
Additional Codes
Hard Rejection
Uploading Files

Control Owner Verification

These codes are returned when verifying the Identity of the control owner(s).

Reject Code	Description	Remediation
`INVALID_OWNER_DATA`	The owner(s) information could not be verified.	Update the `Identity` of the `Merchant` with the correct information. Submit another request to provision the `Merchant`.
`ID_VERIFICATION_NEEDED`	ID Verification needed on owner(s).	Submit a valid Driver's License, State ID, or Passport. For more information, see Uploading Files.
`ID_VERIFICATION_FAILED`	ID Verification was unsuccessful.	Review the ID Verification documents that were submitted. Verify the documents match the owner's full name, is readable, and isn't expired. Rescan the documents if needed. Submit ID Verification again using your Finix Dashboard or Finix's API.
`MATCH_LIST_DECLINE`	One or more owner(s) were found to be in the Mastercard (Member Alert to Control High-Risk Merchants) List.	If you believe this is an error, email Customer Service with the `Merchant` ID (MUxx).
`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` ID (MUxx).

Bank Account Verification

These codes are returned when verifying the identity of the control owner(s).
These codes are also returned when verifying the information on the bank account submitted with the Merchant application.

Reject Code	Description	Remediation
`INVALID_BANK_ROUTING_NUMBER`	The routing number is incorrect.	Create a new `Payment Instrument` for the `Merchant` . Include the correct routing number When creating the `Payment Instrument`. Submit another request to provision the merchant with the `Payment Instrument` that has the updated routing number.
`INVALID_BANK_ACCOUNT_NUMBER`	Bank account provided does not belong to the owner and/or business.	Create a new `Payment Instrument` for the `Merchant` . Include the correct bank account number When creating the `Payment Instrument`. Submit another request to provision the `Merchant` with the `Payment Instrument` that has the updated bank account number.
`BANK_VERIFICATION_NEEDED`	Bank account requires verification.	Upload 3 months of bank statements showing bank account number, account holder name, and bank logo. The bank statements must verify that the bank account belongs to the business or control owner. For more information, see Uploading Files.
`BANK_VERIFICATION_FAILED`	Bank statement could not be verified.	Review the bank statements that were submitted and confirm the account number, account holder name, and bank logo are clearly visible in the statement. Rescan the document if needed. Submit Bank Verification again using your Finix Dashboard or Finix's API.
`BANK_NOT_SUPPORTED`	This bank is not supported.	Use another bank. Create a new `Payment Instrument` with the new bank account details. Submit another request to provision the `Merchant` .
`INVALID_BANK_ACCOUNT_OWNERSHIP`	Owner of the bank account does not match the business or owner(s) provided.	Review the information that was submitted and confirm the bank account details are correct. Create a new `Payment Instrument` and submit another request to provision the `Merchant` .

Company Verification

These merchant codes are returned when verifying information saved for the business.

Reject Code	Description	Remediation
`INVALID_BUSINESS_INFORMATION`	Business information could not be verified.	Update the `Identity` of the `Merchant` with the correct information. Submit another request to provision the `Merchant`.
`INVALID_BUSINESS_TYPE`	The business type could not be verified.	Update the `Identity` of the `Merchant` with the correct `business_type`. Submit another request to provision the `Merchant` .
`INVALID_TAX_ID_NUMBER`	Business Tax ID Number could not be verified.	Update the `Identity` of the `Merchant` with the correct EIN or tax ID. Submit another request to provision the `Merchant` .
`TAX_ID_VERIFICATION_NEEDED`	EIN or Tax ID requires verification.	Upload a scan of your EIN Issuance Letter or Tax ID document. For more information, see Uploading Files.
`TAX_ID_VERIFICATION_FAILED`	EIN or Tax ID documentation could not be verified.	Review the EIN Issuance Letter or Tax ID document that was submitted. Verify the document is clear and readable and matches the details of the `Merchant` . Rescan the document if needed. Submit the EIN Issuance Letter or Tax ID document again using your Finix Dashboard or Finix's API.
`INSUFFICIENT_BUSINESS_HISTORY`	Business does not have sufficient history. EIN or Tax ID documentation could not be verified.	Review the EIN Issuance Letter or Tax ID document that was submitted. Verify the document is clear and readable and matches the details of the `Merchant` . Rescan the document if needed. Submit the EIN Issuance Letter or Tax ID document again using your Finix Dashboard or Finix's API.

Additional Codes

Reject Code	Description	Remediation
`INVALID_MCC`	This Merchant Category Code (MCC) is invalid.	We can not support the provided MCC. If the incorrect MCC was provided, update the `Identity` of the `Merchant` and submit another request to provision the `Merchant` .
`PROHIBITED_MCC`	This Merchant Category Code (MCC) is prohibited.	We can not support the provided MCC. If the incorrect MCC was provided, update the `Identity` of the `Merchant` and submit another request to provision the `Merchant` .
`PO_BOX_ADDRESS_NOT_SUPPORTED`	PO Boxes are not support for business and/or personal addresses.	Update the `Identity` of the `Merchant` with a different address. Submit another request to provision the `Merchant` .
`GENERIC_DECLINE`	This merchant application was declined.	We can not board this `Merchant` . If you think this is in error, reach out to Customer Service.
`DECLINED_DO_NOT_SUBMIT_AGAIN`	This merchant will not be underwritten. Please do not submit again.	We can not board this `Merchant` . 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 `Merchant` . If you think this is in error, reach out to Customer Service.
`FINANCIAL_HISTORY`	The business and/or owners have an unacceptable financial history.	We can not board this `Merchant` . If you think this is in error, reach out to Customer Service.
`MULTIPLE_FACTORS`	The business and/or owners have an unacceptable level of risk.	We can not board this `Merchant` . If you think this is in error, reach out to Customer Service.

Hard Rejection

There are a few reject codes that are a hard rejection. That means that the seller or service provider is explicitly rejected and may not be boarded to Finix. Below are the list of applicable reject codes:

Mistaken hard rejection

If you believe a hard rejection is in error, reach out to Finix Support.

GENERIC_DECLINE
DECLINED_DO_NOT_SUBMIT_AGAIN
HIGH_RISK
FINANCIAL_HISTORY
MULTIPLE_FACTORS
MATCH_LIST_DECLINE
OFAC_DECLINE

Uploading Files

Some reject codes require documents (Drivers License, Bank Statements, Passport, etc.) to get resolved. You can use your Finix Dashboard to upload documents or Finix's API to request and submit documents.

For more information, see Uploading Files to Finix.