# 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](/assets/recipient-onboarding-process.ddd0f0e95a73cd20ff3f0affe5a09a9ac8b0c5ab5b3705b84694b89a031af54f.28b10c14.png)

## 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](#rejected-merchants). |


When these events happen, you'll receive `Merchant Created` and `Merchant Updated` [webhook events](#onboarding-webhooks). 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](/guides/payouts/bank-payouts/) and [card payouts](/guides/payouts/card-payouts).


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


```json
{
    "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`](/api/verifications/getverification).


```shell
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:


```json
{
    "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:


```shell
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.


```json
{
    "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](mailto:support@finix.com).