Deprecated API Reference

This API Reference is being deprecated. Please use the New API Reference.

Reject Codes

If your Merchant gets rejected during onboarding, Finix's API lets you know by sending a reject code via a webhook.

You can use these reject codes to build a UX flow for yourMerchants so they can update their information and provide any documentation that might be needed.

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

Uploading Files

Some reject codes require documents (Drivers License, Bank Statements, Passport, etc.) to resolve. 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.

Viewing Rejections

To see why a Merchant was declined and the specific reject code that was used, fetch the Merchant .

The reject codes that were used for the decline will be listed under messages. 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"
    }
  }
}