> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wepayout.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Onboarding Documents Flow

> New onboarding flow that requests, via webhook, the documents required for the company segment and modality.

<Info>
  This flow is rolled out **per merchant** through a feature flag — **off by default**. It only applies when the company is created with a **segment** (see [Create Company](/api-reference/account/create) and [List Segments](/api-reference/account/segments/list-segments)).

  Merchants without the flag enabled continue on the [legacy onboarding flow](/api-reference/account/webhook/webhook-onboarding).

  For the full integration walkthrough, see [Onboarding Documents Integration](/account/onboarding-documents-flow).
</Info>

## Status Flow

When a company is created with a segment, it is moved to **`pending_documents`** and the onboarding webhook delivers the list of documents the client must send. Once **all required** documents are sent, the solicitation advances to `documents_under_review`.

After compliance approves every document, the flow **branches by modality** (derived from the company address country):

* **National** (address in Brazil): the solicitation moves to `waiting_signature` while the legal representatives sign the contract; once signed, the account is created and becomes `active`.
* **Cross-border** (address outside Brazil): the solicitation moves to `waiting_bank_channel`, then to `bank_channel_created` once the bank channel is opened, and finally to `active`. There is **no signature step** for cross-border.

A rejection sends the solicitation back to `pending_documents`, and a closed review moves it to `canceled`. This flow does **not** go through `due_diligence_review` (that step only exists in the legacy flow).

```mermaid theme={null}
graph LR
    A[pending] --> B[pending_documents]
    B --> C[documents_under_review]
    C -->|rejection| B
    C -->|close| E[canceled]
    C -->|national| S[waiting_signature]
    C -->|cross-border| K[waiting_bank_channel]
    S -->|signed| D[active]
    K --> L[bank_channel_created]
    L --> D[active]
    D --> F[inactive]
    D --> G[closed]

    style A fill:#fef3c7,stroke:#f59e0b,stroke-width:2px,color:#000
    style B fill:#ede9fe,stroke:#8b5cf6,stroke-width:2px,color:#000
    style C fill:#dbeafe,stroke:#3b82f6,stroke-width:2px,color:#000
    style S fill:#ffedd5,stroke:#f97316,stroke-width:2px,color:#000
    style K fill:#cffafe,stroke:#06b6d4,stroke-width:2px,color:#000
    style L fill:#ccfbf1,stroke:#14b8a6,stroke-width:2px,color:#000
    style D fill:#d1fae5,stroke:#10b981,stroke-width:2px,color:#000
    style E fill:#fee2e2,stroke:#ef4444,stroke-width:2px,color:#000
    style F fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#000
    style G fill:#f3f4f6,stroke:#6b7280,stroke-width:2px,color:#000
```

## Statuses

### `pending`

First status of the process. The account opening request has been received and is awaiting processing.

### `pending_documents`

The documents required for the company's **segment** and **modality** (national/crossborder) were resolved and attached to the onboarding request. The webhook for this status includes the list of `documents` the client must send (see [Webhook Payload](#webhook-payload)). The solicitation stays here until **all required** documents are sent; optional documents do not block the transition.

### `documents_under_review`

All required documents were sent and compliance is reviewing them. The webhook payload still includes the `documents` list, now carrying each document's review state. A rejection sends the solicitation back to `pending_documents` (preserving already-approved documents); once everything is approved the flow branches by modality (`waiting_signature` for national, `waiting_bank_channel` for cross-border).

### `waiting_signature`

**National only.** All documents were approved and the contract is awaiting signature by the legal representatives. Fetch the signing links with the [Get Signature Link](/api-reference/account/signature/signature-link) endpoint and route each representative to their `sign_url`. Once every signer has signed, the account is created and the solicitation moves to `active`. The webhook payload for this status does **not** include the `documents` array.

### `waiting_bank_channel`

**Cross-border only.** All documents were approved and the bank channel is being opened by WEpayments. The webhook payload for this status does **not** include the `documents` array.

### `bank_channel_created`

**Cross-border only.** The bank channel was created; the account is being finalized and will move to `active`. The webhook payload for this status does **not** include the `documents` array.

### `active`

Account is active/approved. At this status, the webhook sends the `account_id` (MID - Merchant ID) that identifies the merchant's account.

### `canceled`

Onboarding did not proceed (e.g. compliance closed the review). The webhook payload includes the `documents` list.

### `inactive`

Account is inactive after being previously activated.

### `closed`

Account has been closed.

## Webhook Payload

The payload always carries the solicitation `id`, its `status` and `updated_at`. The `documents` array is included while the solicitation is in `pending_documents`, `documents_under_review` or `canceled`:

```json theme={null}
{
  "id": "1234-5678-90ab-cdef-1234567890ab",
  "status": "pending_documents",
  "updated_at": "2024-01-15T10:30:00.000000Z",
  "account_id": null,
  "documents": [
    {
      "name": "Articles of Incorporation",
      "tag": "articles_of_incorporation",
      "description": "Company's current articles of incorporation",
      "required": true,
      "upload_status": "pending",
      "review_status": "pending"
    }
  ]
}
```

<ResponseField name="id" type="string">
  UUID of the solicitation.
</ResponseField>

<ResponseField name="status" type="string">
  Current status of the solicitation.
</ResponseField>

<ResponseField name="updated_at" type="string">
  Timestamp of the last status change (ISO 8601).
</ResponseField>

<ResponseField name="account_id" type="string | null">
  The merchant account identifier (MID). `null` until the account is created — populated when `status` is `active`.
</ResponseField>

<ResponseField name="documents" type="array">
  List of documents required for the company, resolved from its segment and modality. Present when `status` is `pending_documents`, `documents_under_review` or `canceled`.

  <Expandable title="document object">
    <ResponseField name="name" type="string">
      Human-readable name of the document.
    </ResponseField>

    <ResponseField name="tag" type="string">
      Machine-readable identifier of the document type — the value used to upload it.
    </ResponseField>

    <ResponseField name="description" type="string">
      Description of what the document is.
    </ResponseField>

    <ResponseField name="required" type="boolean">
      Whether the document is mandatory for the onboarding to proceed.
    </ResponseField>

    <ResponseField name="upload_status" type="string">
      Upload state, owned by the client. One of `pending`, `sent`.
    </ResponseField>

    <ResponseField name="review_status" type="string">
      Compliance review state. One of `pending`, `approved`, `rejected`.
    </ResponseField>

    <ResponseField name="reason" type="string">
      Reason for the rejection. Present only when `review_status` is `rejected`.
    </ResponseField>
  </Expandable>
</ResponseField>

<Note>
  **When is it fired?** A webhook is dispatched on every status change, on every document upload, and on every compliance decision — so expect multiple deliveries per solicitation. Reconcile by `id` + `status` and the per-document state, and keep your handler idempotent.
</Note>

<Note>
  **Delivery & retries:** your webhook endpoint must return a `200 OK` status code to acknowledge receipt. If it fails or returns an error, delivery is retried **up to 3 times, every 15 minutes**.
</Note>

<Note>
  To receive onboarding status updates via webhook, register them using the [Webhook Setup](/api-reference/account/webhook/webhook-setup) endpoint.
</Note>