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

# Create a Mandate

> Register a bank auto-debit authorization so purchases can be funded without per-transaction approval.

A **mandate** authorizes the exchange to debit an investor's bank account up
to a ceiling amount. Once registered and active, it can fund purchase
payments without the investor approving each debit.

## Endpoint

```http theme={null}
POST /api/mandates/v1/
Authorization: Bearer <token>
Content-Type: application/json
```

```json theme={null}
{
  "investor_id": "I_SI_IND_000042",
  "investment_account_id": "A_RT_000001",
  "type": "ENACH",
  "amount": 100000,
  "bank_account_id": "bnk_9f21c8",
  "start_date": "2026-09-10",
  "end_date": "2029-09-10",
  "client_ref": "mnd-77"
}
```

Response `201`:

```json theme={null}
{
  "success": true,
  "data": {
    "id": "mnd_4a1b2c",
    "provider_mandate_id": "2024030710018",
    "status": "REGISTERED",
    "umrn": null,
    "remark": ""
  }
}
```

## Fields

| Field                   | Required    | Format / values              | Notes                                                                                              |
| ----------------------- | ----------- | ---------------------------- | -------------------------------------------------------------------------------------------------- |
| `investor_id`           | yes         | friendly investor ID         | Must exist in your account.                                                                        |
| `investment_account_id` | no          | friendly account ID          | If set, must belong to the same investor.                                                          |
| `type`                  | yes         | `ENACH` \| `PHYSICAL`        | `ENACH` = electronic (NACH/eNACH); `PHYSICAL` = signed paper form that you scan and upload.        |
| `amount`                | yes         | number > 0                   | The **maximum debit ceiling**, not an installment. A payment whose total exceeds this is rejected. |
| `bank_account_id`       | conditional |                              | Use this **or** the inline trio below. Must belong to the investor.                                |
| `account_no`            | conditional |                              | Inline alternative to `bank_account_id`.                                                           |
| `ifsc`                  | conditional |                              | Required with inline `account_no`.                                                                 |
| `account_type`          | conditional | `SB` \| `CB` \| `NE` \| `NO` | Required with inline `account_no`.                                                                 |
| `start_date`            | yes         | `YYYY-MM-DD`                 | Must not be before today.                                                                          |
| `end_date`              | yes         | `YYYY-MM-DD`                 | Must be strictly after `start_date`.                                                               |
| `client_ref`            | no          | string                       | Your own reference.                                                                                |

### Validation

Rejected synchronously with `400 VALIDATION_FAILED`:

* `start_date` unparseable or in the past.
* `end_date` unparseable or not after `start_date`.
* `type` not `ENACH` or `PHYSICAL`.
* `amount` not greater than 0.
* Neither `bank_account_id` nor the full inline trio (`account_no` + `ifsc` +
  `account_type`) supplied.
* `investor_id` doesn't exist, or `investment_account_id` belongs to another
  investor.

## Status lifecycle

| `type`     | On create                                             | To become usable                                                        |
| ---------- | ----------------------------------------------------- | ----------------------------------------------------------------------- |
| `ENACH`    | `REGISTERED` (or `REJECTED` if the exchange declines) | Ready immediately once `REGISTERED`.                                    |
| `PHYSICAL` | `PENDING`                                             | Upload the signed scan (below); on acceptance it moves to `REGISTERED`. |

Observed status values: `PENDING`, `REGISTERED`, `REJECTED`, `CANCELLED`.

`GET /api/mandates/v1/:id` refreshes the status live from the exchange before
returning it, so polling this endpoint reflects the latest registration state.

## Upload a physical mandate scan

```http theme={null}
POST /api/mandates/v1/:id/image
Authorization: Bearer <token>
Content-Type: multipart/form-data
```

Form field `file` — the scanned, signed mandate form. Only valid for a
`PHYSICAL` mandate. On acceptance the mandate becomes `REGISTERED`; a rejection
returns `422 UCC_REJECTED`.

## Link a UMRN

```http theme={null}
POST /api/mandates/v1/:id/umrn
{ "umrn": "HDFC0000000012345678", "remark": "" }
```

Associates a bank-assigned Unique Mandate Reference Number with the mandate.

## Using a mandate for payment

When a payment references a mandate, two checks run at payment time:

| Condition                                  | Response                         |
| ------------------------------------------ | -------------------------------- |
| Mandate not `REGISTERED`                   | `422 MANDATE_NOT_ACTIVE`         |
| Payment total exceeds the mandate `amount` | `422 INSUFFICIENT_MANDATE_LIMIT` |
| Mandate belongs to another investor        | `400 VALIDATION_FAILED`          |

## Read endpoints

```http theme={null}
GET /api/mandates/v1/:id
GET /api/mandates/v1?investor_id=&status=&limit=&cursor=
```

## Next step

[Create a purchase order](/purchase-orders) and pay for it with this mandate.