Verification Requirements for Payouts

Learn what recipient information is required to process payouts.

When you onboard a recipient, Finix conducts an OFAC check to verify they are not on government or US watchlists. You can use Webhooks to listen and respond to rejections, all within the Finix API and Dashboard.

onboarding flows

Onboarding Webhooks

We recommend integrating into our webhooks to get alerted when a rejection occurs. Several webhook events get sent during the onboarding process. See Webhooks for details on how to set up webhooks.

Onboarding States

Once you've verified and onboarded the recipient, a Merchant gets created in a PROVISIONING state until approved or rejected.

When a decision gets made, a webhook event with entity merchant and type updated gets sent. It can take anywhere from seconds to several minutes to review and underwrite a Merchant. Use the onboarding_state to understand the result and the next steps to take with the recipient:

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 a payout.
REJECTED The Merchant was rejected and you need to handle the rejection.

Approved Merchants

When a Merchant is APPROVED, you receive a webhook event with entity merchant and type underwritten.

An approved Merchant means your seller is ready to receive a bank payout or card payout.

The following details the different onboarding states and how to handle rejections.

onboarding states flows

Merchant Underwritten Webhook Event
Copy
Copied
{
    "type": "underwritten",
    "entity": "merchant",
    "occured_at": "2021-11-14T19:20:29.48Z",
    "_embedded": {
        "merchants": [
            {
                "id": "MUoBGzwPdFxb397BKM3bHUvf",
                "application": "APcVnXxyWotD6TGRWV2bRWuD",
                "identity": "IDgXNAaoy5d4TLkp5ze6gScA",
                "verification": "VIeZ3gBoRemaDimjp6qS58An",
                "merchant_profile": "MP9e916zYUTTqHUDe4F9ZQvp",
                "processor": "DUMMY_V1",
                "processing_enabled": true,
                "settlement_enabled": true,
                "gross_settlement_enabled": false,
                "creating_transfer_from_report_enabled": false,
                "card_expiration_date_required": true,
                "card_cvv_required": false,
                "tags": {
                    "key_2": "value_2"
                },
                "mcc": "4900",
                "mid": "FNXqtgiZAvNPz44hT67Ai632W",
                "merchant_name": "Finix Flowers",
                "settlement_funding_identifier": "UNSET",
                "ready_to_settle_upon": null,
                "fee_ready_to_settle_upon": "RECONCILIATION",
                "level_two_level_three_data_enabled": false,
                "created_at": "2021-11-14T19:20:29.15Z",
                "updated_at": "2021-11-14T19:20:29.48Z",
                "onboarding_state": "APPROVED"
            }
        ]
    }
}

Rejected Merchants

Sometimes a recipient does not pass verification and the onboarding_state of the Merchant gets set as REJECTED. Usually, a REJECTED state means Finix requires more information to verify the user's identity and enable processing.

Here is an example of a rejected Merchant:

Copy
Copied
{
    "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,
    "tags": {
        "key_2": "value_2"
    },
    "verification": "VIeZ3gBoRemaDimjp6qS58An"
}

To understand what the rejection is, look up the Verification that got created for the Merchant.

Copy
Copied
curl https://finix.sandbox-payments-api.com/verifications/VIpdSnQwTNeWgMHXvFDCPVsx \
-H "Content-Type: application/json" \
-H 'Finix-Version: 2022-02-01' \
-u "USimz3zSq5R2PqiEBXY6rSiJ:8bacba32-9550-48ff-b567-fe7648947041"

Example response:

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

The raw field will contain an array of the rejections and suggestions to get the Merchant approved. Though we recommend building your integration to handle every reject code.

attention

We may add new reject codes over time to help improve the onboarding process.

Most steps to resolve rejections involve updating the information of the recipient's Identity. Once you've updated the Identity, try verifying the Merchant again.

Please note, some reject codes are hard rejections which means the Identity can not be onboarded to Finix. Hard-rejected sellers won't be able to process payments on Finix. If you have any questions, please reach out to your Finix point of contact or the Finix Support team.

Reverifying a Merchant

Reverify a Merchant when:

  • The Merchant initially rejected and failed onboarding. Update the Identity and attempt onboarding again (also called reattempting Merchant provisioning ).
  • Your recipient needs to update their information, which also requires updating the Identity and attempting onboarding again once the changes have been made by the recipient.

If more information is requested, update the Identity and then resubmit the information to Finix. To resubmit the information to Finix, attempt onboarding again by creating a new Verification on the Merchant:

Copy
Copied
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 '{}'

A successful response returns a 200 and a PENDING Verification resource.

Copy
Copied
{
    "id": "VI4zELwvT6beu2bJpwG24zLF",
    "created_at": "2022-10-10T05:06:04.88Z",
    "updated_at": "2022-10-10T05:06:04.93Z",
    "application": "APgPDQrLD52TYvqazjHJJchM",
    "identity": null,
    "merchant": "MUucec6fHeaWo3VHYoSkUySM",
    "merchant_identity": "IDpYDM7J9n57q849o9E9yNrG",
    "messages": [],
    "payment_instrument": null,
    "processor": "DUMMY_V1",
    "raw": null,
    "state": "PENDING",
    "tags": {},
    "trace_id": "002ef04f-9227-4179-8232-3dc2df8fa8a0",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/verifications/VI4zELwvT6beu2bJpwG24zLF"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APgPDQrLD52TYvqazjHJJchM"
        },
        "merchant": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MUucec6fHeaWo3VHYoSkUySM"
        }
    }
}

The Merchant resource will update back to a PROVISIONING stage and you will be notified via webhook when a decision is made.