Create a Purchase Order - Anvitra Atlas

A purchase order buys units of a mutual fund scheme for an investor. This guide covers LUMPSUM_PURCHASE. Placing an order is a two-part flow:

Create the order

POST /api/orders/v1/ — validated and persisted synchronously, then dispatched to the exchange in the background. Returns 202.

Pay for it

POST /api/payments/v1/ — reference one or more orders and a payment mode.

Prerequisites

The investor is status: REGISTERED (see Create an investor).
An investment account exists for the investor.
For mandate-funded payments, a REGISTERED mandate exists.

Supported order types

`order_type`	Status
`LUMPSUM_PURCHASE`	Live — covered here.
`REDEMPTION`	Live.
`SWITCH`	Live.
`SIP`, `XSIP`, `STP`, `SWP`, `SIP_TOPUP`	Not yet available — rejected with `400 VALIDATION_FAILED`.

Create the order

POST /api/orders/v1/
Authorization: Bearer <token>
Idempotency-Key: 7c3f1e6a-...
Content-Type: application/json

{
  "order_type": "LUMPSUM_PURCHASE",
  "investor_id": "I_SI_IND_000042",
  "investment_account_id": "A_RT_000001",
  "scheme_code": "128SDGP",
  "amount": 25000,
  "purchase_type": "FRESH",
  "bank_account_id": "bnk_9f21c8",
  "mandate_id": "mnd_4a1b2c",
  "euin": { "declaration": true, "euin": "E123456" },
  "client_ref": "ord-5521"
}

Response 202:

{
  "success": true,
  "data": {
    "id": "ord_1a2b3c4d",
    "status": "PENDING",
    "order_type": "LUMPSUM_PURCHASE",
    "client_ref": "ord-5521",
    "created_at": "2026-09-06T10:20:00Z"
  }
}

Fields

Field	Required	Format / values	Notes
`order_type`	yes	`LUMPSUM_PURCHASE`
`investor_id`	yes	friendly investor ID	Must be `REGISTERED`.
`investment_account_id`	yes	friendly account ID	Must belong to the investor.
`scheme_code`	yes	string	The exchange scheme code.
`amount`	yes	number	Purchase amount.
`purchase_type`	no	`FRESH` \| `ADDITIONAL`	Defaults to `FRESH`. `ADDITIONAL` requires `folio_no`.
`folio_no`	conditional	string	Required for `ADDITIONAL` purchases.
`bank_account_id`	no		Must belong to the investor if supplied.
`mandate_id`	no		If supplied, checked for usability against `amount` (see mandates).
`euin`	no	`{ declaration, euin }`	`euin` string is required when `declaration` is `true`.
`remarks`	no	string
`client_ref`	no	string	Your own reference.

Validation

Rejected synchronously before the 202:

Condition	Response
Unsupported `order_type`	`400 VALIDATION_FAILED`
Investor not found	`404 NOT_FOUND`
Investor not `REGISTERED`	`422 KYC_INCOMPLETE`
`investment_account_id` missing	`400 VALIDATION_FAILED` — “investment_account_id is required”
`investment_account_id` belongs to another investor	`400 VALIDATION_FAILED`
`bank_account_id` belongs to another investor	`400 VALIDATION_FAILED`
`euin.declaration` true but `euin.euin` empty	`400 VALIDATION_FAILED`
`mandate_id` not usable for `amount`	`422 MANDATE_NOT_ACTIVE` / `INSUFFICIENT_MANDATE_LIMIT`

Send an Idempotency-Key (UUID) on order creation. Replaying the same key + body returns the original response with Idempotency-Replayed: true; a different body with the same key is 409 IDEMPOTENCY_KEY_REUSED.

Order lifecycle

PENDING ──▶ SUBMITTED ──▶ ACCEPTED ──▶ ALLOTTED
   │            │            │
   └──▶ REJECTED └──▶ REJECTED └──▶ REJECTED / CANCELLED
                └──▶ FAILED

Status	Meaning
`PENDING`	Persisted; queued for dispatch.
`SUBMITTED`	Sent to the exchange.
`ACCEPTED`	Exchange accepted the order.
`ALLOTTED`	Units allotted; `nav`, `units`, `allotment_date` populated (set by a status-sync job).
`REJECTED`	Exchange rejected it on business grounds; reason in `provider_remark`.
`FAILED`	Transport failure reaching the exchange; safe to investigate/retry.
`CANCELLED`	Cancelled via the cancel endpoint.

Track progress

Poll GET /api/orders/v1/:id:

{
  "success": true,
  "data": {
    "id": "ord_1a2b3c4d",
    "order_type": "LUMPSUM_PURCHASE",
    "status": "ALLOTTED",
    "payment_status": "CAPTURED",
    "investor_id": "I_SI_IND_000042",
    "investment_account_id": "A_RT_000001",
    "scheme_code": "128SDGP",
    "amount": 25000,
    "units": 412.339,
    "nav": 60.63,
    "allotment_date": "2026-09-09",
    "provider_order_id": "8812345",
    "client_ref": "ord-5521",
    "created_at": "2026-09-06T10:20:00Z",
    "updated_at": "2026-09-09T21:30:00Z"
  }
}

GET /api/orders/v1/:id/events returns the full transition trail ({ from, to, at, remark }). Or listen for webhook events order.accepted, order.rejected, order.failed.

Cancel an order

POST /api/orders/v1/:id/cancel
{ "reason": "customer changed their mind" }

Allowed only from PENDING, SUBMITTED or ACCEPTED — otherwise 409 INVALID_STATE.

Pay for the order

POST /api/payments/v1/
Authorization: Bearer <token>
Content-Type: application/json

{
  "investor_id": "I_SI_IND_000042",
  "investment_account_id": "A_RT_000001",
  "order_ids": ["ord_1a2b3c4d"],
  "mode": "MANDATE",
  "mandate_id": "mnd_4a1b2c"
}

Response 201:

{
  "success": true,
  "data": {
    "id": "pay_77a1b2",
    "status": "INITIATED",
    "amount": 25000,
    "payment_url": "",
    "basket_id": "NSE-BASKET-9931"
  }
}

Payment fields

Field	Required	Notes
`investor_id`	yes
`investment_account_id`	no	If set, every linked order must belong to it.
`order_ids`	yes	1–50 order IDs, same investor, purchase / XSIP only, sharing one investment account.
`mode`	yes	`MANDATE` \| `CHEQUE` \| `UPI` \| `NETBANKING` \| `NEFT_RTGS`.
`mandate_id`	conditional	Required for `MANDATE`.
`bank_account_id`	conditional	Required for `CHEQUE`, `UPI`, `NETBANKING`.
`vpa`	conditional	Required for `UPI`, `name@bank` form.
`cheque`	conditional	`{ number, date }` for `CHEQUE`; date within T-90 … T+3 days.
`utr`	conditional	Required for `NEFT_RTGS` (or submit later — see below).

How each mode settles

Mode	Investor action
`MANDATE`	None — the debit is auto-initiated against the registered mandate.
`UPI` / `NETBANKING`	The response carries `payment_url` — hand it to the investor to complete payment on the hosted page.
`CHEQUE`	Physical cheque details are registered; funds clear out-of-band.
`NEFT_RTGS`	The investor transfers funds out-of-band; you post the UTR.

Payment status

INITIATED → CAPTURED (success) / FAILED / REFUNDED. Completion arrives asynchronously via an exchange callback, which emits webhook events payment.captured, payment.failed, payment.refunded. Each linked order’s payment_status is updated in step.

Submit a UTR

POST /api/payments/v1/:id/utr
{ "utr": "AXISN02026090612345", "transfer_date": "2026-09-06" }

Read endpoints

GET /api/payments/v1/:id
GET /api/payments/v1?investor_id=&status=

Redemption and switch (brief)

Both use the same POST /api/orders/v1/ endpoint:

Redemption — order_type: "REDEMPTION", plus units or all_units: true (demat), or folio_no for physical holdings. No payment step — proceeds are credited to the registered bank account.
Switch — order_type: "SWITCH" with switch: { "to_scheme_code": "..." }.

​Prerequisites

​Supported order types

​Create the order

​Fields

​Validation

​Order lifecycle

​Track progress

​Cancel an order

​Pay for the order

​Payment fields

​How each mode settles

​Payment status

​Submit a UTR

​Read endpoints

​Redemption and switch (brief)

Prerequisites

Supported order types

Create the order

Fields

Validation

Order lifecycle

Track progress

Cancel an order

Pay for the order

Payment fields

How each mode settles

Payment status

Submit a UTR

Read endpoints

Redemption and switch (brief)