Onboarding Rejections

If your seller gets rejected during onboarding, the merchant will have a status of REJECTED. You need to handle these rejections with the API or with the Dashboard.

Handle Rejections With the Dashboard

You can handle onboarding rejections with the dashboard or API. We recommend using the API as these rejections can be handled programmatically, but the dashboard is available to use.

Navigate to 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.

Once you are 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.

Handle Rejections With API

Handling seller rejections with 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" : "VI9MtEd7WrnFubM6hTD8tf4p",
      "application" : "APvGdcrgw3fEycfHQPpv9bmC",
      "tags" : {
        "underwriting_tag" : "underwriting_6rlNN"
      },
      "messages" : [ "INVALID_OWNER_DATA" ],
      "raw" : [ {
        "outcome_code" : "INVALID_OWNER_DATA",
        "description" : "The owner(s) information could not be verified.",
        "remediation" : "Verify and resubmit the information by updating the Identity and submitting a new Merchant Verification."
      } ],
      "processor" : "LITLE_V1",
      "state" : "FAILED",
      "created_at" : "2021-12-16T23:43:52.21Z",
      "updated_at" : "2021-12-17T01:12:33.47Z",
      "trace_id" : "FNX4rcQDMx8mRF9MXp7fZDLuA",
      "payment_instrument" : null,
      "merchant" : "MU9feGj6XnSpn7D137JqZ5yw",
      "merchant_identity": "IDTiyTks118XhKcxSLsArzu", 
      "identity" : null,
      "_links" : {
        "self" : {
          "href" : "https://internal.sandbox-payments-api.com/verifications/VI9MtEd7WrnFubM6hTD8tf4p"
        },
        "application" : {
          "href" : "https://internal.sandbox-payments-api.com/applications/APvGdcrgw3fEycfHQPpv9bmC"
        },
        "merchant" : {
          "href" : "https://internal.sandbox-payments-api.com/merchants/MU9feGj6XnSpn7D137JqZ5yw"
        }
      }
    }
Hosted Onboarding

Hosted Onboarding does not allow handling reject flows for onboarding. You wil 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

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.
  1. Update the Identity of the merchant with the correct information.
  2. 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.
  1. Review the ID Verification documents that were submitted.
  2. Verify the documents match the owner's full name, is readable, and isn't expired. Rescan the documents if needed.
  3. 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.
  1. Create a new Payment Instrument for the merchant. Include the correct routing number When creating the Payment Instrument.
  2. 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.
  1. Create a new Payment Instrument for the merchant. Include the correct bank account number When creating the Payment Instrument.
  2. 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.
  1. 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.
  2. Submit Bank Verification again using your Finix Dashboard or Finix's API.
BANK_NOT_SUPPORTED This bank is not supported.
  1. Use another bank. Create a new Payment Instrument with the new bank account details.
  2. 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.
  1. Review the information that was submitted and confirm the bank account details are correct.
  2. 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.
  1. Update the Identity of the merchant with the correct information.
  2. Submit another request to [provision the `m]Merchant`](/guides/onboarding/onboarding-process/#reverify-a-merchant).
INVALID_BUSINESS_TYPE The business type could not be verified.
  1. Update the Identity of the merchant with the correct business_type.
  2. Submit another request to provision the merchant.
INVALID_TAX_ID_NUMBER Business Tax ID Number could not be verified.
  1. Update the Identity of the merchant with the correct EIN or tax ID.
  2. 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.
  1. Review the EIN Issuance Letter or Tax ID document that was submitted.
  2. Verify the document is clear and readable and matches the details of the merchant. Rescan the document if needed.
  3. 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.
  1. Review the EIN Issuance Letter or Tax ID document that was submitted.
  2. Verify the document is clear and readable and matches the details of the merchant. Rescan the document if needed.
  3. 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.
  1. Update the Identity of the merchant with a different address.
  2. 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 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 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.