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`
Merchant is created	`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`
Merchant is rejected	`verification`	`updated`	`verifications[0].state: FAILED`