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

# Organization - Legacy single-session flow

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

This page describes the previous hosted IDV flow for the Organization 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 an Organization, 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 will need to upload conforms to the one [expected by Mangopay](/guides/users/verification/requirements/kyb-local)
* They have registration details about their organization
* 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 Organization:

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 details of their entity
   * That they will 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 details of their entity:
   * Country of registration
   * Optionally, registration number provided by the relevant national authority
   * Registered organization name
   * Registered organization address
4. The session must then be opened by the registered director who will complete the liveness check (the session autosaves progress)
5. 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
6. The session is redirected to the `ReturnUrl`
7. Mangopay performs automated liveness validation checks:
   * `IDENTITY_DOCUMENT_VERIFICATION`
   * `IDV_AGE_CHECK`

## Checks performed

Currently, for Legal Organization users, the following checks are performed:

| Type                             | Description                                                                                                                                                                               |
| :------------------------------- | :---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `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. |

## Outcomes

For a Organization user, the IDV Session can be refused automatically but otherwise is always reviewed manually. The following outcomes are possible (from a `PENDING` status):

### 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`. This emits the `IDENTITY_VERIFICATION_INCONCLUSIVE` [webhook](#webhooks).

In this case:

* Mangopay reviews the session data and documents manually.
* 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 an Organization user, the simulation of checks performed retain their conditional logic: `IDV_AGE_CHECK` is only performed if `IDENTITY_DOCUMENT_VERIFICATION` is validated.

## 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 entity details <br />and upload KYB documents
        U->>U: Perform ID liveness <br />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 entity details <br />and upload KYB documents
        U->>U: Perform ID liveness <br />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 entity details, uploading KYB documents, and having the registered director complete the ID liveness check using their smartphone. 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 an Organization user:

```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 ==> 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 ==> 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 an Organization:

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

<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>