MF Purchase Object

Mutual fund purchase orders and transactions

Overview

The MF Purchase object represents a mutual fund purchase transaction within the Fintech Primitives platform. This object captures all essential information about an investor's purchase order, from initiation through completion, including amount details, scheme information, processing states, and associated metadata.

This object is central to the mutual fund investment workflow and integrates with various other objects like Investment Accounts, Folios, and Purchase Plans to provide a comprehensive transaction management system.

Attribute	Type	Comments
`object`	`string`	Value is mf_purchase. String representing the object type. Objects of the same type share the same value
`id`	`string`	Unique identifier of the mf_purchase object
`old_id`	`integer`	This is the Numeric ID of the purchase object, We have provided this as some of our APIs use this ID like in Payments
`mf_investment_account`	`string`	This is the ID of the investment account object, and you can identify the investment account associated with the purchase order using this id
`folio_number`	`string`	This value represents the folio number in which the investor has made the purchase. In case of fresh purchases, the folio number will be available only when the order becomes successful.
`state`	`string`	State of the purchase order. Possible values: under_review(Applicable only for ondc gateway), pending, confirmed, submitted, successful, failed, cancelled, reversed
`amount`	`decimal`	Purchase amount in INR
`allotted_units`	`decimal`	Number of units allotted for this purchase transaction. For example, the user might have placed a purchase order for Rs. 500 at a NAV of Rs. 296.0196. A stamp duty at 0.005% of Rs. 500 = 0.03(0.025 rounded up to 0.03) might get applied and the actual investment amount would be 500 - 0.03 = Rs. 499.97. Units allotted = 499.97/296.0196 = 1.68897600024 = 1.689 (Rounded up to 3 decimal points). The value will be available only after the order is submitted to the order gateway and is successfully processed
`purchased_amount`	`decimal`	The actual purchase amount. For example, the user might have placed a purchase order for Rs. 500 at a NAV of Rs. 296.0196. A stamp duty at 0.005% of Rs. 500 = 0.03(0.025 rounded up to 0.03) might get applied and the actual investment amount would be 500 - 0.03 = Rs. 499.97. The value will be available only after the order is submitted to the order gateway and is successfully processed.
`purchased_price`	`decimal`	NAV at which the trade happened
`scheme`	`string`	ISIN of the scheme in which the investment was made
`type`	`string`	This value indicates whether this purchase order is a fresh purchase or an additional purchase in an existing folio. Possible values: purchase, additional_purchase
`plan`	`string`	The object id of the plan with which this purchase is associated. This value will be available only if this purchase order is created by a plan
`scheduled_on`	`string`	The date on which the order is scheduled for submission to the order gateway for processing. In case the order is in confirmed state before the scheduled_on date, the order will be sent to the gateway on the date the order is confirmed
`traded_on`	`string`	The date on which the trade happened. Please note that the trade will happen after the order is submitted to the order gateway
`created_at`	`string`	The time at which the order was created
`confirmed_at`	`string`	The time at which the order was confirmed
`submitted_at`	`string`	The time at which the order was submitted to the order gateway
`succeeded_at`	`string`	The time at which the order was processed successfully
`failed_at`	`string`	The time at which the order was failed
`retried_at`	`string`	The time at which the order was last retried
`reversed_at`	`string`	The time at which the order was reversed
`cancelled_at`	`string`	The time at which the order was cancelled
`gateway`	`string`	The gateway through which the order was submitted for processing. Possible values: rta and ondc(Early access)
`source_ref_id`	`string`	An identifier that is unique across orders of all types(purchases, redemptions, and switch). This is not generated by FP and is populated by API consumers for identification purposes. (ideally an auto generated identifier / uuid to identify the order in your application)
`user_ip`	`string`	IP address of the end user who has initiated the transaction. This should be in IPv4 format. Eg., n.n.n.n where n can have a value between 0 - 255
`server_ip`	`string`	IP address of server through which the request to create this transaction was made.
`euin`	`string`	Unique identity number of the employee / relationship manager/ sales person of the distributor who has advised or interacted with the investor in any other manner for this purchase order.
`partner`	`string`	ID of the partner via which this order is created if any. Note: Sub-broker transactions are yet to be suported via ondc gateway.
`failure_code`	`string`	Failure code of the failed purchase order. Possible values: payment_failure,order_expiry,order_failure_at_gateway and others
`initiated_by`	`string`	The entity/person who has initiated this purchase. Possible values: investor, distributor
`initiated_via`	`string`	The medium via which this transaction was initiated. Possible values: mobile_app, mobile_app_android, mobile_app_ios, mobile_web_android, mobile_web_ios, mobile_web, web

{
  "object": "mf_purchase",
  "id": "mfp_177177219f634373b01072986d2eea7d",
  "old_id": 9123,
  "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
  "folio_number": "31171511",
  "state": "pending",
  "amount": 10000.0,
  "scheme": "INF173K01FE6",
  "gateway": "rta",
  "traded_on": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-06T15:32:52+05:30",
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "failed_at": null,
  "retried_at": null,
  "cancelled_at": null,
  "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "plan": null,
  "initiated_by": "investor",
  "initiated_via": "web",
  "euin": null,
  "partner": "ptnr_20751c37c0a548c3baf12a18bc72187b",
  "failure_code": null,
  "type": "additional_purchase",
  "allotted_units": null,
  "purchased_amount": null,
  "purchased_price": null,
  "confirmed_at": null
}

POST Create a MF Purchase

POST /v2/mf_purchases

Creates a new mutual fund purchase order.

curl -X POST "https://api.fintechprimitives.com/v2/mf_purchases" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-tenant-id: your_tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "investor_id": "inv_1234567890abcdef",
    "amount": 10000,
    "scheme": "INF173K01FE6",
    "payment_method": "netbanking"
  }'

const response = await fetch('https://api.fintechprimitives.com/v2/mf_purchases', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    investor_id: 'inv_1234567890abcdef',
    amount: 10000,
    scheme: 'INF173K01FE6',
    payment_method: 'netbanking'
  })
});

const purchase = await response.json();

import requests

response = requests.post(
  'https://api.fintechprimitives.com/v2/mf_purchases',
  headers={
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  },
  json={
    'investor_id': 'inv_1234567890abcdef',
    'amount': 10000,
    'scheme': 'INF173K01FE6',
    'payment_method': 'netbanking'
  }
)

purchase = response.json()

POST Create batch purchase orders

POST /v2/mf_purchases/batch

Creates multiple mutual fund purchase orders in a single request.

curl -X POST "https://api.fintechprimitives.com/v2/mf_purchases/batch" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-tenant-id: your_tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "purchases": [
      {
        "investor_id": "inv_1234567890abcdef",
        "amount": 10000,
        "scheme": "INF173K01FE6"
      },
      {
        "investor_id": "inv_abcdef1234567890",
        "amount": 15000,
        "scheme": "INF173K01FE7"
      }
    ]
  }'

const response = await fetch('https://api.fintechprimitives.com/v2/mf_purchases/batch', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    purchases: [
      {
        investor_id: 'inv_1234567890abcdef',
        amount: 10000,
        scheme: 'INF173K01FE6'
      },
      {
        investor_id: 'inv_abcdef1234567890',
        amount: 15000,
        scheme: 'INF173K01FE7'
      }
    ]
  })
});

const batchPurchases = await response.json();

import requests

response = requests.post(
  'https://api.fintechprimitives.com/v2/mf_purchases/batch',
  headers={
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  },
  json={
    'purchases': [
      {
        'investor_id': 'inv_1234567890abcdef',
        'amount': 10000,
        'scheme': 'INF173K01FE6'
      },
      {
        'investor_id': 'inv_abcdef1234567890',
        'amount': 15000,
        'scheme': 'INF173K01FE7'
      }
    ]
  }
)

batch_purchases = response.json()

POST Create a MF Purchase Plan Installment

POST /v2/mf_purchases

Creates a purchase order as part of a systematic investment plan (SIP).

curl -X POST "https://api.fintechprimitives.com/v2/mf_purchases" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-tenant-id: your_tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "investor_id": "inv_1234567890abcdef",
    "amount": 5000,
    "scheme": "INF173K01FE6",
    "plan_id": "plan_abcdef1234567890",
    "installment_number": 3
  }'

const response = await fetch('https://api.fintechprimitives.com/v2/mf_purchases', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    investor_id: 'inv_1234567890abcdef',
    amount: 5000,
    scheme: 'INF173K01FE6',
    plan_id: 'plan_abcdef1234567890',
    installment_number: 3
  })
});

const planPurchase = await response.json();

import requests

response = requests.post(
  'https://api.fintechprimitives.com/v2/mf_purchases',
  headers={
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  },
  json={
    'investor_id': 'inv_1234567890abcdef',
    'amount': 5000,
    'scheme': 'INF173K01FE6',
    'plan_id': 'plan_abcdef1234567890',
    'installment_number': 3
  }
)

plan_purchase = response.json()

PATCH Update a MF Purchase

PATCH /v2/mf_purchases/:id

Updates an existing mutual fund purchase order.

curl -X PATCH "https://api.fintechprimitives.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-tenant-id: your_tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 12000,
    "scheduled_on": "2024-04-10"
  }'

const response = await fetch('https://api.fintechprimitives.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    amount: 12000,
    scheduled_on: '2024-04-10'
  })
});

const updatedPurchase = await response.json();

import requests

response = requests.patch(
  'https://api.fintechprimitives.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d',
  headers={
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  },
  json={
    'amount': 12000,
    'scheduled_on': '2024-04-10'
  }
)

updated_purchase = response.json()

PATCH Update batch purchase orders

PATCH /v2/mf_purchases/batch

Updates multiple mutual fund purchase orders in a single request.

curl -X PATCH "https://api.fintechprimitives.com/v2/mf_purchases/batch" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-tenant-id: your_tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "updates": [
      {
        "id": "mfp_177177219f634373b01072986d2eea7d",
        "amount": 12000
      },
      {
        "id": "mfp_abcdef1234567890123456789abcdef",
        "scheduled_on": "2024-04-15"
      }
    ]
  }'

const response = await fetch('https://api.fintechprimitives.com/v2/mf_purchases/batch', {
  method: 'PATCH',
  headers: {
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    updates: [
      {
        id: 'mfp_177177219f634373b01072986d2eea7d',
        amount: 12000
      },
      {
        id: 'mfp_abcdef1234567890123456789abcdef',
        scheduled_on: '2024-04-15'
      }
    ]
  })
});

const batchUpdates = await response.json();

import requests

response = requests.patch(
  'https://api.fintechprimitives.com/v2/mf_purchases/batch',
  headers={
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  },
  json={
    'updates': [
      {
        'id': 'mfp_177177219f634373b01072986d2eea7d',
        'amount': 12000
      },
      {
        'id': 'mfp_abcdef1234567890123456789abcdef',
        'scheduled_on': '2024-04-15'
      }
    ]
  }
)

batch_updates = response.json()

GET Fetch a MF Purchase

GET /v2/mf_purchases/:id

Retrieves a specific mutual fund purchase order by its ID.

curl -X GET "https://api.fintechprimitives.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-tenant-id: your_tenant"

const response = await fetch('https://api.fintechprimitives.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant'
  }
});

const purchase = await response.json();

import requests

response = requests.get(
  'https://api.fintechprimitives.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d',
  headers={
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant'
  }
)

purchase = response.json()

GET List all MF Purchases

GET /v2/mf_purchases

Retrieves a list of all mutual fund purchase orders.

curl -X GET "https://api.fintechprimitives.com/v2/mf_purchases?limit=10&offset=0" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-tenant-id: your_tenant"

const response = await fetch('https://api.fintechprimitives.com/v2/mf_purchases?limit=10&offset=0', {
  method: 'GET',
  headers: {
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant'
  }
});

const purchasesList = await response.json();

import requests

response = requests.get(
  'https://api.fintechprimitives.com/v2/mf_purchases',
  headers={
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant'
  },
  params={
    'limit': 10,
    'offset': 0
  }
)

purchases_list = response.json()

POST Retry MF Purchase

POST /v2/mf_purchases/:id/retry

Retries a failed mutual fund purchase order.

curl -X POST "https://api.fintechprimitives.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d/retry" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-tenant-id: your_tenant" \
  -H "Content-Type: application/json"

const response = await fetch('https://api.fintechprimitives.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d/retry', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  }
});

const retryResult = await response.json();

import requests

response = requests.post(
  'https://api.fintechprimitives.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d/retry',
  headers={
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  }
)

retry_result = response.json()

POST Cancel MF Purchase

POST /v2/mf_purchases/:id/cancel

Cancels a pending mutual fund purchase order.

curl -X POST "https://api.fintechprimitives.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d/cancel" \
  -H "Authorization: Bearer ACCESS_TOKEN" \
  -H "x-tenant-id: your_tenant" \
  -H "Content-Type: application/json" \
  -d '{
    "reason": "User requested cancellation"
  }'

const response = await fetch('https://api.fintechprimitives.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d/cancel', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    reason: 'User requested cancellation'
  })
});

const cancelResult = await response.json();

import requests

response = requests.post(
  'https://api.fintechprimitives.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d/cancel',
  headers={
    'Authorization': 'Bearer ACCESS_TOKEN',
    'x-tenant-id': 'your_tenant',
    'Content-Type': 'application/json'
  },
  json={
    'reason': 'User requested cancellation'
  }
)

cancel_result = response.json()