Create a Purchase Order

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: ACTIVE — registered and client-authorised (see Create an investor).
An investment account exists for the investor.
For mandate-funded payments, a REGISTERED mandate exists.
The target scheme_code allows the transaction type you’re placing — look it up via schemes and check purchase_allowed/redemption_allowed/switch_allowed first.

Supported order types

`order_type`	Status
`LUMPSUM_PURCHASE`	Live — covered here.
`REDEMPTION`	Live.
`SWITCH`	Live.
`SIP`	Live — see Start a SIP.
Any other value	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",
  "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"
  }
}

The 202 is returned the moment the order is validated and persisted; the exchange dispatch runs in the background and a status-sync job later fills in allotment details.

Fields

Field	Required	Format / values	Notes
`order_type`	yes	`LUMPSUM_PURCHASE`
`investment_account_id`	yes	friendly account ID	The investor is derived from this account (must be `ACTIVE`) — `investor_id` is not a separate field.
`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`. When omitted, falls back to the investor’s own `euin` (set at investor creation), then to your tenant’s default EUIN, if either is configured.
`remarks`	no	string
`client_ref`	no	string	Your own reference.

Validation

Rejected synchronously before the 202:

Condition	Response
Unsupported `order_type`	`400 VALIDATION_FAILED`
`investment_account_id` missing	`400 VALIDATION_FAILED` — “investment_account_id is required”
`investment_account_id` not found	`400 VALIDATION_FAILED`
Investor (derived from `investment_account_id`) not `ACTIVE`	`422 KYC_INCOMPLETE`
`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

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

status tracks the order at the exchange; payment_status tracks the money for it separately, and is also returned by the list endpoint (which accepts it as a filter):

`payment_status`	Meaning
`AWAITING`	No payment started yet (the initial value).
`INITIATED`	A payment was created for the order and is in progress.
`CAPTURED`	Funds received.
`FAILED`	The payment failed; create a new payment to retry.
`REFUNDED`	The payment was refunded.

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, order.allotted.

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

{
  "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
`investment_account_id`	no	If set, every linked order must belong to it.
`order_ids`	yes	1–50 order IDs, same investor (the investor is derived from these orders), lumpsum purchase orders only (a SIP is never paid through this endpoint), sharing one investment account, each already accepted by the exchange (`status` past `SUBMITTED`).
`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.

Allotment and redemption-payout timing (T+n) is set by the scheme and its RTA, not by Atlas. The one date rule Atlas enforces is cheque dates: they must fall within T−90 … T+3 calendar days.

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. Once settled, GET /api/payments/v1/:id also returns provider_ref (the exchange’s own settlement reference), payment_account_no, payment_datetime and settlement_number — a reconciliation pass fills these in even for a payment made through the exchange’s own hosted flow without ever calling POST /api/payments/v1 yourself.

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": "..." }.

Both follow the same PENDING → SUBMITTED → ACCEPTED → ALLOTTED lifecycle and emit the same order.allotted / order.rejected webhooks. ALLOTTED means “processed” for every order type:

Redemption — units, nav and allotment_date are the units actually redeemed and the NAV they were redeemed at.
Switch — the exchange books a switch-out and a switch-in. The order becomes ALLOTTED once the switch-in is allotted, and units/nav/ folio_no then describe the new holding in the target scheme. If either side is rejected, the order is REJECTED.

Public order confirmation link

Instead of placing an order directly, you can propose one and have the investor confirm and pay for it themselves — the same self-serve pattern as the public onboarding link for investors, generalized to orders.

Propose the order

POST /api/orders/v1/public-link with the same body POST /api/orders/v1/ takes, wrapped as { "proposal": { ... }, "secret_code": "1234" } (secret_code is an optional PIN). No order is created yet — only the proposal is stored. Response 201:

{ "success": true, "data": { "link_id": "8f3e2b1a-..." } }

Share https://<your-ui>/order-confirm?linkId=8f3e2b1a-... with the investor (and the PIN, out of band, if you set one).

Investor reviews and confirms

GET /api/public/v1/order-links/:link_id (header X-Draft-Secret: 1234 if a PIN was set) returns the proposal pre-confirm, or the live order once confirmed:

{
  "success": true,
  "data": {
    "link_id": "8f3e2b1a-...",
    "proposal": { "order_type": "SWITCH", "scheme_code": "FROM01", "switch": { "to_scheme_code": "TO01" }, "...": "..." },
    "confirmed": false,
    "scheme": { "scheme_code": "FROM01", "name": "Alpha Equity Fund", "amc_name": "Alpha AMC", "plan": "DIRECT", "option": "GROWTH", "category": "Equity" },
    "to_scheme": { "scheme_code": "TO01", "name": "Alpha Liquid Fund", "amc_name": "Alpha AMC", "plan": "DIRECT", "option": "GROWTH", "category": "Debt" }
  }
}

scheme is proposal.scheme_code resolved against the scheme master — the fund being bought, redeemed or (for a SWITCH) switched out of — and to_scheme is the SWITCH target (proposal.switch.to_scheme_code), so your confirmation page can show fund names rather than bare codes. Both are best-effort and omitted when the code isn’t in the master. A REDEMPTION or SWITCH link collects no payment from the investor — word your page accordingly (the payment_link it later surfaces is an exchange authorization page, not a payment page).401 means the PIN is required or wrong; 410 GONE means the link has expired (order/mandate links expire after 7 days — unlike the investor onboarding link, which never expires).POST /api/public/v1/order-links/:link_id/confirm then runs the exact same validated create-and-dispatch flow as the authenticated POST /api/orders/v1/ and returns the same OrderData shape. A second confirm on the same link is 409 ALREADY_CONFIRMED.

Investor pays once accepted

Poll the same GET .../order-links/:link_id — once the exchange has accepted the order, the response adds "order": { ...OrderFullData } and "payment_ready": true. order.payment_link, once populated, is an additional NSE-hosted payment page (the same link NSE already auto-emails/SMSes the investor after order registration) — an alternative you can redirect the investor to directly, without ever calling our own /pay endpoint. It’s best-effort and may take a moment to populate after payment_ready first turns true; whether completing payment there alone also produces a settlement observable through this API is not yet confirmed, so keep polling regardless of which path the investor takes.Alternatively, for programmatic control over payment mode, the investor (or your own backend) can pick a mode and call POST /api/public/v1/order-links/:link_id/pay with the same body shape POST /api/payments/v1/ takes (minus investor_id/order_ids, which are derived from the link, never accepted from the public caller):

{ "mode": "UPI", "vpa": "investor@bank" }

Response is the normal PaymentData — for UPI/NETBANKING, redirect the investor to payment_url to complete settlement. This remains the only path this backend can confirm creates a Payment record.

Atlas

API Guide

API Reference

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)

Public order confirmation link

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

​Public order confirmation link

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)

Public order confirmation link