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

# Process Flows

> How investor registration, order dispatch, payment settlement and mandate registration move through MF Atlas and the exchange.

MF Atlas sits between your application and a transaction backend (currently
NSE). Most write operations are **accepted synchronously and completed
asynchronously** — the API returns quickly, work continues with the exchange in
the background, and the outcome reaches you by polling or webhook. These
diagrams show the moving parts.

## End-to-end onboarding

The happy path from credentials to allotted units.

```mermaid theme={null}
flowchart TD
    A[Get client_id / client_secret] --> B[Exchange for bearer token]
    B --> C[Create investor]
    C --> D{status REGISTERED?}
    D -- no --> C
    D -- yes --> E[Create investment account]
    E --> F[Register mandate - optional]
    F --> G[Create order]
    G --> H[Create payment]
    H --> I[Order ALLOTTED]
```

## Investor & UCC registration

`POST /api/investors/v1/` returns `201 PENDING` immediately. Atlas then
registers the Unique Client Code (UCC) with the exchange and, if a `fatca`
block was supplied, submits it right after — a FATCA failure is recorded but
does not block `REGISTERED`.

```mermaid theme={null}
sequenceDiagram
    participant You
    participant Atlas
    participant Exchange
    You->>Atlas: POST /api/investors/v1/
    Atlas-->>You: 201 status PENDING
    Atlas->>Exchange: Register UCC
    Exchange-->>Atlas: UCC accepted (client_code)
    opt fatca supplied
        Atlas->>Exchange: Submit FATCA
        Exchange-->>Atlas: FATCA accepted / failed (non-blocking)
    end
    Note over Atlas: status REGISTERED
    Atlas-->>You: webhook investor.registered / investor.rejected
```

See [Create an investor](/api-documentation/create-investor) for the field
reference and the `provider_steps` trail.

## Order dispatch & lifecycle

`POST /api/orders/v1/` validates and persists synchronously (`202 PENDING`),
then a background worker dispatches to the exchange. A status-sync job later
moves accepted orders to `ALLOTTED` and fills in `nav`, `units` and
`allotment_date`.

```mermaid theme={null}
sequenceDiagram
    participant You
    participant Atlas
    participant Exchange
    You->>Atlas: POST /api/orders/v1/
    Atlas-->>You: 202 status PENDING
    Atlas->>Exchange: Dispatch order
    Exchange-->>Atlas: Accepted (provider_order_id)
    Atlas-->>You: webhook order.accepted / order.rejected / order.failed
    loop status-sync job
        Atlas->>Exchange: Poll status
    end
    Exchange-->>Atlas: Allotted (nav, units, allotment_date)
```

```mermaid theme={null}
stateDiagram-v2
    [*] --> PENDING
    PENDING --> SUBMITTED
    PENDING --> REJECTED
    SUBMITTED --> ACCEPTED
    SUBMITTED --> REJECTED
    SUBMITTED --> FAILED
    ACCEPTED --> ALLOTTED
    ACCEPTED --> REJECTED
    ACCEPTED --> CANCELLED
    PENDING --> CANCELLED
    ALLOTTED --> [*]
```

See [Create a purchase order](/api-documentation/purchase-orders) for status
meanings and the cancel rules.

## Payment & settlement cycle

A payment references one or more orders and a `mode`. It starts `INITIATED`;
how the money moves depends on the mode. Completion arrives asynchronously via
an exchange callback, which updates each linked order's `payment_status`.

```mermaid theme={null}
sequenceDiagram
    participant You
    participant Atlas
    participant Exchange
    participant Bank
    You->>Atlas: POST /api/payments/v1/
    Atlas-->>You: 201 status INITIATED
    alt MANDATE
        Atlas->>Exchange: Trigger auto-debit
        Exchange->>Bank: Debit registered mandate
    else UPI / NETBANKING
        Atlas-->>You: payment_url (investor pays on hosted page)
    else CHEQUE / NEFT_RTGS
        You->>Atlas: POST /:id/utr or cheque details
    end
    Bank-->>Exchange: Funds received at pay-in cut-off
    Exchange-->>Atlas: callback payment.captured / failed / refunded
    Note over Atlas: NAV applied, units allotted, order payment_status updated
```

<Note>
  The number of business days from pay-in to allotment (or from redemption to
  payout) is set by the scheme and its RTA, not by MF Atlas. The only date
  window Atlas enforces is cheque dates: T−90 … T+3 calendar days.
</Note>

## Mandate registration

```mermaid theme={null}
stateDiagram-v2
    [*] --> REGISTERED: ENACH accepted
    [*] --> PENDING: PHYSICAL, or ENACH awaiting bank
    [*] --> REJECTED: exchange declines
    PENDING --> REGISTERED: signed scan accepted / bank approves
    PENDING --> REJECTED: scan or bank rejects
    REGISTERED --> CANCELLED
    REGISTERED --> [*]
    REJECTED --> [*]
```

An `ENACH` mandate is usable as soon as it is `REGISTERED`; a `PHYSICAL`
mandate needs the signed scan uploaded first. See
[Create a mandate](/api-documentation/mandates) for the first-debit lead time
and the payment-time checks.