> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mangopay.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mangopay.com/_mcp/server.

# Business - Legacy single-session flow

> Details of the legacy single-session flow for Business users, where a single legal representative is verified within the main session

This page describes the previous hosted IDV flow for the Business user type (the **legacy integrated flow**), in which a single individual completes the liveness check within the main IDV Session.

If your platform has been migrated to the new flow (the **multi-session PSC flow**), where all

Persons of Significant Control (PSCs)

are verified individually through separate PSC Sessions, see the [Business](/guides/users/verification/hosted/business) guide instead.

## Prerequisites

Before launching a hosted IDV Session for a Business, please ensure that:

* The **Registration Proof** they will need to upload conforms to the one [expected by Mangopay](/guides/users/verification/requirements/kyb-local)
* The **Articles of Association** they may need to upload conforms to the one [expected by Mangopay](/guides/users/verification/requirements/kyb-local)
* They have details about their business and all beneficial owners ([definition here](/guides/glossary#beneficial-owner-ubo))
* An individual listed in the national registry is available to perform the liveness check (the link can be closed and reopened)
* The **ID proof** the individual will use is [accepted by Mangopay](/guides/users/verification/requirements/id-accepted)

## Flow description

Currently, when a hosted IDV session is generated for a Legal Business:

1. The session `Status` is `PENDING` and can be submitted within 7 days, at which point it becomes `EXPIRED`. This emits the `IDENTITY_VERIFICATION_PENDING` [webhook](#webhooks).
2. The user opens the session and sees a welcome screen explaining:
   * That they will need to provide business details
   * That they may need to provide **Registration Proof (RP)** and **Articles of Association (AoA)** documents (links to the [KYB local](/guides/users/verification/requirements/kyb-local) page are provided later in the flow)
   * That a **registered director** (not necessarily the one listed in the `LegalRepresentative` fields) will need to complete the liveness check with their ID and smartphone, with a link to Mangopay's [accepted ID documents](/guides/users/verification/requirements/id-accepted)
3. The user enters business details:
   * Country of incorporation
   * Registration number provided by the relevant national authority
   * Registered business name
   * Registered business address
4. The user declares one or more **beneficial owners (UBOs)** as

   Persons of Significant Control (PSC)
5. Mangopay performs registry lookup using the business details:
   * `BUSINESS_VERIFICATION`
6. There are two possible outcomes from the registry lookup:
   * There is a match. In this case, the user must upload an accepted **Registration Proof**.
   * There is no match. In this case, the user must upload an accepted **Registration Proof** and **Articles of Association**, and the session is sent for manual review (`Status` will be `REVIEW`).
7. The session must then be opened by the registered director who will complete the liveness check (the session autosaves progress)
8. The registered director completes the liveness ID check (via [QR code](/guides/users/verification/hosted#qr-code-on-desktop) or directly if session opened on a phone) by:
   * Taking a photo of their ID (or two photos if it’s a driver’s license or national ID card)
   * Taking a selfie of their face
9. The session is redirected to the `ReturnUrl`
10. Mangopay performs automated liveness validation checks:
    * `IDENTITY_DOCUMENT_VERIFICATION`
    * `IDV_AGE_CHECK`
11. If successful, Mangopay checks that the individual in the ID is listed in the registry (`BUSINESS_INSIGHTS_MATCH`).
    * If successful, the session’s status becomes `VALIDATED`
    * If unsuccessful, the session is reviewed manually (`REVIEW`) before the final outcome

## Checks performed

Currently, for Legal Business Users, the following checks are performed in the order listed:

| Type                             | Description                                                                                                                                                                                                                                                                                                                              |
| -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BUSINESS_VERIFICATION`          | Uses the business name and registration number (or tax number) entered by the user in the session to attempt a lookup in the national business registry.   If not successful, the user is asked to upload the **Articles of Association** in addition to the **Registration Proof** and the session status will necessarily be `REVIEW`. |
| `IDENTITY_DOCUMENT_VERIFICATION` | Verifies the authenticity of the identity document, the liveness of the selfie, and that the selfie matches the identity document photo.                                                                                                                                                                                                 |
| `IDV_AGE_CHECK`                  | Checks whether the individual on the identity document meets the minimum age requirement for Mangopay users (age 18).   Only performed if `IDENTITY_DOCUMENT_VERIFICATION` is successful.                                                                                                                                                |
| `BUSINESS_INSIGHTS_MATCH`        | Checks whether the name on the ID document matches one of the directors listed in the national registry.  Performed manually if `BUSINESS_VERIFICATION` is unsuccessful.                                                                                                                                                                 |

## Outcomes

For a Business user, the following outcomes are possible (from a `PENDING` status):

### Automated validation

The `Status` becomes `VALIDATED` if all automated checks performed were successful. This emits the `IDENTITY_VERIFICATION_VALIDATED` [webhook](#webhooks). In this case:

* The [verified data](#verified-data) is overwritten in the User object:
  * `LegalRepresentative.FirstName` (even if the fields previously referenced a different individual)
  * `LegalRepresentative.LastName`
  * `LegalRepresentative.Birthday`
  * `CompanyName`
  * `CompanyNumber`
* The User's `KYCLevel` becomes `REGULAR`

### Automated refusal

The `Status` becomes `REFUSED` if any of these checks fail:

* `IDENTITY_DOCUMENT_VERIFICATION`
* `IDV_AGE_CHECK`

This emits the `IDENTITY_VERIFICATION_FAILED` [webhook](#webhooks). In this case:

* You can retrieve more information in the IDV Session's:
  * `Checks.CheckStatus` - For which checks were `REFUSED`
  * `Checks.Reasons` – For the [refusal reasons](/guides/users/verification/hosted/refusals) (`Type` and preset `Value`)
* You need to generate a new session to retry (even if some of the checks were validated)

### Manual review

Provided the `IDENTITY_DOCUMENT_VERIFICATION` and `IDV_AGE_CHECK` are successful, the `Status` becomes `REVIEW` if either of the following checks fail:

* `BUSINESS_VERIFICATION`
* `BUSINESS_INSIGHTS_MATCH`

This emits the `IDENTITY_VERIFICATION_INCONCLUSIVE` [webhook](#webhooks). In this case:

* Mangopay reviews the session data and documents manually.
* The `Checks.CheckStatus` shows which checks were `REFUSED` and triggered the manual review
* Automatically validated checks are returned, including [verified data](#verified-data), but the User object data is only overwritten if the session is validated

### Validation after review

If the manual review is successful, the `Status` changes from `REVIEW` to `VALIDATED`. In this case:

* The [verified data](#verified-data) is overwritten in the User object:
  * `LegalRepresentative.FirstName` (even if the fields previously referenced a different individual)
  * `LegalRepresentative.LastName`
  * `LegalRepresentative.Birthday`
  * `Name`
  * `CompanyNumber`
* The User's `KYCLevel` becomes `REGULAR`

### Refusal after review

If the manual review is unsuccessful, then the status changes to `REFUSED`.

In this case:

* [Verified data](#verified-data) may be returned in the IDV Session but no action is taken with it
* You can retrieve more information in the IDV Session's:
  * `Checks.CheckStatus` - For which checks were `REFUSED`
  * `Checks.Reasons` – For the [refusal reasons](/guides/users/verification/hosted/refusals) – `Type` and, in the case of a manual review, a custom message in the `Value`
* You need to generate a new session to retry (even if some of the checks were validated)

## Testing

For general guidance on testing the hosted IDV experience in Sandbox, see [Testing](/guides/users/verification/hosted#testing).

For this flow, the simulation of checks performed retain their conditional logic: `BUSINESS_INSIGHTS_MATCH` is only performed if `BUSINESS_VERIFICATION` is validated.

To simulate a `REVIEW` session, validate the IDV checks except any of `BUSINESS_VERIFICATION` or `BUSINESS_INSIGHTS_MATCH`.

## Sequence diagram

The following diagram gives an overview of the integration flow:

```mermaid
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#FFFFFF',
      'primaryTextColor': '#2D0F37',
      'primaryBorderColor': '#2D0F37',
      'lineColor': '#2D0F37',
      'secondaryColor': '#FFFFFF',
      'tertiaryColor': '#FFFFFF',
      'fontSize': '32px',
      'fontFamily': 'Inter',
      'noteBorderColor': "#f3f2ff",
      'noteBkgColor': "#F3F2FF",
      'noteTextColor': '#2D0F37'
    }
  }
}%%
sequenceDiagram
    participant U as User
    participant P as Your platform
    participant M as Mangopay API
    P->>M: POST Create IDV Session
    M-->>P: HostedUrl, Status: PENDING
    P->>U: Redirect to HostedUrl
    rect rgb(243, 242, 255)
        Note over U: Hosted KYC/KYB experience
        U->>U: Enter business details, <br />declare PSCs, and upload KYB documents
        U->>U: Registered director performs <br />ID liveness check with smartphone
        U-->>M: Process data
    end
    U->>P: Redirect to ReturnUrl
    M-->>P: Webhook: IDV_VALIDATED / REVIEW / FAILED
    P->>M: GET View an IDV Session
    M-->>P: Return Status, Checks, and (verified) Data
    alt Status: VALIDATED
        P->>U: Success pathway
    else Status: REFUSED
        P->>U: Check reasons and retry
    end
```

```mermaid
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': "#090d0d",
      'primaryTextColor': "#FFFFFF",
      'primaryBorderColor': "#FFFFFF",
      'secondaryColor': "#090D0D",
      'lineColor': "#FFFFFF",
      'tertiaryColor': "#FFFFFF",
      'fontSize': '32px',
      'fontFamily': 'Inter',
      'noteBorderColor': "#4f4f6e",
      'noteBkgColor': "#4f4f6e",
      'noteTextColor': "#FFFFFF"
    }
  }
}%%
sequenceDiagram
    participant U as User
    participant P as Your platform
    participant M as Mangopay API
    P->>M: POST Create IDV Session
    M-->>P: HostedUrl, Status: PENDING
    P->>U: Redirect to HostedUrl
    rect rgb(64, 65, 89)
        Note over U: Hosted KYC/KYB experience
        U->>U: Enter business details, <br />declare PSCs, and upload KYB documents
        U->>U: Registered director performs <br />ID liveness check with smartphone
        U-->>M: Process data
    end
    U->>P: Redirect to ReturnUrl
    M-->>P: Webhook: IDV_VALIDATED / REVIEW / FAILED
    P->>M: GET View an IDV Session
    M-->>P: Return Status, Checks, and (verified) Data
    alt Status: VALIDATED
        P->>U: Success pathway
    else Status: REFUSED
        P->>U: Check reasons and retry
    end
```

## Integration flow

#### Initiate the hosted session

Call the [POST Create an IDV Session](/api-reference/idv-sessions/create-idv-session) endpoint with the `UserId` to initiate a hosted KYC/KYB verification session.

You must include a `ReturnUrl` to which the session redirects once it is completed, before the outcome is known.

In the API response:

* The `HostedUrl` value is the URL for the unique session, with your `ReturnUrl` encoded and appended.
* The `Status` is `PENDING`, indicating that the session is available via the `HostedUrl` value, and the user has not successfully completed all the necessary steps.

The `PENDING` status emits the `IDENTITY_VERIFICATION_PENDING` webhook event type with the session `Id` (read more about [setting up webhooks](/webhooks)).

#### Redirect the user to the hosted session

Redirect the user to the `HostedUrl` value received in the response.

By default, the session can be submitted within 7 days, after which the `Status` changes to `EXPIRED`. If the liveness step has been opened (the QR code was generated), the session instead expires 1 hour after it started.

The object `Status` remains `PENDING` regardless of whether the session has been started or not. On your side you can track whether the `HostedUrl` was accessed by the user.

#### Let the user complete the session

On the `HostedUrl`, the experience guides the user through entering business details, declaring PSCs, uploading KYB documents, and having the registered director complete the ID liveness check using their smartphone (on the same session link). If the session is opened on desktop then a QR code is displayed for the user to scan.

#### Receive the user after completion

Once the session is completed, the `HostedUrl` redirects to the `ReturnUrl`.

The outcome of the session is not returned immediately.

#### Listen to webhooks

When the outcome of the session is known, the `Status` is updated from `PENDING` and a [webhook notification](/webhooks) is emitted.

The `PENDING` value can change directly to one of:

| `Status`    | Webhook event type                | Description                                                                                                     |
| :---------- | :-------------------------------- | :-------------------------------------------------------------------------------------------------------------- |
| `VALIDATED` | `IDENTITY_VERIFICATION_VALIDATED` | The User became KYC/KYB verified: `KYCLevel` changed to `REGULAR` and verified data updated in the User object. |
| `REFUSED`   | `IDENTITY_VERIFICATION_FAILED`    | User was not KYC/KYB verified and a new session must be created for them to retry.                              |

Or, the session may first pass to a temporary state before the final outcome:

| `Status` | Webhook event type                   | Description                                             |
| :------- | :----------------------------------- | :------------------------------------------------------ |
| `REVIEW` | `IDENTITY_VERIFICATION_INCONCLUSIVE` | The session is under manual review by Mangopay’s teams. |

#### Handle outcomes

Once you receive a webhook, call [GET View an IDV Session](/api-reference/idv-sessions/view-idv-session) for more details about the session.

In a successful case, this endpoint returns the verified data points that are updated in the User object.

For `REFUSED` cases, the endpoint returns information about which `Checks` failed and for what reasons.

To see key details about all the sessions attempted for a user, call [GET List IDV Session for a User](/api-reference/idv-sessions/list-idv-sessions-user).

## State machine

The following diagram shows the statuses of the [IDV Session](/api-reference/idv-sessions/idv-session-object) object for this flow:

```mermaid
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': '#FFFFFF',
      'primaryTextColor': '#2D0F37',
      'primaryBorderColor': '#2D0F37',
      'lineColor': '#2D0F37',
      'secondaryColor': '#FFFFFF',
      'tertiaryColor': '#FFFFFF',
      'fontSize': '32px',
      'fontFamily': 'Inter'
    }
  }
}%%
flowchart LR
    Start(["POST&nbsp;Create&nbsp;IDV&nbsp;Session"]) ==> PENDING
    PENDING == All automated checks pass ==> VALIDATED
    PENDING == Ambiguous result ==> REVIEW
    REVIEW == Manual review fails ==> REFUSED
    REVIEW == Manual review passes ==> VALIDATED
    PENDING ==> REFUSED
    VALIDATED == Downgrade / renewal ==> OUT_OF_DATE
    style Start stroke-width:3.5px
    style PENDING stroke-width:3.5px
    style REVIEW stroke-width:3.5px
    style VALIDATED stroke-width:3.5px
    style REFUSED stroke-width:3.5px
    style OUT_OF_DATE stroke-width:3.5px
```

```mermaid
%%{
  init: {
    'theme': 'base',
    'themeVariables': {
      'primaryColor': "#090D0D",
      'primaryTextColor': "#FFFFFF",
      'primaryBorderColor': "#FFFFFF",
      'lineColor': "#FFFFFF",
      'secondaryColor': "#090D0D",
      'tertiaryColor': "#090D0D",
      'fontSize': '32px',
      'fontFamily': 'Inter'
    }
  }
}%%
flowchart LR
    Start(["POST&nbsp;Create&nbsp;IDV&nbsp;Session"]) ==> PENDING
    PENDING == All automated checks pass ==> VALIDATED
    PENDING == Ambiguous result ==> REVIEW
    REVIEW == Manual review fails ==> REFUSED
    REVIEW == Manual review passes ==> VALIDATED
    PENDING ==> REFUSED
    VALIDATED == Downgrade / renewal ==> OUT_OF_DATE
    style Start stroke-width:3.5px
    style PENDING stroke-width:3.5px
    style REVIEW stroke-width:3.5px
    style VALIDATED stroke-width:3.5px
    style REFUSED stroke-width:3.5px
    style OUT_OF_DATE stroke-width:3.5px
```

## Webhooks

The hosted KYC/KYB verification feature takes time for the user to complete.

You are strongly recommended to implement webhooks for IDV Sessions and rely on them in your integration.

Once you receive a [webhook notification](/webhooks), call [GET View an IDV Session](/api-reference/idv-sessions/view-idv-session) for more details.

The following [event types](/webhooks/event-types) are available for this flow:

* `IDENTITY_VERIFICATION_PENDING` – The IDV Session’s `Status` is `PENDING`. The `HostedUrl` link is valid for completion and must be submitted within 7 days (or 1 hour after the liveness step is opened). The session may or may not have been started.
* `IDENTITY_VERIFICATION_VALIDATED` – The IDV Session’s `Status` changed to `VALIDATED` and the User became KYC/KYB verified.
* `IDENTITY_VERIFICATION_FAILED` – The IDV Session’s `Status` changed to `REFUSED` and the User was not KYC/KYB verified. A new session is needed for them to retry.
* `IDENTITY_VERIFICATION_INCONCLUSIVE` – The IDV Session’s `Status` changed to `REVIEW` and the session is under manual review by Mangopay’s teams before an outcome can be given.
* `IDENTITY_VERIFICATION_EXPIRED` – The IDV Session’s `Status` changed to `EXPIRED`. A new session is needed to retry.
* `IDENTITY_VERIFICATION_OUTDATED` – The IDV Session’s `Status` changed to `OUT_OF_DATE` indicating that the user’s KYC/KYB verification status was [downgraded](/guides/users/verification/downgrade). To regain KYC/KYB verified status, the user must complete a new IDV Session successfully.

## Verified data

The hosted KYC/KYB session gathers user data which is then verified as part of the process. This data is returned in the session’s `Checks.Data`. You can retrieve it using the [GET View an IDV Session](/api-reference/idv-sessions/view-idv-session) endpoint.

These data points are overwritten if the session `Status` is `VALIDATED`, but the `Data` may still be returned if the status is `REFUSED` or `REVIEW`.

As part of the `IDENTITY_DOCUMENT_VERIFICATION` check, the data in the next table is extracted from the ID document. If this check fails, the session `Status` is `REFUSED` and no data is overwritten. Note that this data is overwritten even if the individual who completed the session’s ID check is not the one previously entered in the `LegalRepresentative` of the user object.

<table>
  <thead>
    <tr>
      <th class="header">
        `Data.Type`

         value extracted from ID
      </th>

      <th class="header">
        User object property overwritten if 

        `Status`

         is 

        `VALIDATED`
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">`LEGAL_REPRESENTATIVE_FIRST_NAME`</td>

      <td class="table-content">`LegalRepresentative.FirstName`</td>
    </tr>

    <tr>
      <td class="table-content">`LEGAL_REPRESENTATIVE_LAST_NAME`</td>

      <td class="table-content">`LegalRepresentative.LastName`</td>
    </tr>

    <tr>
      <td class="table-content">`LEGAL_REPRESENTATIVE_BIRTHDATE`</td>

      <td class="table-content">`LegalRepresentative.Birthday`</td>
    </tr>
  </tbody>
</table>

As part of the `BUSINESS_VERIFICATION` check, the data in the next table is entered by the user and then validated against the national registry. If this check fails, then the session goes for manual review. If the session `Status` is ultimately `VALIDATED`, then the data entered is considered validated and overwritten in the user object. If the session outcome is `REFUSED`, no data is overwritten.

<table>
  <thead>
    <tr>
      <th class="header">
        `Data.Type`

         value entered by user
      </th>

      <th class="header">
        User object property overwritten if 

        `Status`

         is 

        `VALIDATED`
      </th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td class="table-content">
        `COMPANY_NAME`
      </td>

      <td class="table-content">
        `Name`
      </td>
    </tr>

    <tr>
      <td class="table-content">
        `COMPANY_NUMBER`
      </td>

      <td class="table-content">
        `CompanyNumber`
      </td>
    </tr>
  </tbody>
</table>