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.

Recipient Onboarding Process

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 Recipients

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.

{
    "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 Recipients

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.

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

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:

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

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:

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

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

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