Recipient Verification Process

Learn how to onboard Recipients to receive payouts.


When you onboard a Recipient, Finix runs global sanctions checks to comply with regulatory requirements for bank and card payouts. Use Finix's APIs, webhooks, or dashboard to listen and respond to updates during the onboarding process.

Onboarding Diagram

Onboarding States

When you first create your Recipient's Merchant account, their information will be sent to Finix's underwriting systems. Their Merchant account will start in the PROVISIONING state, and transition to either APPROVED or REJECTED after underwriting. Typically, this happens within seconds of the Merchant account.

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

When these events happen, you'll receive Merchant Created and Merchant Updated webhook events. Use the webhook's onboarding_state to understand the results and determine next steps.

Approved Merchants

When your Merchant is APPROVED, you will receive a Merchant Underwritten webhook. An approved Merchant means your seller is ready to receive bank payouts and card payouts.

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": "APPROVED",
    "processing_enabled": true,
    "processor": "DUMMY_V1",
    "ready_to_settle_upon": null,
    "settlement_enabled": true,
    "settlement_funding_identifier": "UNSET",
    "surcharges_enabled": false,
    "verification": "VItYKnaucfcaRNdb48y1kr3F"
}

Rejected Merchants

Should your Merchant get REJECTED, you will receive a Merchant Updated webhook with onboarding_state: REJECTED. Rejections happen in rare cases when Finix isn't able to approve your Merchant as-is. Typically, this means that your Merchant has invalid data (for example, an incorrect address), or is missing data.

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,
    "verification": "VItYKnaucfcaRNdb48y1kr3F"
}

To learn why Finix rejected your Merchant, and how you can resolve the issue, use the Merchant's verification ID to fetch the Verification.

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

The Verification's messages and raw fields will have codes explaining the rejection:

Copy
Copied
{
    "id": "VItYKnaucfcaRNdb48y1kr3F",
    "created_at": "2024-09-13T19:25:31.60Z",
    "updated_at": "2024-09-13T19:25:31.68Z",
    "application": "APrMqXwT4CE9sRjtGaHcYJN7",
    "identity": null,
    "merchant": "MU9KBbc3MWNwcDgF78PAh92b",
    "merchant_identity": "ID5kBwNdEVcdaFcksHSEVfJu",
    "messages": [
        "INVALID_OWNER_DATA"
    ],
    "outcome_summary": null,
    "outcomes": null,
    "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": "INVALID_OWNER_DATA",
            "description": "Business Tax ID Number could not be verified.",
            "remediation_item": "Ensure a valid EIN or Tax ID is supplied by updating Identity and submitting a new Merchant Verification."
        }
    ],
    "state": "FAILED",
    "tags": {},
    "trace_id": "FNXjmWCgqrQ23hFDfRhEyC4Nr",
    "type": "MERCHANT",
    "_links": {
        "self": {
            "href": "https://finix.sandbox-payments-api.com/verifications/VItYKnaucfcaRNdb48y1kr3F"
        },
        "application": {
            "href": "https://finix.sandbox-payments-api.com/applications/APrMqXwT4CE9sRjtGaHcYJN7"
        },
        "merchant": {
            "href": "https://finix.sandbox-payments-api.com/merchants/MU9KBbc3MWNwcDgF78PAh92b"
        }
    }
}

Soft Rejections

In most cases, Finix will send "soft rejections" that do not block onboarding. When you receive these codes, you can re-submit your Merchant to Finix's underwriting system after resolving the issue. Typically, the most common soft rejection outcome_code is INVALID_OWNER_DATA, which happens when your Recipient has invalid or missing data.

outcome_code
description
remediation_item
BANK_VERIFICATION_NEEDED Bank account requires verification. Provide three months of bank statements showing bank account number, account holder name, and bank logo. This statement must verify that the bank account details belong to the business or control owner. Email Customer Service with the Merchant Resource (MUxx). Customer Service will follow up with a secure link to upload three months of bank statements.
ID_VERIFICATION_NEEDED ID Verification needed on owner(s). Submit a valid Driver's License, State ID, or Passport. To submit these file(s), use our File Upload feature.
INSUFFICIENT_BUSINESS_HISTORY Business does not have sufficient history. Additional verification needed. Email Customer Service with the Merchant Resource (MUxxx). Customer Service will follow up with a secure link and required information and/or documentation.
INVALID_BANK_ACCOUNT_DETAILS Bank account details could not be verified. Verify the bank account details and resubmit by creating a new Payment Instrument and submitting a new Merchant Verification.
INVALID_BANK_ACCOUNT_NUMBER Bank account provided does not belong to the owner and/or business. Verify the bank account details and resubmit by creating a new Payment Instrument and submitting a new Merchant Verification.
INVALID_BANK_ROUTING_NUMBER The routing number is incorrect. Provide the correct routing number associated with the bank account by creating new Payment Instrument and submitting a new Merchant Verification.
INVALID_OWNER_DATA The owner(s) information could not be verified. Verify and resubmit the information by updating the Identity and submitting a new Merchant Verification.
PO_BOX_ADDRESS_NOT_SUPPORTED PO Boxes are not supported for business and/or personal addresses. Provide a different address by updating Identity and submitting a new Merchant Verification.

Most steps to resolve rejections involve updating the information of the recipient's Identity. After updating the Identity, create a new Verification to send the Merchant back to Finix's underwriting systems:

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

This will place your Merchant back in the PROVISIONING state, at which point they will go through the underwriting process again.

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": "PROVISIONING",
    "processing_enabled": true,
    "processor": "DUMMY_V1",
    "ready_to_settle_upon": null,
    "settlement_enabled": true,
    "settlement_funding_identifier": "UNSET",
    "surcharges_enabled": false,
    "verification": "VItYKnaucfcaRNdb48y1kr3F"
}

Hard Rejections

In some cases, Finix will assign hard rejection codes when we cannot board your Merchant. If you have any questions, please reach out to your Finix point of contact or the Finix Support team.

outcome_code
description
remediation_item
BANK_NOT_SUPPORTED This bank is not supported. Use another bank. Create a new Payment Instrument and submit a new Merchant Verification.
BANK_VERIFICATION_FAILED Bank statement could not be verified. Ensure the account number, account holder name, and bank logo are clearly visible in the statement. Resubmit Bank Verification to the link provided by Customer Service for the Merchant Resource (MUxx).
DECLINED_DO_NOT_SUBMIT_AGAIN This merchant will not be underwritten. Please do not submit again. We can not board this user. If you think this is in error, reach out to Customer Service.
GENERIC_DECLINE This merchant application was declined. We can not board this user. 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 user. If you think this is in error, reach out to Customer Service.
INVALID_BANK_ACCOUNT_OWNERSHIP Owner of the bank account does not match the business or owner(s) provided. Verify the bank account details and resubmit by creating a new Payment Instrument and submitting a new Merchant Verification.
MULTIPLE_FACTORS The business and/or owners have an unacceptable level of risk. We can not board this user. If you think this is in error, reach out to Customer Service.
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 Resource (MUxx). Customer Service will follow up with a secure link to upload a photo for ID Verification.
POTENTIAL_FRAUD The business and/or owners have an unacceptable level of risk. We can not board this user. If you think this is in error, reach out to Customer Service.

Onboarding Webhooks

Finix recommends integrating into our webhooks to learn about your Merchant's onboarding progress. See our Webhooks guide for instructions on using our webhooks.

Webhook properties
Lifecycle event
entity
type
_embedded
Merchant is created merchant created merchants[0].onboarding_state: PROVISIONING
verification created verifications[0].state: PENDING
Merchant is approved merchant underwritten merchants[0].onboarding_state: APPROVED
merchant updated merchants[0].onboarding_state: APPROVED
verification updated verifications[0].state: SUCCEEDED
Merchant is rejected merchant updated merchants[0].onboarding_state: REJECTED
verification updated verifications[0].state: FAILED