Update Requests

In some cases, Finix requests documents or data updates during the seller onboarding process. Finix requests these updates when we need additional information to verify your sellers (for example, if we cannot identify the bank account's owner), or when your seller's data is invalid (for example, if the bank account's routing number does not belong to a financial institution).

When this happens, Finix will move the Merchant to the Update Requested state and re-review their application after receiving the requested updates. This guide explains how to handle update requests with our Dashboard and APIs.

Handling Update Requests with the Dashboard

Viewing Update Requests

On the Merchants > Merchant Accounts page, you can see all Merchants in your system. The Update Requested tab [1] shows all Merchants with outstanding update requests. To see the updates Finix has requested, you can check the Onboarding State column [2], or click on the Merchant to navigate to their account page.

On the Merchant page, you will find details about the documents and data updates Finix has requested. You may also see notes providing additional context about the requested updates (for example, we may include a note explaining that the bank account routing number is invalid).

Making Updates with Onboarding Forms

If you boarded your Merchant with an Onboarding Form, your Merchant can make the requested updates using their original Onboarding Form. To do this, use the Get Onboarding Form Link button on the Merchant page to get and copy your Merchant's Onboarding Form link. You can send the link to your Merchant however you like (for example, over email).

Once your Merchant is back inside their Onboarding Form, they will see exactly which documents and data updates Finix has requested [1]. They will have file uploaders for each document [2], and we will highlight each field they need to update in red [3].

After your Merchant completes the requested updates and re-submits their Onboarding Form, Finix will update their Onboarding State state back to Provisioning and re-review their application. No action is needed from your team at this point (Finix will automatically create a new verification on their account).

Making Updates with the Dashboard

Alternatively, your team can make updates to your Merchants directly inside the Finix Dashboard. You might do this if you already have the requested documents or correct data on-hand, and prefer to handle the update request on behalf of your Merchant.

You can upload documents on the Merchant page [1], as well as navigate to and edit their Identity to make data updates [2]. Your Merchant can upload files through their own Dashboard as well. After uploading files or updating the Identity, your team must create a new verification on the Merchant [3] to put the Merchant back in the underwriting process for further review.

Finix advises making updates with Onboarding Forms to streamline this process, but offers the option to make updates through the Dashboard to give your team the most flexibility.

Notifications

Finix offers notifications through both email and the Finix dashboard, making it easy for your team to receive updates as your sellers progress through onboarding. For example, your team can subscribe to receive notifications when your sellers submit their Onboarding Forms and are approved.

To learn more about notifications, see Notifications and Webhooks.

Handling Update Requests with the API

Merchant Resource

When Finix requests updates from your Merchant, your Merchant's onboarding_state will be UPDATE_REQUESTED.

{
    "id": "MUno35MtzSMr61mUvY7qCayR",
    "created_at": "2022-01-27T07:36:58.19Z",
    "updated_at": "2022-10-06T20:25:24.06Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "card_cvv_required": false,
    "card_expiration_date_required": true,
    "convenience_charges_enabled": false,
    "creating_transfer_from_report_enabled": true,
    "default_partial_authorization_enabled": false,
    "fee_ready_to_settle_upon": "RECONCILIATION",
    "gross_settlement_enabled": false,
    "identity": "IDpYDM7J9n57q849o9E9yNrG",
    "level_two_level_three_data_enabled": false,
    "mcc": "4900",
    "merchant_name": "Bobs Burgers",
    "merchant_profile": "MPzW2oRPtkLxK3fymcMACFi",
    "mid": "FNXh6htoPnfwmgGdvaG4L67Q1",
    "onboarding_state": "UPDATE_REQUESTED",
    "processing_enabled": true,
    "processor": "DUMMY_V1",
    "processor_details": {},
    "ready_to_settle_upon": "RECONCILIATION",
    "rent_surcharges_enabled": false,
    "settlement_enabled": true,
    "settlement_funding_identifier": "UNSET",
    "surcharges_enabled": false,
    "tags": {},
    "verification": "VIxfDrRKZZzkCDDbeCT15oDN",
    "_links": {}
}

Verification Resource

When Finix requests updates from your Merchant, the Verification will have state: FAILED, as well as an outcomes array listing each outcome_code assigned to your Merchant. In addition, your Merchant will have an outcome_summary providing additional context about the requested updates (for example, we may include a note explaining the bank account routing number is invalid). Use the Merchant's Verification ID (verification) to get the Verification.

{
    "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"
    ],
    "outcomes": [
        {
            "outcome_code": "BANK_STATEMENT_ONE_MONTH_REQUESTED",
            "remediation_details": {
                "type": "FILE_UPLOAD",
                "file_type": "BANK_STATEMENT_ONE_MONTH",
                "entity_type": "IDENTITY",
                "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA"
            }
        },
        {
            "outcome_code": "INVALID_BUSINESS_TAX_ID",
            "remediation_details": {
                "type": "FIELD_UPDATE",
                "field_name": "entity.business_tax_id",
                "entity_type": "IDENTITY",
                "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA"
            }
        }
    ],
    "outcome_summary": "Requesting a bank statement and valid business tax ID.",
    "payment_instrument": null,
    "payment_instrument_verification_details": {},
    "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": {}
}

outcomes format

Each object in outcome_codes has the following properties, including remediation_details that describe how to resolve the outcome codes to get your Merchant boarded.

Jump to Outcome Codes to see the possible outcomes Finix will assign to your Merchants.

Migrating Your Integration

If you are already integrated into the Verification resource, you will not need to update your integration into the messages and raw fields. To maintain backward compatibility, Finix maps the new outcomes object into those fields. While this lets you continue using those fields as needed, we encourage you to update your integration to get the most value from the Verification resource.

Onboarding Form Resource

If you boarded your Merchant with an Onboarding Form, their Onboarding Form will have status: UPDATE_REQUESTED when Finix requests updates from them. When your Merchant resubmits their Onboarding Form, it will move back to status: COMPLETED.

{
    "id": "obf_cJUfiz97L8de54EwkC3Hiu",
    "onboarding_data": {
        "entity": {...},
        "associated_entities": [...],
        "payment_instruments": {...},
        "additional_underwriting_data": {...},
        "max_transaction_amount": 100000
    },
    "merchant_processors": [...],
    "onboarding_link_details": {...},
    "onboarding_link": {...},
    "status": "UPDATE_REQUESTED",
    "identity_id": null,
    "application_id": "APgPDQrLD52TYvqazjHJJchM",
    "created_at": "2023-03-30T19:16:28.377022Z",
    "updated_at": "2023-03-30T19:16:28.377022Z",
    "tags": {}
}

Updating Fields

If the Verification has any outcomes with remediation_details.type: FIELD_UPDATE, you will need to update the specified Identity based on the field_name and entity_id. In the example below, you would need to update business_tax_id for ID5ZbV3hkc7eLxNhmFjfrrYA.

{
    "outcome_code": "INVALID_BUSINESS_TAX_ID",
    "remediation_details": {
        "type": "FIELD_UPDATE",
        "field_name": "entity.business_tax_id",
        "entity_type": "IDENTITY",
        "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA"
    }
}

To perform these updates, Finix recommends asking your Merchants to review and update the specified fields within your application or onboarding flow. You can update the Identity with a PUT request. If you board a Merchant with any associated_identities, be sure to update the correct Identity when making the PUT request.

curl "https://finix.sandbox-payments-api.com/identities/ID5ZbV3hkc7eLxNhmFjfrrYA" \
  -H "Content-Type: application/json" \
  -H "Finix-Version: 2022-02-01" \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X PUT \
  -d '
  {
    "entity": {
        "business_tax_id": "112222222"
    }
  }'

Finix does not include additional context in remediation_details that describe why the existing field is incorrect or the update was requested. However, Finix assigns these codes when we believe the fields have incorrect data. We recommend asking the Merchant to review and update the field as-needed. Finix may provide additional context on the requested updates through the outcome_summary field, but we do not recommend displaying this to your Merchant as it comes directly from the Finix underwriting team and is not meant for your end users.

Updating Bank Accounts

In some cases, Finix will assign outcome codes indicating that your Merchant's bank account details are incorrect (for example, Finix will assign INVALID_PAYMENT_INSTRUMENT_BANK_CODE if the bank account's routing number is invalid). To handle these outcome codes, you should collect the correct bank account details from your Merchant and create a new Payment Instrument:

curl "https://finix.sandbox-payments-api.com/payment_instruments" \
  -H 'Accept: application/hal+json' \
  -H 'Content-Type: application/json' \
  -H 'Finix-Version: 2022-02-01' \
  -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e \
  -X POST \
  -d '
  {
    "account_number": "123123123",
    "account_type": "SAVINGS",
    "bank_code": "123123123",
    "identity": "ID5ZbV3hkc7eLxNhmFjfrrYA",
    "name": "John Smith",
    "type": "BANK_ACCOUNT"
  }'

Finix does not support editing Payment Instruments' account and routing numbers, so we recommend always creating a new Payment Instrument when handling outcome codes for invalid bank account data. Jump to Outcome Codes to see the outcome codes for invalid bank account data.

Uploading Files

If the Verification has any outcomes with remediation_details.type: FILE_UPLOAD, you will need to upload Files linked to the specified Identity based on the file_type and entity_id. In the example below, you would need to upload a BANK_STATEMENT_ONE_MONTH File linked to ID5ZbV3hkc7eLxNhmFjfrrYA.

{
    "outcome_code": "BANK_STATEMENT_ONE_MONTH_REQUESTED",
    "remediation_details": {
        "type": "FILE_UPLOAD",
        "file_type": "BANK_STATEMENT_ONE_MONTH",
        "entity_type": "IDENTITY",
        "entity_id": "ID5ZbV3hkc7eLxNhmFjfrrYA"
    }
}

Jump to File Types to see the new File types Finix supports, and see Uploading Files to Finix for instructions on uploading Files to Finix via API or Dashboard.

Creating Verifications

After resolving all outcome codes by updating fields or uploading files, you are ready put your Merchant back into underwriting process for further review. To do this, create another verification on the Merchant:

curl "https://finix.sandbox-payments-api.com/merchants/MUno35MtzSMr61mUvY7qCayR/verifications" \
    -H "Content-Type: application/json" \
    -H 'Finix-Version: 2022-02-01' \
    -u USsRhsHYZGBPnQw8CByJyEQW:8a14c2f9-d94b-4c72-8f5c-a62908e5b30e
    -X POST

Webhooks

Finix sends webhooks to update you about your seller's progress throughout the onboarding process. For example, you can listen to the Merchant Updated and Merchant Underwritten events to know when your Merchant transitions from PROVISIONING to another state.

To learn more about webhooks, see Notifications and Webhooks.

Outcome Codes

Business Outcome Codes

Finix assigns these outcome codes when there are issues related to your Merchant's business data. Use the remediation_details to know how to correct the issues and get the Merchant boarded. In these cases, the Merchant's onboarding_state is set to UPDATE_REQUESTED.

Business File Upload Requests

Business Field Update Requests

Owner Outcome Codes

Finix assigns these outcome codes when there are issues related to one or more of your Merchant's owners. Use the remediation_details to know how to correct the issues and get the Merchant boarded. In these cases, the Merchant's onboarding_state is set to UPDATE_REQUESTED.

Owner File Upload Requests

Owner Field Update Requests

Bank Account Outcome Codes

Finix assigns these outcome codes when there are issues related to your Merchant's bank account. Use the remediation_details to know how to correct the issues and get the Merchant boarded. In these cases, the Merchant's onboarding_state is set to UPDATE_REQUESTED.

Bank Account File Upload Requests

Bank Account Field Update Requests