Introduction

The FP API is designed to be easily predictable and have consistency across all the resources. It accepts json in the request body and returns a json representation of the resource. We use standard HTTP response codes and HTTP verbs.

You can access FP API in sandbox and production modes separately. Use the following base URLs:
Sandbox (for testing): https://s.finprim.com
Production (for live transactions): https://api.fintechprimitives.com

Authentication

Overview

FP uses OAuth 2.0 protocols for authentication. At present, FP supports the following authentications

Types of authentication

• Tenant authentication: To access the FP APIs in the context of a tenant, this authentication type must be used. This will let you access resources across partners and investors. Please note that this authentication must be only used when you are accessing FP APIs from your server.
• Partner authentication(Coming soon): If you rely on partners like sub-distributors to distribute mutual funds, instead of authenticating your partners by yourself, use FP's partner authentication service and get a partner-specific access token. Once you get this token, you can access any FP API with that token and the API will be aware of this partner context and behave accordingly to ensure that partners can access only those resources which they are supposed to access.
• Investor authentication(Coming soon): Instead of authenticating the investors by yourself, use FP's investor authentication service and get an investor specific access token. Once you get this token, you can access any FP API with that token and the API will be aware of this investor context and behave accordingly to ensure that investors can access only those resources which they are supposed to access.

Endpoints:

POST /v2/auth/{tenant_name}/token

Tenant Authentication

Getting Started

1. Write an email to fpsupport@cybrilla.com and register yourself as OAuth 2.0 client for tenant authentication purposes.
2. We will share the client_id, client_secret, and tenant_name.
3. Use POST /v2/auth/{tenant_name}/token endpoint and provide client_id, client_secret, and tenant_name to generate token object.
4. Use the generated token object's access_token to access FP APIs.
5. Every token object will have an expiry time. Ensure that you are creating a new token object if the existing token object is expired.

Token Object

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyUVVoVl9aaGVyQmRHMjVQMl83cmdVaDYxcS1WXzZ0NzNmO",
  "expires_in": 1800,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "default"
}

Attribute	Type	Comments
access_token	string	The access token contains the security credentials for a login session and identifies the user. You need to pass this in the header at the time of invoking FP APIs.
expires_in	long	It specifies the validity of the access token in seconds.
refresh_token	string	Not applicable for tenant login and reserved for Partner and Investor authentication.
refresh_expires_in	long	Not applicable for tenant login and reserved for Partner and Investor authentication.
token_type	string	The token type will always be Bearer. This type of authentication means that any Bearer of an access token can access FP APIs.
not-before-policy (for internal use)	int	not-before-policy ensures that any tokens issued before that time become invalid.
scope (for internal use)	string	The scope is a mechanism in OAuth 2.0 to limit an application's access to a user's account.

Getting tenant token

For tenant tokens, we are using Client Credentials flow. This flow is recommended for server-side (aka confidential) client applications with no end-user, which normally describes server-to-server communication. The application needs to securely store its client ID and secret and pass them in exchange for an access token.

POST /v2/auth/{tenant_name}/token

curl \
-d "client_id=XXX" \
-d "client_secret=XXXXXXX" \
-d "grant_type=client_credentials" \
"{baseUrl}/v2/auth/{tenant_name}/token"

Success response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICIyUVVoVl9aaGVyQmRHMjVQMl83cmdVaDYxcS1WXzZ0NzNmO",
  "expires_in": 1800,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "default"
}

Request Parameters

Parameter	Mandatory	Default	Description
client_id	yes	-	client_id provided by fintechprimitives
client_secret	yes	-	client_secret provided by fintechprimitives
grant_type	yes	-	client_credentials

Using token to make API call

FP API uses bearer auth to authenticate all the API calls. You need to send the following header in all your API calls along with your access token:

Authorization: Bearer ACCESS_TOKEN

Error Response

Fintech Primitives use standard HTTP error codes. Please refer to HTTP error codes documentation.

All authentication errors will responses will have following structure.

Error response:

{
  "error": "unauthorized_client",
  "error_description": "Invalid client secret"
}

Attribute	Type	Comments
error	string	Error code
error_description	string	Error descriptive message.

Possible types of errors are invalid_client, unsupported_grant_type, unauthorized_client, invalid_request and access_denied.

KYC Checks

Create a kyc check

curl -X POST "https://s.finprim.com/api/kyc/check"
-H "Authorization: Bearer JWTTOKEN"
-d
'
{
  "pan": "BNBPP9384M"
}
'

The above command returns JSON structured like this:

{
  "id": "5620fd1f-eb14-442e-b0ee-da96a6c305c0",
  "source_ref_id": null,
  "pan": "BNBPP9384M",
  "entity_details": {
  },
  "status": true,
  "constraints": [
    {
      "type": "investment_limit",
      "amount": {
        "value": 50000,
        "currency": "inr"
      }
    }
  ],
  "sources": [
    {
      "name": "kra-cams",
      "response_verbatim": "Y|BNBPP9384M|KS100",
      "fetched_at": "2018-04-21T23:00:20+05:30"
    }
  ],
  "created_at": "2018-04-21T23:00:20+05:30",
  "updated_at": "2018-04-21T23:00:20+05:30"
}

Creating a KYC Check fetches the investor's kyc status from different sources

HTTP Request

POST https://s.finprim.com/api/kyc/check

Query Parameters

Parameter	Mandatory	Default	Description
pan	yes	-	A valid PAN number to check the kyc status for

Fetch a kyc check

curl "https://s.finprim.com/api/kyc/5620fd1f-eb14-442e-b0ee-da96a6c305c0"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "id": "5620fd1f-eb14-442e-b0ee-da96a6c305c0",
  "source_ref_id": null,
  "pan": "BNBPP9384M",
  "entity_details": {
  },
  "status": true,
  "constraints": [
    {
      "type": "investment_limit",
      "amount": {
        "value": 50000,
        "currency": "inr"
      }
    }
  ],
  "sources": [
    {
      "name": "kra-cams",
      "response_verbatim": "Y|BNBPP9384M|KS100",
      "fetched_at": "2018-04-21T23:00:20+05:30"
    }
  ],
  "created_at": "2018-04-21T23:00:20+05:30",
  "updated_at": "2018-04-21T23:00:20+05:30"
}

Retrieve the KYC Check object

HTTP Request

GET https://s.finprim.com/api/kyc/{id}

Refetch a kyc check

curl -X PUT "https://s.finprim.com/api/kyc/5620fd1f-eb14-442e-b0ee-da96a6c305c0/refetch"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "id": "5620fd1f-eb14-442e-b0ee-da96a6c305c0",
  "source_ref_id": null,
  "pan": "BNBPP9384M",
  "entity_details": {
  },
  "status": true,
  "constraints": [
    {
      "type": "investment_limit",
      "amount": {
        "value": 50000,
        "currency": "inr"
      }
    }
  ],
  "sources": [
    {
      "name": "kra-cams",
      "response_verbatim": "Y|BNBPP9384M|KS100",
      "fetched_at": "2018-04-21T23:00:20+05:30"
    }
  ],
  "created_at": "2018-04-21T23:00:20+05:30",
  "updated_at": "2018-04-21T23:00:20+05:30"
}

Force the platform to refetch the kyc information from the sources

HTTP Request

PUT https://s.finprim.com/api/kyc/{id}/refetch

KYC Requests

This endpoint can be used to create a KYC application. Even though values for name, pan, email, date_of_birth and mobile fields are required to create a KYC application and generate an OTP, all the required information must be collected from the KYC non-compliant user in order to perform eSign and complete the KYC application submission. At any point in time you can refer to requirements.fields_needed attribute in the KYC object to check the fields for which the values are required.

Endpoints:

POST /v2/kyc_requests
GET /v2/kyc_requests/:id
GET /v2/kyc_requests
PATCH /v2/kyc_requests
POST /v2/kyc_requests/:id/simulate

Basic workflow

1. Create a KYC application by providing values for name, pan, email, date_of_birth and mobile. The KYC request will be in pending state at this stage. You can check the state by referring to the status attribute in the KYC object.

2. Provide all the required information to eSign and submit the KYC application that is created. You can also check the requirements.fields_needed section in the KYC object to see the list of fields which are yet to be input.

3. Once all the required details are provided, the KYC application moves from pending to esign_required state. Please note that this process might take 1-2 minutes (approx.) in production environment as the bank account details are verified in the background.

4. Once the state of the KYC application changes to esign_required, Esign API should be used to create an esign object. Redirect the user to redirect_url in the esign object in order to perform the eSign.

5. Once the user completes the eSign process successfully, the KYC application will be submitted and state moves from esign_required to submitted.

6. Now our AMC partner would have received the KYC application that was submitted and the verification process begins, post which the application will be moved to either successful or rejected state

KYC Request Object

{
  "object": "kyc_request",
  "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
  "status": "pending",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "raj@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "signature": "434ceed567-53c5-3f68-ba3b-cbdc58526c64",
  "photo": "946848da-50bb-4957-a940-c164c0c71172",
  "gender": "male",
  "date_of_birth": "1981-01-15",
  "marital_status": "married",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "110001",
    "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "6d0f4d71-aec3-4be6-8295-630e0fddaef6",
  "residential_status": "resident_individual",
  "occupation_type": null,
  "created_at": "2019-11-09T13:26:38.946+0530",
  "expires_at": "2019-11-09T13:26:38.946+0530",
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
  },
  "verification": {
    "status": "pending",
    "details": null,
    "details_verbose": null
  },
  "requirements": {
    "fields_needed": [
      "ipv_video"
    ]
  }
}

Attribute	Type	Comments
object	string	Value is kyc_request. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the kyc_request object
name	string	Full name of the investor
pan	string	PAN number of the investor
email	string	Email id of the investor
mobile	hash	Mobile number of the investor
date_of_birth	string	Date of birth of the investor
aadhaar_number	string	Last 4 digits of the investor's aadhaar number
father_name	string	Investor's father name
spouse_name	string	Investor's spouse name
mother_name	string	Investor's mother name
gender	enum	Investor's gender. Possible values: male, female, transgender
country_of_birth	enum	Investor's country of birth in ISO 3601 2 alphabet code
marital_status	enum	Investor's marital status. Possible values: married, unmarried, others
residential_status	enum	This determines the investor's residential status for tax purposes. Possible values: resident_individual
occupation_type	enum	Investor's occupation details. Possible values: business, professional, self_employed, retired, housewife, student, public_sector, private_sector, government_sector, others
geolocation	hash	Location of the investor from where the kyc application is submitted. It contains latitude and longitude
bank_account	hash	Investor's bank account details. Contains account_holder_name, account_number, ifsc_code, proof
address	hash	Address for all correspondence
identity_proof	string	Copy of investor's pan card
ipv_video	string	Verification video
signature	string	Investor's signature
photo	string	Investor's photograph
otp	string	Verification code for the video. The code has no expiration time.
status	string	The status of the kyc request. Can be pending, esign_required, submitted, successful, rejected
created_at	string	The timestamp at which the kyc request object is created
expires_at	string	The timestamp at which the kyc request object expires
verification	hash	The details of the verification status of the data submitted
requirements	hash	Feedback on the data requirements. It contains fields_needed which represent the list of fields that are required for procesing the KYC Request

verification hash

A snippet of verification hash from the KYC Request object

{
  // showing only a part of KYC Request object
  "verification": {
    "status": "rejected",
    "details": {
      "pan": "data_mismatch",
      "signature": "data_missing",
      "address.proof": "document_unclear"
    },
    "details_verbose": {
      "pan": {
        "code": "data_mismatch",
        "reason": "Invalid pan"
      },
      "signature": {
        "code": "data_missing",
        "reason": "Signature not available"
      },
      "address.proof": {
        "code": "document_invalid",
        "reason": "Proof of address not valid; Translation into english is required"
      }
    }
  }
}

Attribute	Type	Comments
status	string	Status of the verification. Can be pending, esign_required, submitted, successful, rejected
details	hash	If the verification status is rejected, this contains the details about the rejection. Keys of this hash represent the fields in the kyc request object and value can be data_missing, data_mismatch, document_unclear, document_invalid
details_verbose	hash	If the verification status is rejected, this contains the details about the rejection along with a reason text. Keys of this hash represent the fields in the kyc request object and value is a hash with code and reason keys. code is the same as in the details hash

Create a kyc request

curl -X POST "https://s.finprim.com/v2/kyc_requests"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "pan": "K1PPG1998U",
  "email": "raj@example.com",
  "aadhaar_number": "1210",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": "",
  "mother_name": "Neha Gupta",
  "gender": "male",
  "date_of_birth": "1980-10-19",
  "country_of_birth": "in",
  "marital_status": "unmarried",
  "residential_status": "resident_individual",
  "occupation_type": "private_sector",
  "address": {
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "city": "Delhi",
    "pincode": "110001",
    "country": "in",
    "proof": "4192de0d-165f-458e-89ec-d4334b370256",
    "proof_back": "771a4d57-5447-4b1e-b4b6-dcb6049bda8c",
    "proof_type": "passport",
    "proof_number": "JXXXXXX0",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
  },
  "identity_proof": "2f4d93e0-b700-41b8-b78e-e130224cfb03",
  "signature": "434ceed567-53c5-3f68-ba3b-cbdc58526c64",
  "photo": "946848da-50bb-4957-a940-c164c0c71172"
}

JSON response:

{
  "object": "kyc_request",
  "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
  "status": "pending",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "raj@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "signature": "434ceed567-53c5-3f68-ba3b-cbdc58526c64",
  "photo": "946848da-50bb-4957-a940-c164c0c71172",
  "gender": "male",
  "date_of_birth": "1981-01-15",
  "marital_status": "married",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "110001",
    "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "6d0f4d71-aec3-4be6-8295-630e0fddaef6",
  "residential_status": "resident_individual",
  "occupation_type": null,
  "created_at": "2019-11-09T13:26:38.946+0530",
  "expires_at": "2019-11-09T13:26:38.946+0530",
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
  },
  "verification": {
    "status": "pending",
    "details": null,
    "details_verbose": null
  },
  "requirements": {
    "fields_needed": [
      "ipv_video"
    ]
  }
}

The endpoint is used to submit a KYC request to the platform.

HTTP Request

POST /v2/kyc_requests

Query Parameters

Name	Mandatory*	Type	Comments
name	yes	string	name of the investor
pan	yes	string	should be a valid individual pan number
email	yes	string	email ID of the investor to be reported to AMC
date_of_birth	yes	string	date of birth in yyyy-mm-dd format
mobile	yes	object
aadhaar_number	no	string	last 4 digits of aadhaar
father_name	no	string	mandatory if spouse_name is not mentioned
spouse_name	no	string	mandatory if father_name is not mentioned
mother_name	no	string
gender	no	string	gender of the investor. Values permitted: male, female, transgender
country_of_birth	no	string	investor's country of birth in ISO 3601 2 alphabet code
marital_status	no	string	marital status of the investor. Values permitted: married, unmarried, others
residential_status	no	string	residential status of the investor. Values permitted: resident_individual
occupation_type	no	string	occupation of the investor. Values permitted: business, professional, self_employed, retired, housewife, student, public_sector, private_sector, government_sector, others
address	no	object
identity_proof	no	string	(ID of File) PAN card image. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
ipv_video	no	string	(ID of File) verification video of the investor. File must be in mp4 format and size should not exceed 10 MB.
signature	no	string	(ID of File) copy of the wet signature of the investor. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
photo	no	string	(ID of File) investor's photo. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
geolocation	no	object	Location details of the investor from where the kyc application is submitted
bank_account	no	object	Investor's bank account details

Mobile params

Name	Mandatory	type	Comments
isd	yes	string	isd code of country
number	yes	string	mobile number

Address params

Name	Mandatory	type	Comments
line_1	yes	string	address line 1
line_2	no	string	address line 2
line_3	no	string	address line 3
city	yes	string	city name
pincode	yes	string	valid area pincode
country	yes	string	country in ISO 3601 2 alphabet code
proof	yes	string	(ID of File) copy of the address proof. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
proof_back	no	string	(ID of File) copy of the back side of the address proof. Required if proof_type is voter_id, passport and driving_licence. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.
proof_type	yes	string	one of passport, voter_id, driving_licence
proof_number	yes	string	valid number mentioned on the address proof
proof_issue_date	no	string	Required if proof_type is passport, driving_licence. Should be in past in yyyy-mm-dd format
proof_expiry_date	no	string	Required if proof_type is passport, driving_licence. Should be in future in yyyy-mm-dd format

Geolocation

Name	Mandatory	type	Comments
latitude	yes	float	Geolocation latitude
longitude	yes	float	Geolocation longitude

Bank Account

Name	Mandatory	type	Comments
account_holder_name	yes	string	Name of the bank account holder
account_number	yes	string	Account number on cancelled cheque document
ifsc_code	yes	string	IFSC code of the bank
proof	yes	string	(ID of File) cancelled cheque image. File must be in jpg, jpeg, png or pdf format and size should not exceed 5 MB.

Fetch a kyc request

curl -X GET "https://s.finprim.com/v2/kyc_requests/123"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response:

{
  "object": "kyc_request",
  "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
  "status": "rejected",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "raj@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "ipv_video": "02651d2a-38fc-42a2-8c20-221d10453b3c",
  "signature": "434ceed567-53c5-3f68-ba3b-cbdc58526c64",
  "photo": "946848da-50bb-4957-a940-c164c0c71172",
  "gender": "male",
  "date_of_birth": "1981-01-15",
  "marital_status": "married",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "110001",
    "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "6d0f4d71-aec3-4be6-8295-630e0fddaef6",
  "residential_status": "resident_individual",
  "occupation_type": null,
  "created_at": "2019-11-09T13:26:38.946+0530",
  "expires_at": "2019-11-09T13:26:38.946+0530",
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
  },
  "requirements": {
    "fields_needed": [

    ]
  },
  "verification": {
    "status": "rejected",
    "details": {
      "pan": "data_mismatch",
      "signature": "data_missing",
      "address.proof": "document_unclear"
    },
    "details_verbose": {
      "pan": {
        "code": "data_mismatch",
        "reason": "Invalid pan"
      },
      "signature": {
        "code": "data_missing",
        "reason": "Signature not available"
      },
      "address.proof": {
        "code": "document_invalid",
        "reason": "Proof of address not valid; Translation into english is required"
      }
    }
  }
}

The endpoint is used to fetch the details of a KYC request.

HTTP Request

GET /v2/kyc_requests/:id

Query Parameters

Parameter	Mandatory	Default	Description
id	yes	-	id of the KYC Request

Status Descriptions - verification.status

Value	Description
pending	The KYC request has been created. It will be sent to AMC when all the required fields are provided.
esign_required	Investor details document needs to be eSigned for the kyc request to be processed further.
submitted	The KYC request has been submitted to the AMC
successful	The KYC request has been successfully processed by the AMC
rejected	The KYC request has been rejected

Verification Details

Value	Description
data_mismatch	The data provided in the input is not matching with the document
document_invalid	The provided document is not valid
document_unclear	The provided document is not clear to read
data_missing	The data point is completely missing

Details Verbose

Name	Comments
code	Value is same as Verification Details
reason	Rejection messages separated by semicolon

List all kyc requests

curl -X GET "https://s.finprim.com/v2/kyc_requests?pan=K1PPG1998U&status=rejected,pending"
-H "Authorization: Bearer ACCESS_TOKEN"

JSON response:

{
  "object": "list",
  "data": [
    {
      "object": "kyc_request",
      "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
      "status": "rejected",
      "aadhaar_number": "1210",
      "pan": "K1PPG1998U",
      "name": "Rani Gupta",
      "father_name": "Rajesh Gupta",
      "spouse_name": null,
      "mother_name": null,
      "email": null,
      "mobile": null,
      "ipv_video": "02651d2a-38fc-42a2-8c20-221d10453b3c",
      "signature": null,
      "photo": null,
      "gender": "male",
      "date_of_birth": "1981-01-15",
      "marital_status": "married",
      "country_of_birth": "in",
      "address": {
        "city": "Delhi",
        "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
        "line_1": "E/&02",
        "line_2": "Opp SBI ATM",
        "line_3": "12th Main Road South Delhi",
        "country": "in",
        "pincode": "401012",
        "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
        "proof_type": "passport",
        "proof_number": "JXXXXXXA",
        "proof_issue_date": "2004-10-20",
        "proof_expiry_date": "2020-10-20"
      },
      "identity_proof": "6d0f4d71-aec3-4be6-8295-630e0fddaef6",
      "residential_status": "resident_individual",
      "occupation_type": null,
      "created_at": "2019-11-09T13:26:38.946+0530",
      "expires_at": "2019-11-09T13:26:38.946+0530",
      "otp": "9bbf32",
      "geolocation": {
        "latitude": 12.354,
        "longitude": 77.453
      },
      "bank_account": {
        "account_holder_name": "Rani Gupta",
        "account_number": "919017057965811",
        "ifsc_code": "UTIB0003093",
        "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
      },
      "requirements": {
        "fields_needed": [

        ]
      },
      "verification": {
        "status": "rejected",
        "details": {
          "pan": "data_mismatch",
          "signature": "data_missing",
          "address.proof": "document_unclear"
        },
        "details_verbose": {
          "pan": {
            "code": "data_mismatch",
            "reason": "Invalid pan"
          },
          "signature": {
            "code": "data_missing",
            "reason": "Signature not available"
          },
          "address.proof": {
            "code": "document_invalid",
            "reason": "Proof of address not valid; Translation into english is required"
          }
        }
      }
    },
    {
      "object": "kyc_request",
      "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
      "status": "pending",
      "aadhaar_number": "1210",
      "pan": "K1PPG1998U",
      "name": "Rani Gupta",
      "father_name": "Rajesh Gupta",
      "spouse_name": null,
      "mother_name": null,
      "email": null,
      "mobile": null,
      "signature": null,
      "photo": null,
      "gender": "male",
      "date_of_birth": "1981-01-15",
      "marital_status": "married",
      "country_of_birth": "in",
      "address": {
        "city": "Delhi",
        "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
        "line_1": "E/&02",
        "line_2": "Opp SBI ATM",
        "line_3": "12th Main Road South Delhi",
        "country": "in",
        "pincode": "401012",
        "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
        "proof_type": "passport",
        "proof_number": "JXXXXXXA",
        "proof_issue_date": "2004-10-20",
        "proof_expiry_date": "2020-10-20"
      },
      "identity_proof": "6d0f4d71-aec3-4be6-8295-630e0fddaef6",
      "residential_status": "resident_individual",
      "occupation_type": null,
      "created_at": "2019-11-09T13:26:38.946+0530",
      "expires_at": "2019-11-09T13:26:38.946+0530",
      "otp": "9bbf32",
      "geolocation": {
        "latitude": 12.354,
        "longitude": 77.453
      },
      "bank_account": {
        "account_holder_name": "Rani Gupta",
        "account_number": "919017057965811",
        "ifsc_code": "UTIB0003093",
        "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
      },
      "requirements": {
        "fields_needed": [
          "ipv_video"
        ]
      },
      "verification": {
        "status": "pending",
        "details": null,
        "details_verbose": null
      }
    }
  ]
}

The endpoint is used to fetch the list of KYC requests.

HTTP Request

GET /v2/kyc_requests

Query Parameters

Name	Mandatory*	Type	Comments
pan	No	string	PAN number
status	No	string	Can be pending, esign_required, submitted, successful, rejected. Multiple values are supported by , seperator.

Update a kyc request

curl -X POST "https://s.finprim.com/v2/kyc_requests/6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "identity_proof": "1411ff9c-3b68-4c5c-bfe7-46f1a1cdd7f6",
  "ipv_video": "76e18d5f-e84a-478d-a836-4971f38d3814"
}

The endpoint is used to update the details of a KYC request

JSON response:

{
  "object": "kyc_request",
  "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
  "status": "pending",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "raj@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "signature": "434ceed567-53c5-3f68-ba3b-cbdc58526c64",
  "photo": "946848da-50bb-4957-a940-c164c0c71172",
  "gender": "male",
  "date_of_birth": "1981-01-15",
  "marital_status": "married",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "110001",
    "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "1411ff9c-3b68-4c5c-bfe7-46f1a1cdd7f6",
  "ipv_video": "76e18d5f-e84a-478d-a836-4971f38d3814",
  "residential_status": "resident_individual",
  "occupation_type": null,
  "created_at": "2019-11-09T13:26:38.946+0530",
  "expires_at": "2019-11-09T13:26:38.946+0530",
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
  },
  "verification": {
    "status": "pending",
    "details": null,
    "details_verbose": null
  },
  "requirements": {
    "fields_needed": [

    ]
  }
}

HTTP Request

POST/PATCH /v2/kyc_requests/:id

Request/Response same as Create KYC Request

Simulate a kyc request

curl -X POST "https://s.finprim.com/v2/kyc_requests/6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21/simulate"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "status": "successful"
}

The endpoint is used to simulate the status of a KYC request

JSON response:

{
  "object": "kyc_request",
  "id": "6wq82c2ce-e38d-4b8e-85f3-wqfb7dc382f21",
  "status": "successful",
  "aadhaar_number": "1210",
  "pan": "K1PPG1998U",
  "name": "Rani Gupta",
  "father_name": "Rajesh Gupta",
  "spouse_name": null,
  "mother_name": "Neha Gupta",
  "email": "raj@example.com",
  "mobile": {
    "isd": "+91",
    "number": "8160597103"
  },
  "ipv_video": "02651d2a-38fc-42a2-8c20-221d10453b3c",
  "signature": "434ceed567-53c5-3f68-ba3b-cbdc58526c64",
  "photo": "946848da-50bb-4957-a940-c164c0c71172",
  "gender": "male",
  "date_of_birth": "1981-01-15",
  "marital_status": "married",
  "country_of_birth": "in",
  "address": {
    "city": "Delhi",
    "proof": "e17b7wb1-2204-40f2-b4b9-8012c3c36f73",
    "line_1": "E/&02",
    "line_2": "Opp SBI ATM",
    "line_3": "12th Main Road South Delhi",
    "country": "in",
    "pincode": "110001",
    "proof_back": "71a773fa-134c-4849-891e-df3a2s230f6f",
    "proof_type": "passport",
    "proof_number": "JXXXXXXA",
    "proof_issue_date": "2004-10-20",
    "proof_expiry_date": "2020-10-20"
  },
  "identity_proof": "6d0f4d71-aec3-4be6-8295-630e0fddaef6",
  "residential_status": "resident_individual",
  "occupation_type": null,
  "created_at": "2019-11-09T13:26:38.946+0530",
  "expires_at": "2019-11-09T13:26:38.946+0530",
  "otp": "9bbf32",
  "geolocation": {
    "latitude": 12.354,
    "longitude": 77.453
  },
  "bank_account": {
    "account_holder_name": "Rani Gupta",
    "account_number": "919017057965811",
    "ifsc_code": "UTIB0003093",
    "proof": "cc10460f-905d-4b37-8983-97a5a8afc07a"
  },
  "requirements": {
    "fields_needed": [

    ]
  },
  "verification": {
    "status": "successful",
    "details": null,
    "details_verbose": null
  }
}

HTTP Request

POST /v2/kyc_requests/:id/simulate

Query Parameters

Name	Mandatory*	Type	Comments
status	yes	string	expected status of the kyc request. Values permtted: successful, rejected, expired. For successful or rejected, the KYC request must be in submitted state. For expired, the KYC request must be in pending or esign_required state

Esigns

Use this to complete the Esign process for the KYC request.

Endpoints:

POST /v2/esigns
GET /v2/esigns/:id

Esign Object

{
  "object": "esign",
  "id": "8f05d378-3cf2-4e57-83c8-5ad767f21f12",
  "type": "aadhaar",
  "kyc_request": "c6b524ed-fcbd-4e37-9348-6fee95f7d997",
  "redirect_url": "http://s.finprim.com/v2/esigns/8f05d378-3cf2-4e57-83c8-5ad767f21f12/sign?token=ce825801-beab-4868-8fd8-5c4009e7f112",
  "status": "pending",
  "postback_url": "http://localhost:3000",
  "created_at": "2020-06-22T13:15:12.308+0530"
}

Attribute	Type	Comments
object	string	Value is esign. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the esign object
type	string	Type of the esign. Can be aadhaar
kyc_request	string	KYC Request for which this esign is being processed for
redirect_url	string	Url for starting the esign process
status	string	Status of the esign. Can be pending, successful
postback_url	string	Url to which you will be redirected once esign process is complete
created_at	string	The timestamp at which the esign object is created

* The redirect_url can be used multiple times in case the user is not able to complete the esign process

Create an esign

curl -X POST "https://s.finprim.com/v2/esigns"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -H "Content-Type: application/json"
  -d '{json_request}'

JSON request:

{
  "kyc_request": "c6b524ed-fcbd-4e37-9348-6fee95f7d997",
  "postback_url": "http://localhost:3000"
}

JSON response:

{
  "object": "esign",
  "id": "8f05d378-3cf2-4e57-83c8-5ad767f21f12",
  "type": "aadhaar",
  "kyc_request": "c6b524ed-fcbd-4e37-9348-6fee95f7d997",
  "redirect_url": "http://s.finprim.com/v2/esigns/8f05d378-3cf2-4e57-83c8-5ad767f21f12/sign?token=ce825801-beab-4868-8fd8-5c4009e7f112",
  "status": "pending",
  "postback_url": "http://localhost:3000",
  "created_at": "2020-06-22T13:15:12.308+0530"
}

The endpoint is used to create an esign

HTTP Request

POST /v2/esigns

Query Parameters

Name	Mandatory*	Type	Comments
kyc_request	yes	string	id of the kyc_request to which it is related
postback_url	yes	string	The URL to which you want be redirected once the esign process is complete.

Postback response

After the esign process is completed, we redirect the user to postback_url with the following query parameters

Name	Value
esign	id of the esign object
status	status of the esign.

Fetch an esign

curl -X GET "https://s.finprim.com/v2/esigns/8f05d378-3cf2-4e57-83c8-5ad767f21f12"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON response:

{
  "object": "esign",
  "id": "8f05d378-3cf2-4e57-83c8-5ad767f21f12",
  "type": "aadhaar",
  "kyc_request": "c6b524ed-fcbd-4e37-9348-6fee95f7d997",
  "redirect_url": "http://s.finprim.com/v2/esigns/8f05d378-3cf2-4e57-83c8-5ad767f21f12/sign?token=ce825801-beab-4868-8fd8-5c4009e7f112",
  "status": "successful",
  "postback_url": "http://localhost:3000",
  "created_at": "2020-06-22T13:15:12.308+0530"
}

The endpoint is used to fetch an esign

HTTP Request

GET /v2/esigns/:id

Query Parameters

Name	Mandatory*	Type	Comments
id	yes	string	id of the esign

Parses

Represents parse operation. This API can be used to parse a consolidated account statement or CAS file. We support CAS files - Detailed type of Karvy and CAMS.

Upload CAS file in Files API Refer before using parser service. File service returns id once you have uploaded the file, use this to perform parsing.

Note: Non commercial transactions are not parsed.

A typical parse object contains the following fields.

Parse Object

{
  "id": "parse_a7b0f278604d46d8a847fde20da1b4e7",
  "object": "parse",
  "status": "processed",
  "file": "file_fe8a573f4a6b4a68be04d26e7aa164a0",
  "outcome": [
    {
      "pan": "AMXXXXXX9M",
      "advisor": "ARN-2590",
      "registrar": "FTAMIL",
      "folio_number": "180111958/0",
      "transactions": [
        {
          "date": "2013-01-31",
          "type": "purchase",
          "amount": 11000,
          "units": 44.972,
          "price": 244.595,
          "unit_balance": 44.972
        }
      ],
      "scheme_code": "FTI034",
      "scheme_name": "0349905131566 Franklin India Taxshield - GROWTH",
      "opening_balance": 0,
      "closing_balance": 44.972,
      "calculated_closing_balance": 44.972
    }
  ],
  "reason": null,
  "created_at": "2020-06-18T14:16:13+05:30"
}

Attribute	Type	Comments
object	string	Value is parse. String representing the object type. Objects of the same type share the same value.
id	string	Unique identifier for the parse object created
file	string	File id used to create parse request
status	string	Status of the parse request. Can be pending, processed, and failed
outcome	list	Contains the transactions parsed from the file
reason	string	Contains reason if status is failed
created_at	timestamp	Date and time when the parse object was created

Outcome attributes

Attribute	Type	Description
pan	string	PAN number of the investor
advisor	string	ARN code or RIA code of the distributor/advisor as seen in the CAS file
registrar	string	RTA identifier
folio_number	string	Folio number
scheme_code	string	Scheme code. Refer Single Fund Schemes Detail API for scheme code details
scheme_name	string	Scheme name as it appears in the CAS file. Any scheme name which is spread across more than one line is truncated.
reverse_product_code	string	Unique code to identify a scheme.
transactions	list	List of transactions. The order will remain the same as in the CAS file.
opening_balance	decimal	Opening balance
closing_balance	decimal	Closing balance
calculated_closing_balance	decimal	Computed closing balance in parser service based on difference between credit and debits in the transactions. This can be used for reconciliation purposes.

Transaction attributes

Attribute	Type	Description
date	date	Date of transaction
type	string	Supported transaction types are sip, purchase, redemption, switch_in, switch_out and reversal
amount	decimal	Refers to the amount which investor have invested, transferred or withdrawn or the dividend amount being paid or reinvested
units	decimal	Number of units allotted or redeemed
price	decimal	Transaction NAV
unit_balance	decimal	Holding units after the end of this particular transaction

Create a parse

curl -X POST "https://s.finprim.com/v2/parses"
-H "Authorization: Bearer JWTTOKEN"
-d
'{
    "file" : "file_fe8a573f4a6b4a68be04d26e7aa164a0",
    "password": "password"
}'

The above command returns a JSON similar to one below:

{
  "id": "parse_a7b0f278604d46d8a847fde20da1b4e7",
  "object": "parse",
  "status": "pending",
  "file": "file_fe8a573f4a6b4a68be04d26e7aa164a0",
  "outcome": null,
  "created_at": "2020-06-18T14:16:13+05:30"
}

This API is for submitting a request to parse the file.

HTTP Request

POST /v2/parses

Query Parameters

Parameter	Mandatory	Default	Description
file	yes	-	id of the file to parse. Refer file-operations to upload a file. File type should be in pdf format.
password	no	-	Password to open the CAS file.

Fetch a parse

curl "https://s.finprim.com/v2/parses/parse_a7b0f278604d46d8a847fde20da1b4e7"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns a JSON similar to one below

{
  "id": "parse_a7b0f278604d46d8a847fde20da1b4e7",
  "object": "parse",
  "status": "processed",
  "file": "file_fe8a573f4a6b4a68be04d26e7aa164a0",
  "outcome": [
    {
      "pan": "AMXXXXXX9M",
      "advisor": "ARN-2590",
      "registrar": "FTAMIL",
      "folio_number": "180111958/0",
      "scheme_code": "FTI034",
      "scheme_name": "Franklin India Taxshield - GROWTH",
      "reverse_product_code": "FITGP",
      "transactions": [
        {
          "date": "2013-01-31",
          "type": "purchase",
          "amount": 11000,
          "units": 44.972,
          "price": 244.595,
          "unit_balance": 44.972
        },
        {
          "date": "2013-02-01",
          "type": "sip",
          "amount": 1000,
          "units": 4.098,
          "price": 244.0149,
          "unit_balance": 49.07
        }
      ],
      "opening_balance": 0,
      "closing_balance": 49.07,
      "calculated_closing_balance": 49.07
    }
  ],
  "reason": null,
  "created_at": "2020-06-18T14:16:13+05:30"
}

This API is used to fetch the parsed details.

HTTP Request

GET /v2/parses/:id

Query Parameters

Parameter	Mandatory	Default	Description
id	yes	-	id returned from create parse request api.

Map Parsed Folios

curl -X POST  "https://s.finprim.com/v2/mf_folios/migrate"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "parse_operation_id": "parse_71a50be288154737ad6a3e53a27bf1c6",
  "mf_investment_account_id": "mfia_798fa03aba614840b983609e89ed16f2"
}

JSON Response:

{
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "results": {
    "migrated": [
      {
        "folio_number": "18019158/1",
        "amc_code": "RMF",
        "amc_name": "RELIANCE CAPITAL ASSET MANAGEMENT LTD."
      }
    ],
    "failed": [
      {
        "folio_number": "18019158/0",
        "reason": "Folio already exist"
      },
      {
        "folio_number": "18019158/2",
        "reason": "Folio - Investor pan mismatch "
      },
      {
        "folio_number": "18019158/3",
        "reason": "No Fund house found with scheme code : FTI034"
      }
    ]
  }
}

POST /v2/mf_folios/migrate

This API can be used to map the folio numbers of a successful parse-operation against an investment account provided that the following conditions are met.

• The parse operation must be successful.
• The investment account must be a valid FP investment account.
• The pan in the CAS statement must match the primary investor PAN of the investment account.
• The holding pattern of the investment account must be single.

Once you have mapped a folio number against an investment account, you are allowed to place orders against that investment account-folio combination.

Request Parameters

Name	Mandatory	Type	Comments
mf_investment_account_id	yes	string	V2 id of the investment account
parse_operation_id	yes	string	id returned from create parse request api.

Bank Accounts ^{(Early Access)}

Endpoints:

POST /v2/bank_accounts

GET /v2/bank_accounts/:id

GET /v2/bank_accounts

Bank account object

{
  "id": "bac_98367e8972b43867a9c68a7c4605a31d",
  "object": "bank_account",
  "investor": "156",
  "primary_account_holder_name": "Tony",
  "account_number": "00000001214415",
  "type": "SAVINGS",
  "ifsc_code": "ICIC0000611",
  "proof": "file_3867a9c68a7c4605a31d98367e8972b4",
  "created_at": "2021-04-01T17:51:21+05:30",
  "updated_at": "2021-04-01T17:51:21+05:30"
}

Attribute	Type	Nullable	Remarks
id	string	no	Unique identifier of the bank account object
object	string	no	Indicates the type of object. bank_account
investor	string	no	Investor Id to whom the bank_account belongs to.
primary_account_holder_name	string	no	Registred account holder name
account_number	string	no	Account number of the bank account.
type	string	no	Type of the bank account. Possible values - savings -current -nro -nre
ifsc_code	string	no	IFSC of the bank account.
proof	string	conditional	File referring to the cancelled_cheque or any proof corresponding to the bank account
created_at	string	no	Bank account creation timestamp
updated_at	string	yes	Bank account object last updated timestamp

Create Bank Account

Use the below endpoint to create bank account for an investor.

curl -X POST "https://s.finprim.com/v2/bank_accounts"
  -H "Authorization: Bearer ACCESS_TOKEN"

REQUEST:

{
  "investor": "156",
  "primary_account_holder_name": "Tony",
  "account_number": "00000001234455",
  "type": "SAVINGS",
  "ifsc_code": "ICIC0000611",
  "proof": "file_3867a9c68a7c4605a31d98367e8972b4"
}

RESPONSE:

{
  "id": "bac_98367e8972b43867a9c68a7c4605a31d",
  "object": "bank_account",
  "investor": "156",
  "primary_account_holder_name": "Tony",
  "account_number": "00000001214415",
  "type": "SAVINGS",
  "ifsc_code": "ICIC0000611",
  "proof": "file_3867a9c68a7c4605a31d98367e8972b4",
  "created_at": "2021-04-01T17:51:21+05:30",
  "updated_at": "2021-04-01T17:51:21+05:30"
}

Request:
POST /v2/bank_accounts

Request parameters:

Name	Mandatory	Type	Comments
investor	yes	string	Investor for whom the bank account to be attached to.
primary_account_holder_name	yes	string	Registered name of the investor in the bank
account_number	yes	string	Bank Account number of the bank account
type	yes	string	Type of the bank account. Possible values - savings -current -nro -nre
ifsc_code	yes	string	IFSC code of the bank account
proof	conditional	string	Needed as demanded by the flow. ex. manual bank account verification.

Useful Tips:

• proof is mandatory for bank account verification by manual mode
• Check if the ifsc_code is supported by FP before creating bank_account

Fetch all Bank Accounts

Use the below endpoint to fetch details of bank account based on the filters applied.

GET /v2/bank_accounts

curl -X POST "https://s.finprim.com/v2/bank_accounts?investor=156"
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
  "object": "list",
  "data": [
    {
      "id": "bac_98367e8972b43867a9c68a7c4605a31d",
      "object": "bank_account",
      "investor": "156",
      "primary_account_holder_name": "Tony",
      "account_number": "00000001214415",
      "type": "SAVINGS",
      "ifsc_code": "ICIC0000611",
      "proof": "file_3867a9c68a7c4605a31d98367e8972b4",
      "created_at": "2021-04-01T17:51:21+05:30",
      "updated_at": "2021-04-01T17:51:21+05:30"
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
investor	no	string	Investor id for whom the bank account are to be retrieved.

Fetch Bank Account by ID

Use the below endpoint to fetch details of the bank account object.

GET /v2/bank_accounts/:id

curl -X POST "https://s.finprim.com/v2/bank_accounts/bac_98367e8972b43867a9c68a7c4605a31d"
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
  "id": "bac_98367e8972b43867a9c68a7c4605a31d",
  "object": "bank_account",
  "investor": "156",
  "primary_account_holder_name": "Tony",
  "account_number": "00000001214415",
  "type": "SAVINGS",
  "ifsc_code": "ICIC0000611",
  "proof": "file_3867a9c68a7c4605a31d98367e8972b4",
  "created_at": "2021-04-01T17:51:21+05:30",
  "updated_at": "2021-04-01T17:51:21+05:30"
}

Path Parameters

Name	Mandatory	Type	Comments
id	yes	string	This is the unique identifier for the bank account created. For example bac_98367e8972b43867a9c68a7c4605a31d

Files

Create a file

curl -X POST "https://s.finprim.com/files"
-H "Authorization: Bearer JWTTOKEN"
-F
'
"file" : {file_to_upload}
'

The above command returns JSON structured like this:

{
  "object": "file",
  "id": "224f380c-d8f9-6f15-b2d9-27968a75f491",
  "created_at": "2018-05-13T17:53:58+05:30",
  "filename": "bob_dl_back.jpg",
  "content_type": "image/jpeg",
  "purpose": null,
  "byte_size": 4501312,
  "url": "https://files.fp.com/bob_dl_back.jpg"
}

Endpoint is used to upload POI, POA, photo, video, signature files.

HTTP Request

POST https://s.finprim.com/files

Query Parameters

Parameter	Mandatory	Default	Description
file	yes	-	File to upload.
purpose	no	-	Notes.

Fetch a file

curl "https://s.finprim.com/files/870d11d1-c63b-41ca-362a-c8062f4efc71"
  -H "Authorization: Bearer JWTTOKEN"

Endpoint is used to fetch details of a particular file.

{
  "object": "file",
  "id": "224f380c-d8f9-6f15-b2d9-27968a75f491",
  "created_at": "2018-05-13T17:53:58+05:30",
  "filename": "bob_dl_back.jpg",
  "content_type": "image/jpeg",
  "purpose": null,
  "byte_size": 4501312,
  "url": "https://files.fp.com/bob_dl_back.jpg"
}

Endpoint is used to fetch details of a particular file.

HTTP Request

GET https://s.finprim.com/files/{id}

Query Parameters

Parameter	Mandatory	Default	Description
id	yes	-	file id returned from upload file api.

List all files

curl -X GET "https://s.finprim.com/files"
  -H "Authorization: Bearer JWTTOKEN"

Enpoint fetches the list of all the files.

{
  "object": "list",
  "data": [
    {
      "object": "file",
      "id": "d2784e7c-a414-4da8-954c-911fe425094a",
      "created_at": "2018-01-29T13:07:32+05:30",
      "filename": "file1.png",
      "content_type": "image/png",
      "purpose": "kyc approve document",
      "byte_size": 127343,
      "url": "https://files.fp.com/file1.png"
    },
    {
      "object": "file",
      "id": "81d631b2-4bc7-49b9-a11d-ff10110e484b",
      "created_at": "2018-01-29T13:44:56+05:30",
      "filename": "undraw_deliveries_131a.png",
      "content_type": "image/png",
      "purpose": "kyc document",
      "byte_size": 73441,
      "url": "https://files.fp.com/undraw_deliveries_131a.png"
    }
  ]
}

Enpoint fetches the list of all the files.

HTTP Request

GET https://s.finprim.com/files

MF Investment Accounts

You need to create an investment account for your investors before you can start accepting orders. Any orders placed via an investment account and folios associated with those orders are organized under the investment account. When you migrate folios, folios having the same pans and holding pattern combination are organized under the investment accounts of matching pans and holding pattern. mf_investment_account object represents such investment accounts.

Endpoints:

POST /v2/mf_investment_accounts
PATCH /v2/mf_investment_accounts
GET /v2/mf_investment_accounts/:id
GET /v2/mf_investment_accounts

MF Investment Account Object

{
  "object": "mf_investment_account",
  "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "old_id": 110,
  "primary_investor_pan": "ACCPP55K7L",
  "second_investor_pan": null,
  "third_investor_pan": null,
  "primary_investor_old_id": 109,
  "second_investor_old_id": null,
  "third_investor_old_id": null,
  "holding_pattern": "single",
  "created_at": "2020-04-06T15:32:52+05:30"
}

Attribute	Type	Comments
object	string	Value is mf_investment_account. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the mf_investment_account object
old_id	integer	This id is the V1 id of this investment account object. We have provided this id for backward compatibility purposes, and you can use this id in V1 APIs. However, please use V2 object ids and V2 APIs wherever possible
primary_investor_pan	string	PAN of the first holder
second_investor_pan	string	PAN of the second holder
third_investor_pan	string	PAN of the third holder
primary_investor_old_id	string	V1 identifier of the first investor object attached to this investment account
second_investor_old_id	string	V1 identifier of the second investor object attached to this investment account
third_investor_old_id	string	V1 identifier of the third investor object attached to this investment account
holding_pattern	string	this value indicates the holding nature of the folios that are mapped against this investment account. For example, if the holding pattern is single, you can create transactions against investor's folios where the investor is the primary investor and holding pattern is single. Possible values: single, joint, either_or_survivor, anyone_or_survivor, first_or_survivor
created_at	string	The time at which the investment_account is created

Create a mf investment account

POST /v2/mf_investment_accounts

curl -X POST "https://s.finprim.com/v2/mf_investment_accounts"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "primary_investor_old_id": 109,
  "holding_pattern": "single"
}

JSON Response:

{
  "object": "mf_investment_account",
  "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "old_id": 110,
  "primary_investor_pan": "ACCPP55K7L",
  "second_investor_pan": null,
  "third_investor_pan": null,
  "primary_investor_old_id": 109,
  "second_investor_old_id": null,
  "third_investor_old_id": null,
  "holding_pattern": "single",
  "created_at": "2020-04-06T15:32:52+05:30"
}

Request Parameters

Name	Mandatory	Type	Comments
primary_investor_old_id	yes	string	Provide V1 investor id of the first holder
holding_pattern	no	string	Provide holding pattern for the investment account. Supported values: single

Note: Investor Details Validation

In accordance with "AMFI Best Practice Guidelines Circular No.97 /2021-22 published on March 28, 2022", FP performs following validations while creating/updating an investment account .

Attribute	Validation
Investor Name	Name must not contain special characters such as : %, [ , . , = , & , - , \ , /, _ , : , ; , ?, ( , @ , * , + , ) , # , ! , $ , ^ , ] , ", and ,
Guardian Name	Name must not contain special characters. Name should not be same as investor name.
Nominee Name	Name must not contain special characters. Name should not be same as investor name. If more than one nominee, Nominee names should be Unique.
Investor Mobile Number	For indian numbers, i.e isd_code = 91 Acceptable length of the Mobile number is 10 digits. Mobile number should not start with 0 or 1 or 2 or 3 or 4 or 5. All the digits in a Mobile number should not be the same. (Example: 7777777777 is an invalid number)
Investor Email	A valid structured email address should be present in investor contact details. (Example: values like notprovided, noemail or empty will be considered invalid email) The email address must contain exactly one occurence of '@' symbol. (Example: mf@investor@gmail.com is an invalid email address) Email address must not end with a dot. (Example: mfinvestor@gmail.com. is an invalid email address) Email address must not end with an invalid Top Level Domain. (Whitelisted TLD's : .com, .in, .org, .co, .net, .edu)

Update a mf investment account

PATCH /v2/mf_investment_accounts

This API lets you associate an investor with an investment account. This will be necessary when you avail FP's folio migration facility. When folios are migrated, corresponding investment accounts are created and folios are organized under the investment accounts. No investor objects are created. Therefore, there will be investment accounts without any investor associated with them. When you onboard an investor, you can search whether there are any investment accounts are present or not. If they are present, you can associate an investor with the investment account using this API.

curl -X PATCH "https://s.finprim.com/v2/mf_investment_accounts/mfia_14bafabfbfbc423d9b54412dd577981b"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "primary_investor_old_id": 109
}

JSON Response:

{
  "object": "mf_investment_account",
  "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "old_id": 110,
  "primary_investor_pan": "ACCPP55K7L",
  "second_investor_pan": null,
  "third_investor_pan": null,
  "primary_investor_old_id": 109,
  "second_investor_old_id": null,
  "third_investor_old_id": null,
  "holding_pattern": "single",
  "created_at": "2020-04-06T15:32:52+05:30"
}

Request Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 Id of the investment account.
primary_investor_old_id	yes	integer	Provide V1 investor id of the first holder. The pan of the investor should match with the primary_investor_pan of the investment account.

Note:

Validations performed during Create a mf investment account , are also applied while Update a mf investment account.

Fetch a mf investment account

GET /v2/mf_investment_accounts/:id

This API is used to fetch a given investment account by its V2 identifier.

curl -X GET "https://s.finprim.com/v2/mf_investment_accounts/mfia_14bafabfbfbc423d9b54412dd577981b"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response:

{
  "object": "mf_investment_account",
  "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "old_id": 110,
  "primary_investor_pan": "ACCPP55K7L",
  "second_investor_pan": null,
  "third_investor_pan": null,
  "primary_investor_old_id": 109,
  "second_investor_old_id": null,
  "third_investor_old_id": null,
  "holding_pattern": "single",
  "created_at": "2020-04-06T15:32:52+05:30"
}

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account_id	yes	string	V2 or V1 id of the investment account

List all mf investment accounts

GET /v2/mf_investment_accounts

curl -X GET "https://s.finprim.com/v2/mf_investment_accounts"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response:

{
  "object": "list",
  "data": [
    {
      "object": "mf_investment_account",
      "id": "mfia_14bafabfbfbc423d9b54412dd577981b",
      "old_id": 110,
      "primary_investor_pan": "ACCPP55K7L",
      "second_investor_pan": null,
      "third_investor_pan": null,
      "primary_investor_old_id": 109,
      "second_investor_old_id": null,
      "third_investor_old_id": null,
      "holding_pattern": "single",
      "created_at": "2020-04-06T15:32:52+05:30"
    },
    {
      "object": "mf_investment_account",
      "id": "mfia_24bafbbfbfbc423d9b54412dc57a9a11",
      "old_id": 111,
      "primary_investor_pan": "PCCPK55K7L",
      "second_investor_pan": null,
      "third_investor_pan": null,
      "primary_investor_old_id": 112,
      "second_investor_old_id": null,
      "third_investor_old_id": null,
      "holding_pattern": "single",
      "created_at": "2020-04-06T15:32:52+05:30"
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
primary_investor_pan	no	string	Filter by primary investor pan.
second_investor_pan	no	string	Filter by second investor pan.
third_investor_pan	no	string	Filter by third investor pan.
holding_pattern	no	string	Filter by holding_pattern of investment account.
investor	no	string	Accepts a PAN as a value. Using this option, you can filter all the investment accounts in which this PAN is present either as primary, secondary or third investor

Note:

The response contains maximum of 100 mf investment accounts ordered by the created date

Introduction to MF Orders

Overview

At a fundamental level, FP supports 3 types of mutual fund orders viz. mf_purchase,mf_redemption, and mf_switch. You can generate these orders explicitly or you can use purchase plans, redemption plans or switch plans to generate these orders periodically. There are certain aspects that are common to any type of order. The following section covers such general aspects of any mutual fund order.

Also, any order is always created against an investment account. This means that before creating an order you have to ensure that investment account is present. You can use create investment account API to create an investment account.

Order States

State	Remarks
pending	The order is created, but it is not yet ready for submission.
confirmed	A confirmed order is an order which is ready to be submitted to order gateway(rta or bse), and will be eventually submitted to the order gateway by FP.
submitted	The order has been submitted to the order gateway.
successful	The order has been successfully processed by the order gateway.
failed	The order is marked as failed.
cancelled	The order has been explicitly canceled from processing by the user.
reversed	A previously successful order has been reversed by the order gateway for some reason. Changes in units will be reversed in such cases.

Order Expiry

An order which is in pending state will be marked as failed if the order is not marked as confirmed within a specified time.

Order type	Expiry after
mf_purchase	T+7 working days(Order will be expired on T+8)
mf_redemption	T+1 working day(Order will be expired on T+2)
mf_switch	T+1 working day(Order will be expired on T+2)

Note:
T is the day on which the order is supposed to be submitted to the order gateway. Each order will expose this date via the scheduled_on attribute.

Frequently Asked Questions(FAQs)

1) Are order creation APIs idempotent?

Order creation APIs are not idempotent. This means that if you create two orders with same parameters again, the second order will also be treated as a new order. However, every order has a source_ref_id attribute. This is an optional but unique field. While creating an order, you can set a unique value for each order. This means that if you try to create two orders with same source_ref_id, only the first order will succeed and the second order will fail with a validation error.

2) How do I handle situations where there is a request timeout while creating an order using V2 apis?

Please note that this will not happen in general. However, in exceptional cases, if this happens, you wouldn't know whether the order is created or not. This scenario can arise even if we have sent the response and you have failed to process the response due to some error. There are two possible ways to handle such scenarios.

You can ignore the previous attempt to create an order and you can create a new order again. If you do this, if an order was created earlier via the request that timedout, such an order will auto expire according to order expiry schedule.

You can always set source_ref_id and pass a unique value while creating order. This way, when you try to create the same order again, you will get an error. If there was no order with same source_ref_id, a new order will be created.

3) How do I handle situations where there is a request timeout while confirming an order using V2 apis?

You can fetch an order using its id and you can check the order status. Only if the order is in pending state, you can try to confirm the order again. If you try to confirm an already confirmed order, you will get a validation error.

MF Purchases

Represents a mutual fund purchase order. The purchase order can be a lump sum purchase order or it can be a purchase order created via a purchase plan.

Endpoints:

POST /v2/mf_purchases
PATCH /v2/mf_purchases
GET /v2/mf_purchases/:id
GET /v2/mf_purchases POST /v2/mf_purchases/:id/retry

MF Purchase Object

{
  "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,
  "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,
  "distributor_id": null,
  "failure_code": null,
  "type": "additional_purchase",
  "allotted_units": null,
  "purchased_amount": null,
  "purchased_price": null,
  "confirmed_at": null
}

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 id is the V1 id of this purchase object. We have provided this id for backward compatibility purposes, and you can use this id in V1 APIs. However, please use V2 object ids and V2 APIs wherever possible
mf_investment_account	string	This id is the V2 id of the investment account, and you can identify the investment account associated with the purchase order using this id
folio_number	string	This value represents the mutual fund folio number. Using the folio number, you can determine the folio 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: pending, confirmed, sumitted, successful, failed, cancelled, reversed
amount	decimal	Purchase amount in Rupees
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 V2 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(bse or rta) for processing
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 is created
confirmed_at	string	The time at which the order is confirmed
submitted_at	string	The time at which the order is submitted to the order gateway
succeeded_at	string	The time at which the order is processed successfully
failed_at	string	The time at which the order is failed
retried_at	string	The time at which the order is last retried
reversed_at	string	The time at which the order is reversed
gateway	string	The gateway through which the order was submitted for processing. Possible values: rta, ,bse
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 end user who has initiated the transaction.
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.
distributor_id	string	The id of the distributor/ria associated with the purchase order.
failure_code	string	Failure code of the failed purchase order. Possible values: payment_failure,order_expiry,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

Create a MF Purchase

POST /v2/mf_purchases

Note:

When you create an order using Create mf_purchase order API, the order will be in the pending state. However, the orders would get submitted to the order gateway only after you mark the order as confirmed. You can use our Update mf_purchase order API to mark an order as confirmed. If you are routing orders via RTA and if you are using our payments API to make payments for orders, orders will get marked as confirmed upon successful payment by FP. In such cases, you need not mark the order as confirmed explicitly. BSE orders will be submitted only if they are marked as confirmed.

An order which is in pending state will be marked as failed due to inactivity after T+1 market day post RTA order submission cut-off time, if the order is not confirmed within this duration.

curl -X POST "https://s.finprim.com/v2/mf_purchases"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "mf_investment_account": "mfia_367a75826694614a539c0f82b196027",
  "scheme": "INF173K01FE6",
  "folio_number": "31171511",
  "amount": 10000,
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "source_ref_id": "71312fdc-b2da-46ca-90a3-c3d9b99bfca0",
  "euin": null
}

JSON Response:

{
  "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,
  "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,
  "distributor_id": null,
  "failure_code": null,
  "type": "additional_purchase",
  "allotted_units": null,
  "purchased_amount": null,
  "purchased_price": null,
  "confirmed_at": null
}

Request Parameters

Name	Mandatory	Type	Comments
mf_investment_account	yes	string	Provide the V2 id of the investment account against which this order must be placed.
scheme	yes	string	Provide the isin of the scheme for which this order must be placed.
folio_number	no	string	Provide the folio number mapped against the investment account if you want to make an additional purchase against a folio.
amount	yes	integer	Provide purchase amount in Rupees. if In case of fresh purchases, the amount should be between min_initial_investment and max_initial_investment and should be a multiple of initial_investment_multiples In case of additional purchases, the amount should be between min_additional_investment and max_additional_investment and should be a multiple of additional_investment_multiples Each scheme has different initial investment amount constraints or additional investment constraints. You can fetch scheme details using Fund Scheme Details API to know the values for such constraints.
user_ip	no	string	Provide IP address of the end-user.
server_ip	no	string	Provide IP address of the server through which the request to create this order is made.
source_ref_id	no	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).
euin	no	string	Provide EUIN associated with the distributor through which the order is being placed.

Update a MF Purchase

PATCH /v2/mf_purchases

If active order gateway is rta, mf_settlement_details should be present before purchase order confirmation.

curl -X PATCH "https://s.finprim.com/v2/mf_purchases"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "id": "mfp_177177219f634373b01072986d2eea7d",
  "state": "confirmed"
}

JSON Response:

{
  "object": "mf_purchase",
  "id": "mfp_177177219f634373b01072986d2eea7d",
  "old_id": 9123,
  "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
  "folio_number": "39171511",
  "state": "confirmed",
  "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,
  "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,
  "distributor_id": null,
  "failure_code": null,
  "type": "additional_purchase",
  "allotted_units": null,
  "purchased_amount": null,
  "purchased_price": null,
  "confirmed_at": "2020-04-06T20:32:52+05:30"
}

Request Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 Id of the purchase order.
state	yes	string	New state of the purchase order. Supported values: confirmed

Fetch a MF Purchase

GET /v2/mf_purchases/:id

curl -X GET "https://s.finprim.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch a given purchase order by its identifier.

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 or V1 id of the purchase order.

JSON Response:

{
  "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,
  "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,
  "distributor_id": null,
  "failure_code": null,
  "type": "additional_purchase",
  "allotted_units": null,
  "purchased_amount": null,
  "purchased_price": null,
  "confirmed_at": null
}

List all MF Purchases

GET /v2/mf_purchases

curl -X GET "https://s.finprim.com/v2/mf_purchases"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API used to fetch all purchase orders.

JSON Response:

{
  "object": "list",
  "data": [
    {
      "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,
      "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,
      "distributor_id": null,
      "failure_code": null,
      "type": "additional_purchase",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null,
      "confirmed_at": null
    },
    {
      "object": "mf_purchase",
      "id": "mfp_266177219f634373b01072986d2eea4d",
      "old_id": 9123,
      "mf_investment_account": "mfia_177a85826694614a531c0f82b196022",
      "folio_number": "11171611",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF373K01FE1",
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2020-02-07",
      "created_at": "2020-03-06T15:32:52+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "retried_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": "mobile_app",
      "euin": null,
      "distributor_id": null,
      "failure_code": null,
      "type": "additional_purchase",
      "allotted_units": null,
      "purchased_amount": null,
      "purchased_price": null,
      "confirmed_at": null
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account	no	string	The investment account against which the purchases are made.

Note:

The response can contain 100 latest orders at max.

Retry MF Purchase

POST /v2/mf_purchases/:id/retry

curl -X POST "https://s.finprim.com/v2/mf_purchases/mfp_177177219f634373b01072986d2eea7d/retry"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API used to retry failed order, after retrying the order will be eligible to make payment again.

Note:

Can be used only when gateway provider is RTA and order has failed due to payment failure i.e. failure_code is payment_failure

JSON Response:

{
  "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,
  "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,
  "distributor_id": null,
  "failure_code": null,
  "type": "additional_purchase",
  "allotted_units": null,
  "purchased_amount": null,
  "purchased_price": null,
  "confirmed_at": null
}

Mf Redemptions

Represents a mutual fund sell order. You can create a redemption order via Create Redemption order API or the redemption order can be created via a redemption plan.

Endpoints:

POST /v2/mf_redemptions
PATCH /v2/mf_redemptions
GET /v2/mf_redemptions/:id
GET /v2/mf_redemptions

MF Redemption Object

{
  "object": "mf_redemption",
  "id": "mfr_15f8d86bae614801bab5accaed131abc",
  "old_id": 6597,
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "state": "pending",
  "amount": 10000.0,
  "scheme": "INF173K01FQ0",
  "redemption_mode": "normal",
  "traded_on": null,
  "failed_at": null,
  "plan": null,
  "euin": null,
  "distributor_id": null,
  "units": null,
  "redeemed_price": null,
  "redeemed_units": null,
  "redeemed_amount": null,
  "redemption_bank_account_number": null,
  "redemption_bank_account_ifsc_code": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-07T14:50:23+05:30",
  "confirmed_at": null,
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "gateway": "rta",
  "initiated_by": "investor",
  "initiated_via": "web",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1"
}

Attribute	Type	Comments
object	string	Value is mf_redemption. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the mf_redemption object
old_id	integer	This id is the V1 id of this redemption object. We have provided this id for backward compatibility purposes, and you can use this id in V1 APIs. However, please use V2 object ids and V2 APIs wherever possible
mf_investment_account	string	This id is the V2 id of the investment account, and you can identify the investment account associated with the redemption order using this id
folio_number	string	This value represents the mutual fund folio number. Using the folio number, you can determine the folio in which the investor has made the redemption.
state	string	State of the redemption order. Possible values: pending, confirmed, sumitted, successful, failed, cancelled, reversed
amount	decimal	You can create a redemption order for a particular amount or you can create a redemption order for a particular number of units. If the redemption order was created for a specific amount, the value will not be empty. It will be empty otherwise. Please note that if the redemption amount and units are both empty, the entire holding amount would be redeemed upon successful processing of the order.
units	decimal	You can create a redemption order for a particular amount or you can create a redemption order for a particular number of units. If the redemption order was created to redeem a certain number of units, the value will not be empty. It will be empty otherwise. Please note that if the redemption amount and units are both empty, the entire holding amount would be redeemed upon successful processing of the order.
redeemed_amount	decimal	The actual amount that was redeemed.
redeemed_units	decimal	The actual number of units that were deducted from the investors holdings after the redemption order was processed by the order gateway.
redeemed_price	decimal	The NAV at which the redemption order was processed.
scheme	string	The isin of the scheme from which the redemption has to be made.
plan	string	The V2 object id of the plan with which this rdemption is associated. This value will be available only if this redemption order is created by a plan.
scheduled_on	string	The date on which the order is scheduled for submission to the order gateway(bse or rta) for processing.
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.
redemption_mode	string	Mode of redemption: normal: In this mode, FP sends orders via order gateway as it does for other types of orders. Usually, the investor will receive the redemption proceeds in the bank account after two to three working days depending on TAT for redemption proceeds defined by AMCs. You can place redemption orders for any schemes(including liquid funds) in this mode. instant: This mode is only applicable for liquid fund schemes and the investor will receive the redemption proceeds in the bank account instantly on successfully placing the redemption order. This mode is currently supported by a few AMCs as of now. Click here to know more
redemption_bank_account_number	string	This value indicates the bank account number in which the instant redemption proceeds have been deposited. This value will be null if the redemption mode is normal.
redemption_bank_account_ifsc_code	string	This value indicates the IFSC code of the bank account in which the instant redemption proceeds have been deposited. This value will be null if the redemption mode is normal.
created_at	string	The time at which the order is created
confirmed_at	string	The time at which the order is confirmed
submitted_at	string	The time at which the order is submitted to the order gateway
succeeded_at	string	The time at which the order is processed successfully
failed_at	string	The time at which the order is failed
reversed_at	string	The time at which the order is reversed
gateway	string	The gateway through which the order was submitted for processing. Possible values: rta, ,bse
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 end user who has initiated the transaction.
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.
distributor_id	string	The id of the distributor/ria associated with the redemption order.
initiated_by	string	The entity/person who has initiated this redemption. 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

Create a MF Redemption

POST /v2/mf_redemptions

Note:

When you create a mf_redemption order, the order will be in the pending state. However, the orders would get submitted to the order gateway only after you mark the order as confirmed. You can use Update mf_redemption order API to mark the order as confirmed.

An order which is in pending state will be marked as failed due to inactivity after T+1 market day post RTA order submission cut-off time, if the order is not confirmed within this duration.

curl -X POST "https://s.finprim.com/v2/mf_redemptions"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "amount": 10000,
  "scheme": "INF173K01FQ0",
  "units": null,
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "source_ref_d": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "euin": null
}

JSON Response:

{
  "object": "mf_redemption",
  "id": "mfr_15f8d86bae614801bab5accaed131abc",
  "old_id": 6597,
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "state": "pending",
  "amount": 10000.0,
  "scheme": "INF173K01FQ0",
  "redemption_mode": "normal",
  "traded_on": null,
  "failed_at": null,
  "plan": null,
  "euin": null,
  "distributor_id": null,
  "units": null,
  "redeemed_price": null,
  "redeemed_units": null,
  "redeemed_amount": null,
  "redemption_bank_account_number": null,
  "redemption_bank_account_ifsc_code": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-07T14:50:23+05:30",
  "confirmed_at": null,
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "gateway": "rta",
  "initiated_by": "investor",
  "initiated_via": "web",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1"
}

Request Parameters

Name	Mandatory	Type	Comments
mf_investment_account	yes	string	Provide the V2 id of the investment account against which this order must be placed.
scheme	yes	string	Provide the isin of the scheme for which this order must be placed
folio_number	yes	string	Provide the folio number mapped with the investment account against which order must be placed.
amount	no	integer	Provide redemption amount in Rupees. The amount should be between min_withdrawal_amount and max_withdrawal_amount and should be a multiple of withdrawal_multiples If the redemption amount and units are both empty, the entire holding amount would be redeemed upon successful processing of the order. Note : You can use Get holdings Report API to check the maximum redeemable amount for a given folio and a scheme.
units	no	decimal	Provide the number of units that you want to redeem The units should be between min_withdrawal_units and max_withdrawal_units and should be a multiple of withdrawal_multiples_units If the redemption amount and units are both empty, the entire holding amount would be redeemed upon successful processing of the order. Note : You can use Get holdings Report API to check the maximum redeemable units for a given folio and a scheme.
user_ip	no	string	Provide IP address of the end-user.
server_ip	no	string	Provide IP address of the server through which the request to create this order is made.
source_ref_id	no	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).
euin	no	string	Provide EUIN associated with the distributor through which the order is being placed.

Update a MF Redemption

PATCH /v2/mf_redemptions

curl -X PATCH "https://s.finprim.com/v2/mf_redemptions"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "id": "mfr_15f8d86bae614801bab5accaed131abc",
  "state": "confirmed"
}

JSON Response:

{
  "object": "mf_redemption",
  "id": "mfr_15f8d86bae614801bab5accaed131abc",
  "old_id": 6597,
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "state": "confirmed",
  "amount": 10000.0,
  "scheme": "INF173K01FQ0",
  "redemption_mode": "normal",
  "traded_on": null,
  "failed_at": null,
  "plan": null,
  "euin": null,
  "distributor_id": null,
  "units": null,
  "redeemed_price": null,
  "redeemed_units": null,
  "redeemed_amount": null,
  "redemption_bank_account_number": null,
  "redemption_bank_account_ifsc_code": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-07T14:50:23+05:30",
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "gateway": "rta",
  "initiated_by": "investor",
  "initiated_via": "web",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1"
}

Request Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 Id of the redemption order
state	yes	string	New state of the redemption order. Supported values: confirmed

Fetch a MF Redemption

GET /v2/mf_redemptions/:id

curl -X GET "https://s.finprim.com/v2/mf_redemptions/mfr_15f8d86bae614801bab5accaed131abc"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch a given redemption order by its V2 identifier

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 or V1 id of the redemption order.

JSON Response:

{
  "object": "mf_redemption",
  "id": "mfr_15f8d86bae614801bab5accaed131abc",
  "old_id": 6597,
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "state": "pending",
  "amount": 10000.0,
  "scheme": "INF173K01FQ0",
  "redemption_mode": "normal",
  "traded_on": null,
  "failed_at": null,
  "plan": null,
  "euin": null,
  "distributor_id": null,
  "units": null,
  "redeemed_price": null,
  "redeemed_units": null,
  "redeemed_amount": null,
  "redemption_bank_account_number": null,
  "redemption_bank_account_ifsc_code": null,
  "scheduled_on": "2020-04-07",
  "created_at": "2020-04-07T14:50:23+05:30",
  "confirmed_at": null,
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "gateway": "rta",
  "initiated_by": "investor",
  "initiated_via": "web",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1"
}

List all MF Redemptions

GET /v2/mf_redemptions

curl -X GET "https://s.finprim.com/v2/mf_redemptions"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch all mf_redemption orders.

JSON Response:

{
  "object": "list",
  "data": [
    {
      "object": "mf_redemption",
      "id": "mfr_15f8d86bae614801bab5accaed131abc",
      "old_id": 6597,
      "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
      "folio_number": "15075102",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF173K01FQ0",
      "redemption_mode": "normal",
      "traded_on": null,
      "failed_at": null,
      "plan": null,
      "euin": null,
      "distributor_id": null,
      "units": null,
      "redeemed_price": null,
      "redeemed_units": null,
      "redeemed_amount": null,
      "redemption_bank_account_number": null,
      "redemption_bank_account_ifsc_code": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-07T14:50:23+05:30",
      "confirmed_at": null,
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "gateway": "rta",
      "initiated_by": "investor",
      "initiated_via": "web",
      "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
      "user_ip": "10.0.128.12",
      "server_ip": "126.1.10.1"
    },
    {
      "object": "mf_redemption",
      "id": "mfr_21f8a86bae614101bab5accaed121abf",
      "old_id": 6597,
      "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
      "folio_number": "15075102",
      "state": "pending",
      "amount": 10000.0,
      "scheme": "INF213K04FQ0",
      "redemption_mode": "normal",
      "traded_on": null,
      "failed_at": null,
      "plan": null,
      "euin": null,
      "distributor_id": null,
      "units": null,
      "redeemed_price": null,
      "redeemed_units": null,
      "redeemed_amount": null,
      "redemption_bank_account_number": null,
      "redemption_bank_account_ifsc_code": null,
      "scheduled_on": "2020-04-07",
      "created_at": "2020-04-07T14:50:23+05:30",
      "confirmed_at": null,
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "gateway": "rta",
      "initiated_by": "investor",
      "initiated_via": "web",
      "source_ref_id": "aad6ca01-a002-46ar-8e1c-ea6fe191a5de",
      "user_ip": "10.1.128.11",
      "server_ip": "122.1.9.1"
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account	no	string	The investment account against which the redemptions are made.
mf_redemption_plan	no	string	Provide a redemption plan id to fetch redemption orders that belong to a particular plan..

Note:

The response can contain 100 latest orders at max.

MF Switches

Represents a mutual fund switch order. You can create a switch order via Create Switch order API or the switch order can be created via a switch plan.

Endpoints:

POST /v2/mf_switches
PATCH /v2/mf_switches
GET /v2/mf_switches/:id
GET /v2/mf_switches

MF Switch Object

{
  "object": "mf_switch",
  "id": "mfs_b1aba06d52184619151d3b82efa65de6",
  "old_id": 16586,
  "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
  "folio_number": "39171511",
  "state": "pending",
  "amount": 1000.0,
  "units": null,
  "switch_out_scheme": "INF173K01FE6",
  "switch_in_scheme": "INF173K02FE5",
  "plan": null,
  "switched_out_units": null,
  "switched_out_amount": null,
  "switched_out_price": null,
  "switched_in_units": null,
  "switched_in_amount": null,
  "switched_in_price": null,
  "gateway": "rta",
  "traded_on": null,
  "scheduled_on": "2021-01-21",
  "created_at": "2021-01-03T19:21:04+05:30",
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "failed_at": null,
  "confirmed_at": null,
  "source_ref_id": null,
  "user_ip": null,
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "web",
  "euin": null,
  "partner": null,
  "failure_code": null
}

Attribute	Type	Comments
object	string	Value is mf_switch. A string representing the object type. Objects of the same type share the same value
id	string	Unique identifier to identify a mf_switch order
old_id	integer	This id is the V1 id of this mf_switch object. We have provided this id for backward compatibility purposes, and you can use this id in V1 APIs. However, please use V2 object ids and V2 APIs wherever possible
mf_investment_account	string	This id is the V2 id of the investment account, and you can identify the investment account associated with the switch order using this id.
folio_number	string	This value represents the mutual fund folio number. Using the folio number, you can determine the folio in which the investor has made the switch from one scheme to another
state	string	State of the switch order Possible values: pending, confirmed, submitted, successful, failed, cancelled, reversed
amount	decimal	The amount of money requested to be switched out from the source scheme during the creation of the switch order
units	decimal	The number of units requested to be switched out from the source scheme during the creation of the switch order
switch_out_scheme	string	The ISIN of the source scheme from which the switch must be made
switch_in_scheme	string	The ISIN of the destination scheme to which the switch must be made
plan	string	The V2 object id of the plan with which this switch is associated. This value will be available only if this switch order is created by a plan
switched_out_units	decimal	The actual number of units that are deducted from the source scheme after the switch order is processed successfully
switched_out_amount	decimal	The actual amount of money that is deducted from the source scheme holdings after the switch order is processed successfully
switched_out_price	decimal	Source scheme NAV which was applied for processing the switch order
switched_in_units	decimal	The actual number of units in the target scheme that are switched after the switch order is processed successfully
switched_in_amount	decimal	The actual amount of money that is invested in the target scheme after the switch order is processed successfully
switched_in_price	decimal	Target scheme NAV which was applied for processing the switch order
scheduled_on	string	The date on which the order will be submitted to the order gateway(BSE or RTA) for further processing
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 is created
confirmed_at	string	The time at which the order is confirmed
submitted_at	string	The time at which the order is submitted to the order gateway
succeeded_at	string	The time at which the order is processed successfully
failed_at	string	The time at which the order is failed
reversed_at	string	The time at which the order is reversed
gateway	string	The gateway through which the order was submitted for processing. Possible values: rta, ,bse
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 end user who has initiated the transaction.
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	The id of the distributor/ria associated with the switch order
failure_code	string	Failure code of the failed purchase order. Possible values: order_expiry 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

Create a MF Switch

POST /v2/mf_switches

Note:

When you create an order using Create mf_switch order API, the order will be in the pending state. However, the orders would get submitted to the order gateway only after you mark the order as confirmed. You can use our Update mf_switch order API to mark an order as confirmed.

An order which is in pending state will be marked as failed due to inactivity after T+1 market day post RTA order submission cut-off time, if the order is not confirmed within this duration.

curl -X POST "https://s.finprim.com/v2/mf_switches"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "amount": 10000,
  "switch_out_scheme": "INF273K01FQ0",
  "switch_in_scheme": "INF171K07FQ0",
  "units": null,
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "source_ref_d": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "euin": null
}

JSON Response:

{
  "object": "mf_switch",
  "id": "mfs_b1aba06d52184619151d3b82efa65de6",
  "old_id": 16586,
  "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
  "folio_number": "39171511",
  "state": "pending",
  "amount": 1000.0,
  "units": null,
  "switch_out_scheme": "INF173K01FE6",
  "switch_in_scheme": "INF173K02FE5",
  "plan": null,
  "switched_out_units": null,
  "switched_out_amount": null,
  "switched_out_price": null,
  "switched_in_units": null,
  "switched_in_amount": null,
  "switched_in_price": null,
  "gateway": "rta",
  "traded_on": null,
  "scheduled_on": "2021-01-21",
  "created_at": "2021-01-03T19:21:04+05:30",
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "failed_at": null,
  "confirmed_at": null,
  "source_ref_id": null,
  "user_ip": null,
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "web",
  "euin": null,
  "partner": null,
  "failure_code": null
}

Request Parameters

Name	Mandatory	Type	Comments
mf_investment_account	yes	string	Provide the V2 id of the investment account against which this order must be placed.
folio_number	yes	string	Provide the folio number mapped against the investment account if you want to make an additional switch against a folio.
switch_out_scheme	yes	string	Provide the isin of the source scheme from which the switch must be made.
switch_in_scheme	yes	string	Provide the isin of the destination scheme to which the switch must be made.
amount	no	integer	Provide redemption amount in Rupees. The amount should be greater than or equals to min_switch_out_amount and should be a multiple of switch_out_amount_multiples If the switch amount and units are both empty, the entire holding amount would be switched upon successful processing of the order. Note : You can use Get holdings Report API to check the maximum switch amount for a given folio and a switch_out_scheme.
units	no	decimal	Provide the number of units that you want to switch The units should be greater than or equals to min_switch_out_units and should be a multiple of switch_out_unit_multiples If the switch amount and units are both empty, the entire holding amount would be switched upon successful processing of the order. Note : You can use Get holdings Report API to check the maximum switchable units for a given folio and a switch_out_scheme.
user_ip	no	string	Provide IP address of the end-user.
server_ip	no	string	Provide IP address of the server through which the request to create this order is made.
source_ref_id	no	string	An identifier that is unique across orders of all types(switches, 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).
euin	no	string	Provide EUIN associated with the distributor through which the order is being placed.

Update a MF Switch

PATCH /v2/mf_switches

curl -X PATCH "https://s.finprim.com/v2/mf_switches"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "id": "mfs_b1aba06d52184619151d3b82efa65de6",
  "state": "confirmed"
}

JSON Response:

{
  "object": "mf_switch",
  "id": "mfs_b1aba06d52184619151d3b82efa65de6",
  "old_id": 16586,
  "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
  "folio_number": "39171511",
  "state": "confirmed",
  "amount": 1000.0,
  "units": null,
  "switch_out_scheme": "INF173K01FE6",
  "switch_in_scheme": "INF173K02FE5",
  "plan": null,
  "switched_out_units": null,
  "switched_out_amount": null,
  "switched_out_price": null,
  "switched_in_units": null,
  "switched_in_amount": null,
  "switched_in_price": null,
  "gateway": "rta",
  "traded_on": null,
  "scheduled_on": "2021-01-21",
  "created_at": "2021-01-03T19:21:04+05:30",
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "failed_at": null,
  "confirmed_at": "2021-01-03T20:32:52+05:30",
  "source_ref_id": null,
  "user_ip": null,
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "web",
  "euin": null,
  "partner": null,
  "failure_code": null
}

Request Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 Id of the switch order.
state	yes	string	New state of the switch order. Supported values: confirmed

Fetch a MF Switch

GET /v2/mf_switches/:id

curl -X GET "https://s.finprim.com/v2/mf_switches/mfs_b1aba06d52184619151d3b82efa65de6"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch a given switch order by its identifier.

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 or V1 id of the switch order.

JSON Response:

{
  "object": "mf_switch",
  "id": "mfs_b1aba06d52184619151d3b82efa65de6",
  "old_id": 16586,
  "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
  "folio_number": "39171511",
  "state": "pending",
  "amount": 1000.0,
  "units": null,
  "switch_out_scheme": "INF173K01FE6",
  "switch_in_scheme": "INF173K02FE5",
  "plan": null,
  "switched_out_units": null,
  "switched_out_amount": null,
  "switched_out_price": null,
  "switched_in_units": null,
  "switched_in_amount": null,
  "switched_in_price": null,
  "gateway": "rta",
  "traded_on": null,
  "scheduled_on": "2021-01-21",
  "created_at": "2021-01-03T19:21:04+05:30",
  "succeeded_at": null,
  "submitted_at": null,
  "reversed_at": null,
  "failed_at": null,
  "confirmed_at": null,
  "source_ref_id": null,
  "user_ip": null,
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "web",
  "euin": null,
  "partner": null,
  "failure_code": null
}

List all MF Switches

GET /v2/mf_switches

curl -X GET "https://s.finprim.com/v2/mf_switches"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API used to fetch all switch orders.

JSON Response:

{
  "object": "list",
  "data": [
    {
      "object": "mf_switch",
      "id": "mfs_b1aba06d52184619151d3b82efa65de6",
      "old_id": 16586,
      "mf_investment_account": "mfia_167a75826694614a539c0f82b196027",
      "folio_number": "39171511",
      "state": "pending",
      "amount": 1000.0,
      "units": null,
      "switch_out_scheme": "INF173K01FE6",
      "switch_in_scheme": "INF173K02FE5",
      "plan": null,
      "switched_out_units": null,
      "switched_out_amount": null,
      "switched_out_price": null,
      "switched_in_units": null,
      "switched_in_amount": null,
      "switched_in_price": null,
      "gateway": "rta",
      "traded_on": null,
      "scheduled_on": "2021-01-21",
      "created_at": "2021-01-03T19:21:04+05:30",
      "succeeded_at": null,
      "submitted_at": null,
      "reversed_at": null,
      "failed_at": null,
      "confirmed_at": null,
      "source_ref_id": null,
      "user_ip": null,
      "server_ip": null,
      "initiated_by": "investor",
      "initiated_via": "web",
      "euin": null,
      "partner": null,
      "failure_code": null
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account	no	string	The investment account against which the switch orders are made.

Note:

The response can contain 100 latest orders at max.

MF Settlement Details

MF Settlement object capture the details of money transfer from investor's bank account to the AMC's bank account. If you are using FP's payment APIs for payment collection, settlement details are auto captured by FP. However, if you are managing payment collection from your investors by yourselves, you will have to report the settlement details to us so that we can report this information to RTAs and AMCs for compliance and reconcilliation purposes.

Managing payment collection on your own :

a) Create a purchase order.
b) Accept payment from the investor and initiate the transfer of money to AMC's bank account.
c) Capture the transfer initiation details using Create mf settlement details API. Please note that, at this stage, you don't have to share the UTR number and settlement time.
d) Mark the order as confirmed. Without transfer initiation details, purchase orders cannot be marked as confirmed.
e) When the settlement to the AMC's bank account is complete, provide the UTR number and settlement time using Update mf settlement detail API

Endpoints:

POST /v2/mf_settlement_details
GET /v2/mf_settlement_details/:id
GET /v2/mf_settlement_details
PATCH /v2/mf_settlement_details

MF Settlement Detail Object

{
  "object": "mf_settlement_detail",
  "id": "mfsd_3c496b27ece044418e7eda9e101875e1",
  "mf_purchase": "mfp_621f8a91658b41c3b1f41f005dc393b6",
  "utr_number": "UTB123312",
  "bank_account_number": "999900002222",
  "bank_ifsc": "UTIB0003098",
  "bank_name": "AXIS BANK",
  "bank_account_type": "SAVINGS",
  "payment_type": "netbanking",
  "beneficiary_account_number": "1233453",
  "beneficiary_account_title": "PMF MF Collection A/c",
  "beneficiary_bank_name": "Amc Bank Name",
  "settlement_processed_at": "2022-03-17T06:30:09+05:30"
}

Attribute	Type	Comments
object	string	Value is mf_settlement_detail. String representing the object type. Objects of the same type share the same value
mf_purchase	string	The V2 identifier of the purchase order for which these settlement details have been provided
utr_number	string	Unique transaction reference number that can be used to identify the payment that was made to the AMC's bank account against the order
bank_account_number	string	Bank account number of the source bank account from which the investor has made the payment
bank_ifsc	string	IFSC of the branch in which the source bank account,the bank account from which the payment was made, is located
bank_name	string	Name of the bank in which the investor has his source bank account
bank_account_type	string	Source bank account type
payment_type	string	Mode of payment used by the investor to make the payment. Possible values: netbanking, nach, neft, rtgs
beneficiary_account_number	string	AMC's bank account number to which the transfer was made
beneficiary_account_title	string	AMC's bank account name
beneficiary_bank_name	string	Name of the bank in which the AMC has its beneficiary bank account, the bank account to which you have transferred the investor's money.
settlement_processed_at	string	Time at which the settlement is processed

Create a mf settlement detail

POST /v2/mf_settlement_details

curl -X POST "https://s.finprim.com/v2/mf_settlement_details"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "mf_purchase": "mfp_621f8a91658b41c3b1f41f005dc393b6",
  "payment_type": "netbanking",
  "utr_number": "UTB123312",
  "bank_account_number": "999900002222",
  "bank_ifsc": "UTIB0003098",
  "beneficiary_account_number": "1233453",
  "beneficiary_account_title": "PMF MF Collection A/c",
  "beneficiary_bank_name": "Amc Bank Name",
  "settlement_processed_at": "2022-03-17T06:30:09+05:30"
}

JSON Response:

{
  "object": "mf_settlement_detail",
  "id": "mfsd_3c496b27ece044418e7eda9e101875e1",
  "mf_purchase": "mfp_621f8a91658b41c3b1f41f005dc393b6",
  "utr_number": "UTB123312",
  "bank_account_number": "999900002222",
  "bank_ifsc": "UTIB0003098",
  "bank_name": "AXIS BANK",
  "bank_account_type": "SAVINGS",
  "payment_type": "netbanking",
  "beneficiary_account_number": "1233453",
  "beneficiary_account_title": "PMF MF Collection A/c",
  "beneficiary_bank_name": "Amc Bank Name",
  "settlement_processed_at": "2022-03-17T06:30:09+05:30"
}

Request Parameters

Name	Mandatory	Type	Comments
mf_purchase	yes	string	Provide the V2 identifier of the purchase for which this settlement was made
payment_type	yes	string	Provide the payment mode using which the investor made the payment. Possible values: netbanking, nach, neft, rtgs
utr_number	no	string	Provide the unique transaction reference of the transfer made to the AMC
bank_account_number	yes	string	Provide the account number of the investor's bank account from which the payment originated
bank_ifsc	yes	string	Provide the ifsc of the investor's bank account from which the payment originated
beneficiary_account_number	yes	string	Provide the AMC's bank account number to which the transfer was made
beneficiary_account_title	yes	string	Provide the bank account name of the AMC's bank account to which the transfer was made
beneficiary_bank_name	yes	string	Provide the bank name of the AMC's bank account to which the transfer was made
settlement_processed_at	no	string	Provide the settlement timestamp in ISO Local Date Time yyyy-MM-ddThh:mm:ss format

Update a mf settlement detail

PATCH /v2/mf_settlement_details

curl -X PATCH "https://s.finprim.com/v2/mf_settlement_details"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "id": "mfsd_3c496b27ece044418e7eda9e101875e1",
  "utr_number": "UTB123312",
  "settlement_processed_at": "2022-03-17T06:30:09"
}

JSON Response:

{
  "object": "mf_settlement_detail",
  "id": "mfsd_3c496b27ece044418e7eda9e101875e1",
  "mf_purchase": "mfp_621f8a91658b41c3b1f41f005dc393b6",
  "utr_number": "UTB123312",
  "bank_account_number": "999900002222",
  "bank_ifsc": "UTIB0003098",
  "bank_name": "AXIS BANK",
  "bank_account_type": "SAVINGS",
  "payment_type": "netbanking",
  "beneficiary_account_number": "1233453",
  "beneficiary_account_title": "PMF MF Collection A/c",
  "beneficiary_bank_name": "Amc Bank Name",
  "settlement_processed_at": "2022-03-17T06:30:09+05:30"
}

Request Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 id of the settlement detail
utr_number	yes	string	Provide the unique transaction reference of the transfer made to the AMC
settlement_processed_at	yes	string	Provide the settlement timestamp in ISO Local Date Time yyyy-MM-ddThh:mm:ss format

Fetch a mf settlement detail

GET /v2/mf_settlement_details/:id

curl -X GET "https://s.finprim.com/v2/mf_settlement_details/mfsd_3c496b27ece044418e7eda9e101875e1"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch a given settlement detail by its V2 identifier

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	V2 id of the settlement detail.

JSON Response:

{
  "object": "mf_settlement_detail",
  "id": "mfsd_3c496b27ece044418e7eda9e101875e1",
  "mf_purchase": "mfp_621f8a91658b41c3b1f41f005dc393b6",
  "utr_number": "UTB123312",
  "bank_account_number": "999900002222",
  "bank_ifsc": "UTIB0003098",
  "bank_name": "AXIS BANK",
  "bank_account_type": "SAVINGS",
  "payment_type": "netbanking",
  "beneficiary_account_number": "1233453",
  "beneficiary_account_title": "PMF MF Collection A/c",
  "beneficiary_bank_name": "Amc Bank Name",
  "settlement_processed_at": "2022-03-17T06:30:09+05:30"
}

List all mf settlement details

GET /v2/mf_settlement_details

curl -X GET "https://s.finprim.com/v2/mf_settlement_details"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API can be used to fetch a settlement detail for a given purchase order.

Query Parameters

Name	Mandatory	Type	Comments
mf_purchase	yes	string	V2 id of the purchase order.

JSON Response:

{
  "object": "mf_settlement_detail",
  "id": "mfsd_3c496b27ece044418e7eda9e101875e1",
  "mf_purchase": "mfp_621f8a91658b41c3b1f41f005dc393b6",
  "utr_number": "UTB123312",
  "bank_account_number": "999900002222",
  "bank_ifsc": "UTIB0003098",
  "bank_name": "AXIS BANK",
  "bank_account_type": "SAVINGS",
  "payment_type": "netbanking",
  "beneficiary_account_number": "1233453",
  "beneficiary_account_title": "PMF MF Collection A/c",
  "beneficiary_bank_name": "Amc Bank Name",
  "settlement_processed_at": "2022-03-17T06:30:09+05:30"
}

Introduction to MF Plans

Plan Overview

What are transaction plans?

At a fundamental level, FP provides support for 3 types of mutual fund transactions viz mf_purchase,mf_redemption, and mf_switch. While these transactions can be created as and when required, there are cases where investors might want to repeat such transactions in a specific pattern.

If you want to enable such use cases for your investors, you need to create transaction plans. Transaction plans are the blueprints that specify how the transactions must be repeatedly created and processed.

Can you give an example?

Sure. Imagine that an investor wants to invest Rs 1000 in a mutual fund scheme monthly on the 25th of every month, you can create a purchase plan by providing these details, and FP will take care of generating installments according to this schedule.

How do Systematic Plans like SIPs, SWPs, STPs compare to FP Transaction plans?

Let us assume that an investor wants to invest Rs 1000 in a scheme every month on the 25th of every month. There are two ways of solving this problem. You can register a SIP with AMC for the same or you can create a lumpsum purchase every month on 25th and submit it to AMCs. In the former approach, you are informing AMCs in advance about the nature of repetition and in the latter approach, you just submit the transactions repeatedly. In the latter approach, AMCs will not know about the nature of repetition.

Of course, there are pros and cons to both approaches, but the important point to note here is that FP Transaction plans allow you to take any approach to create and process transactions repeatedly.

General behaviors

This section documents certain behaviors that are common to all types of FP Transaction plans. A solid understanding of these behaviors will help you appreciate the semantics of FP Transaction Plans.

Important note: Some of the behaviors might not be supported by certain FP Transaction Plans due to some limitations at the underlying order gateway or some of these behaviors might be different in certain situations. Details about such exceptions can be found in the documentation of specific transaction plans.

Installment type

You can send the installments of a plan to order gateways as a normal order or as a systematic installment. For example, you can create a mf_purchase_plan and send the installments as sysetmatic installments or as normal purchase orders. You can determine the installment type only when you are registering a systematic transaction plan.

Schedule

Plan schedules let you specify how often the transactions should be repeated and how many times a specific transaction should be repeated. Every plan type will have the following schedule attributes.

Related object attributes

Attribute	Data type	Can be null?	Remarks
frequency	string	No	Frequency specifies how often the repetitions must be made. Supported values are DAILY WEEKLY, FORTNIGHTLY, MONTHLY, QUARTERLY, HALF-YEARLY, YEARLY Please see the frequency table below for detailed explanation.
transaction_day	integer	Yes	Specifies the day on which the transaction should be repeated. If the frequency is DAILY, this value is not applicable. However, it is applicable for other frequencies.
requested_activation_date	date	Yes	You can create a plan anytime and choose to activate the plan at a later point in time. In such cases, you have to explicitly request FP to activate a plan on a specific date. The value of this attribute specifies the date on which the activation was requested. This date, if present, will always be greater than the Systematic Transaction Plan creation date.
number_of_installments	integer	No	When the total number of processed installments of a plan reaches number_of_installments, no further installments are generated.
start_date	date	Yes	The date on which the first installment will become available for processing.If auto_generate_installments=true, then, this value will be null.
next_installment_date	date	Yes	This is the date on which the next installment becomes available for processing.If auto_generate_installments=true, then, this value will be null.
previous_installment_date	date	Yes	The date on which the last installment became available for processing.
end_date	date	No	This is the date on which the plan will end and no installment will be generated after this particular date

Plan Frequencies

Frequency	Remarks
daily	Transactions will be processed every business day. Transactions are not processed on market holidays.
weekly	4 installments will be processed per month. The gap between adjacent installments is 1 Week. For example, if transaction_day=10 and frequency=WEEKLY, installments will be processed on 10th, 17th, 24th , and 31st of every month.
fortnightly	2 installments processed per month. The gap between adjacent installments is two weeks. For example, if transaction_day=10 and frequency=FORTNIGHTLY, installments will be processed on 10th, 24th
monthly	1 installment per month. The gap between adjacent installments is one month.
quarterly	1 installment per 3 months. The gap between installments is 3 months. For example, if the first installment is processed on Feb 1, 2022, the second installment will be processed on May 1st, 2022.
half_yearly	1 installment per 6 months. The gap between installments is 6 months. For example, if the first installment is processed on Feb 1, 2022, the second installment will be processed on July 1st, 2022.
yearly	1 installment per year. The gap between installments is 1 year. For example, if the first installment is processed on Feb 1 2022, the second installment will be processed on Feb 1, 2023.

Note

If the SIP frequency is DAILY, the installments are never processed on market holidays. However, if the SIP frequency is a frequency other than DAILY and installment day is not present in the month (example: 31st is not present in Feb) OR installment day is a market holiday, then the installment is processed on the next business day.

end_date and number_of_installments

a) While creating or updating a transaction plan, you can specify either end_date of a transaction plan or number_of_installments, but not both at once. If you specify the end_date, number_of_installments value is derived from the end_date and if you specify the number_of_installments, end_date value is derived from the number_of_installments value.

b) While creating a plan, if installment_type is a normal installment(ex: normal_purchase_installment), the number_of_installments value (provided explicitly or derived from end_date), must be greater than or equal to 1.

c) While creating a plan if installment_type is a systematic installment, the number_of_installments value (provided explicitly or derived from end_date), must be greater than or equal to the minimum number of systematic installments. For example, if you are creating a purchase plan with installment_type =systematic_purchase_installment, the number_of_installments must be greater than or equal to min_sip_installments

d) end_date or number_of_installments of an existing plan can be updated only when a transaction plan is in created, active, or paused state.

e) While modifying an existing plan, the new number_of_installments value must pass all the validations to which the plan is subjected during its creation.

f) While modifying an existing plan, the new number_of_installments value (provided explicitly or derived from end_date) must be greater than or equal to the number of installments generated by the transaction plan.

g) While modifying an existing plan if the new number_of_installments value (provided explicitly or derived from end_date) is equal to the number of installments generated by the transaction plan, the transaction plan is immediately marked as completed if the plan state is active or it will be marked as canceled if the plan state is paused

h) While modifying an existing plan if installment_type is systematic installment, the new number_of_installments value (provided explicitly or derived from end_date) must be less than or equal to the number_of_installments provided during systematic transaction plan creation. For example, if you have created a purchase plan with number_of_installments = 12, you can change the number_of_installments to 9. After that, you can again, increase it to 10. However, you can never increase the value beyond 12.

Installment generation

While creating a plan, you can either ask FP to manage the installment generation or you can choose to generate installment by yourselves. Please note this choice can be made during the registration of a Systematic Transaction Plan.

Related object attributes

Attribute	Data type	Can be null?	Remarks
auto_generate_installments	boolean	No	If true, FP will generate installments periodically according to the frequency. If not, the installment generation is your responsibility

Behavior when FP manages the installment generation

a) The installment will be available on the day of installment irrespective of whether the installment day falls on a market holiday or not, but the installment will not be available before that day. For example, if you have created a monthly SIP with transaction_day=10, and the SIP is registered on Jan 1st, 2022, you can fetch the first installment on Jan 10th, 2022, but the first installment will not be available until Jan 9th, 2022.

b) The installment will be in pending state by default.

c) The first installment will be generated immediately upon the registration of the Systematic Transaction Plan, c.i) If the frequency is DAILY or if the transaction_day equals the registration day of Systematic Transaction Plan AND c.ii) The systematic transaction plan is registered before the cut-off time.

d) Generating the first installment immediately when neither the frequency is DAILY nor the transaction_day equals the registration day of Systematic Transaction Plan :

Sometimes, the transaction_day is not equal to the day of registration, but you may want to process the first installment on the day of registration nevertheless. In such cases, the Systematic Transaction Plans allow you to request installment generation immediately provided following conditions are met.

d.i) You explicitly request FP to generate first installment immediately while creating a Systematic Transaction Plan (Ex: generate_first_installment_now=true) d.ii) You are not requesting delayed registration of a transaction plan. d.iii) frequency is not DAILY

When you manage the installment generation

If you create a systematic transaction plan with auto_generate_installments=false, FP doesn't generate installments. You have to create the installments manually by providing the plan id. Please note that the information required to create the installments may vary depending on the plan type and will be discussed while discussing a specific plan type.

Also, creating installments is similar to creating normal orders like mf_purchase,mf_redemption, or mf_switch. The installment will be submitted to the order gateway only after you create and confirm the installment.

Day of installment confirmation	Cut-off	Installment submission day
Business day(T)	Before cut-off	T day
Business day(T)	After cut-off	T+1 business day
Market holiday(T)	Before cut-off	T+1 business day
Market holiday(T)	Before cut-off	T+1 business day

Note You can create a systematic transaction plan with auto_generate_installments=true only when the installment type is systematic i.e you can't create a plan which generates installments as normal orders(for example: normal purchases as opposed to systematic installments) and manage the installment generation by yourself. If you want to implement such a use case, systematic transaction plans are not required. You can create normal orders directly whenever you want.

Plan States

State	Remarks
created	The plan is created,but Yet to be submitted to order gateway
active	The plan has been registered with order gateway and installments will be generated according to the schedule
paused	Installments will not be processed until the plan becomes active again
cancelled	Plan is cancelled by the user. This is the final state. A plan cannot be modified further. A plan can be canceled by the system too. The plan is canceled by the system because plan has been paused for too long or a paused plan's schedule is completed
completed	Lifecycle complete
failed	Plan activation failed

Allowed state transitions

State	created	active	paused	cancelled	completed	failed
created	NA	yes	no	yes	no	yes
active	no	NA	yes	yes	yes	no
paused	no	yes	NA	yes	no	no
cancelled	no	no	no	NA	no	no
completed	no	no	no	no	NA	no
failed	no	no	no	no	no	NA

Plan activation

When the registration of the plan with order gateway is successful, the plan becomes active. Usually, FP initiates the plan activation process immediately after you create a plan. Depending on the order gateway and certain other limitations, the plan activation might take some time. However, these plan-specific and gateway-specific details are discussed while discussing specific plan types like mf_purchase_plan, mf_redemption_plan etc.

As mentioned earlier, you can also request FP to delay the plan activation when you are creating a plan. In such cases, FP will initiate the plan activation only on the requested activation date. Please note that this feature is available only in cases where you delegate the responsibility of installment generation to FP.

Plan cancellation

a) If a plan is cancelled, no installments against this plan will be/can be generated. b) Cancelling a plan cancels not only the plan but also any installments in of the plan that are in pending state. However, any confirmed installment will be processed. c) Plan cancellation is allowed only when the plan is in created,active, or paused state. d) While cancelling a plan, you can provide cancellation remarks. Otherwise, FP will include a default cancellation remarks.

Pausing a plan

If you want to skip processing installments for a certain period of time, FP has a provision to pause installments using which you can pause plans for a specific period or indefinitely. Only plans which are active can be paused, and only plans which are paused can be resumed.

Request Parameters

Name	Mandatory	Type	Comments
id	Yes	String	V2 id of the systematic transaction plan
pause_from	No	string	By default, the pause_from date will be current date. This date must be in yyyy-dd-mm format and must be greater than or equal to the current date and less than the plan's end_date
pause_till	No	string	This date must be greater than or equal to pause_from date and less than plan's end_date. If the value of this attribute is specified, the plan will be paused till pause_till date and reactivation attempt is made on pause_till + 1 day.
pause_installments	No	int	You can also pause a plan for specific number of installments. The value must be greater than or equal to 1

Note:
a) You can either specify pause_till or pause_installments, but you cannot specify both.
b) If value for neither pause_till nor pause_installments is specified, the plan will be paused indefinitely.
c) If you specify pause_till, pause_installments will be calculated automatically, and if you specify pause_installments, pause_till date will be calculated automatically. Either way, when you pause a systematic transaction plan, validations for both pause_till and pause_installments must be respected.

Pause FAQs

1) Are installments generated when a systematic transaction is paused?

If you delegate the installment generation to FP and if the plan is paused, FP will generate the installment and automatically mark the installment as cancelled. This installment will never be sent to order gateways.

2) Should we pause a plan explicitly if we are generating installments by ourselves?

Yes, We recommend pausing the plan explicitly as we may relay the same information to order gateways internally in some cases.

3) What happens to existing installments when plan is paused?

At the time of pausing sip(the plan pauses on pause_from date given while pausing sip), if there are any pending installments, those will be marked as canceled and a default cancellation reason is populated against those installments. Therefore, if you want to process any pending installments, please confirm these installments before pausing plans

4) What should I know about pausing Systematic transaction plans indefinitely?

If a plan is paused indefinitely, and the plan's end date is elapsed, plan will be marked as canceled automatically. OR if the installments are systematic installments, the plan will be automatically canceled after skipping 3 installments irrespective of whether the plan is past its end date or not.

5) If I am managining installment generation myself, what happens if I try to generate installment against a paused plan?

The installment will be generated and it will be in the cancelled state. In fact, we recommend creating the installment even though the plan is paused because we can know the which installment was skipped and communicate the same to order gateways.

6) Can I cancel a paused plan?

Yes,You can cancel a plan that is paused. The state of the plan will change to canceled.

Resuming a plan

If you have given a specific date till which the plan must be paused or if you have chosen a specific number of installments to skip, FP will try to reactivate the plan automatically after the duration of pause is over. Upon resumption, if it is found out that plan's lifecycle is complete, the plan will be marked as completed. Otherwise, the plan will be marked as active.

On the other hand, if you have paused for an indefinite time or if you have given a specific deadline for pause, but you want to resume the plan earlier, you can explicitly do so by using the following API.

Request Parameters

Name	Mandatory	Type	Comments
id	Yes	String	V2 id of the systematic transaction plan
state	Yes	string	active

Plan completion

When the expected number of installments are generated by a plan, the plan is automatically marked as completed by FP.

Other common plan attributes

Attribute	Data type	Can be null?	Remarks
source_ref_id	string	Yes	An identifier that is unique across orders of all types(purchase_plan, redemption_plan, and switch_plan). 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)
partner	string	No	The id of the distributor/ria associated with the plan.
gateway	string	No	Order gateway. Can be bse or rta
euin	string	Yes	Unique identity number of the employee / relationship manager/ salesperson of the distributor who has advised or interacted with the investor in any other manner for this plan.
user_ip	string	Yes	IP address of end-user who has initiated the transaction.
server_ip	string	Yes	IP address of server through which the request to create this transaction was made.
initiated_by	string	Yes	The entity/person who has initiated this transaction. Possible values: investor, distributor
initiated_via	string	Yes	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

MF Purchase Plans

MF Purchase plan represents a plan defined to create purchase orders on a recurring basis.

Endpoints:

POST /v2/mf_purchase_plans
GET /v2/mf_purchase_plans/:id
GET /v2/mf_purchase_plans
PATCH /v2/mf_purchase_plans

MF Purchase Plan Object

{
  "object": "mf_purchase_plan",
  "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "installment_type": "systematic_withdrawal_installment",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "transaction_day": 1,
  "start_date": "2021-04-01",
  "end_date": "2021-11-01",
  "number_of_installments": 7,
  "next_installment_date": "2021-06-01",
  "previous_installment_date": "2021-05-01",
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2021-04-01T17:51:21+05:30",
  "activated_at": "2021-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null
}

Attribute	Data type	Remarks
object	string	Value is mf_purchase_plan. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the mf_purchase_plan object
old_id	integer	V1 id of a purchase plan
mf_investment_account	string	This id is the V2 id of the investment account, and you can identify the investment account associated with the purchase order using this id
folio_number	string	Indicates the folio in which the purchases resulting from this plan will be made
scheme	string	ISIN of the scheme against whose units must be purchased periodically.
amount	decimal	Periodic purchase amount
installment_type	string	The value of this attribute indicates the way this purchase plan is registered with order gateways. If the value is systematic_purchase_installment, it means that the plan is registered as a Systematic Installment Plan with RTA/BSE and every installment is considered as a traditional sip installment. However, if the value is normal_purchase_installment, it means that FP will create purchase orders according to the defined schedule and send the installments as normal purchase orders to order gateways
frequency	string	Frequency of the purchase plan. Possible values:
transaction_day	integer	Specifies the day on which the transaction should be repeated. If the frequency is DAILY, this value is not applicable. However, it is applicable for other frequencies
requested_activation_date	date	You can create a plan anytime and choose to activate the plan at a later point in time. In such cases, you have to explicitly request FP to activate a plan on a specific date. The value of this attribute specifies the date on which the activation was requested. This date, if present, will always be greater than the Systematic Transaction Plan creation date.
number_of_installments	integer	The values specifies the number of times the purchases must be made
start_date	date	The date on which the first purchase will be processed
end_date	date	This is the date on which the plan will end and no installment will be generated after this particular date
next_installment_date	date	The date on which the next installment will be processed by the order gateway
previous_installment_date	date	The date on which the previous installment was processed by the order gateway
state	string	State of the purchase plan. Possible values
mandate_old_id	integer	FP manadate old id you will get from Fetch a mandate API . more
source_ref_id	string	An identifier that is unique across orders of all types(purchase_plan, redemption_plan, and switch_plan). 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))
partner	string	The id of the distributor/ria associated with the plan
gateway	string	The gateway through which the order was submitted for processing. Possible values: rta,bse
euin	string	Unique identity number of the employee / relationship manager/ salesperson of the distributor who has advised or interacted with the investor in any other manner for this plan
user_ip	string	IP address of end user who has initiated the transaction
server_ip	string	IP address of server through which the request to create this transaction was made
initiated_by	string	The entity/person who has initiated this redemption. 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
created_at	timestamp	The time at which the plan is created
activated_at	timestamp	The time at which the plan is activated
last_paused_at	timestamp	The time when the plan was paused last time
last_resumed_at	timestamp	The time when the plan was resumed last time
cancelled_at	timestamp	The time at which the plan is cancelled
failed_at	timestamp	The time at which the plan is failed
completed_at	timestamp	The time at which the plan is completed
cancellation_reason	string	Reason for cancellation
failure_reason	string	Reason for failure of the plan

Create MF Purchase Plan Request

POST /mf_purchase_plans

curl -X POST "https://s.finprim.com/v2/mf_purchase_plans"
  -H "Authorization: Bearer JWTTOKEN"

REQUEST:

{
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "scheme": "INF173K01FQ0",
  "frequency": "monthly",
  "folio_number": "15075102",
  "amount": 10000,
  "transaction_day": 2,
  "number_of_installments": 12,
  "installment_type": "systematic_purchase_installment",
  "mandate_old_id": 24,
  "auto_generate_installments": true,
  "activate_after": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app"
}

RESPONSE:

{
  "object": "mf_purchase_plan",
  "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "installment_type": "systematic_withdrawal_installment",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "transaction_day": 1,
  "start_date": "2021-04-01",
  "end_date": "2021-11-01",
  "number_of_installments": 7,
  "next_installment_date": "2021-06-01",
  "previous_installment_date": "2021-05-01",
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2021-04-01T17:51:21+05:30",
  "activated_at": "2021-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null
}

Request Parameters

Name	Mandatory	Type	Comments
mf_investment_account	Yes	string	The V2 id of the investment account against which the plan must be created.
scheme	Yes	string	The isin of the scheme against which purchases must be made.
frequency	Yes	string	Provide frequency of the purchase_plan. Possible values: monthly. Please note that the frequencies weekly, fortnightly, and half_yearly are not supported when order gateway is bse and installment_type=systematic_purchase_installment
folio_number	No	string	If the folio number is present, purchases will be made against the given folio. If folio number is not present, the folio number of the folio against which the purchases must be made is decided by the AMC
amount	Yes	decimal	The installment amount. 1) If installment_type = systematic_purchase_installment, amount should be in multiples of sip_multiples and between min_sip_amount and max_sip_amount 2) If installment_type = normal_purchase_installment and folio number is not provided,the amount should be between min_initial_investment and max_initial_investment and should be a multiple of initial_investment_multiples 3) If installment_type = normal_purchase_installment and folio number is provided, the amount should be between min_additional_investment and max_additional_investment and should be a multiple of additional_investment_multiples
transaction_day	No	integer	Specify the day on which the transaction should be repeated. If the frequency is DAILY, this value is not applicable. However, it is applicable for other frequencies
number_of_installments	No	integer	Total number of purchase installemts to be generated.
end_date	No	integer	The day after which no purchase must be made. FP calculates the no_of_installments automatically from the end_date. The date must in yyyy-mm-dd format
installment_type	Yes	string	Must be systematic_purchase_installment or normal_purchase_installment
mandate_old_id	No	integer	If mandate id is provided, the payments for installments will be made via mandates. Please check here for more details
generate_first_installment_now	No	boolean	The value is false by default. This facility is not available when you choose to generate installments by yourself.In other words, if auto_generate_installments=true, this value must be false. See more details here
auto_generate_installments	No	boolean	The facility of installment generation on demand is not available for BSE sips. In other words, when gateway is bse and installment_type=systematic_purchase_installment, this value must be false. By default, the value is true
activate_after	No	string	A date in future on which the registration of this plan must be initiated. This facility is only available when you have delegated the responsibility of installment generation to FP. If you are creating a bse sip(installment_type=systematic_purchase_installment) and generate_first_installment_now=false, if the mandate is not approved at the time of registration, FP waits till the mandate becomes approved, i.e. in such cases SIP registration can happen after the activate_after date.
initiated_by	No	string	The entity/person who has initiated purchases via this plan. Possible values: investor, distributor
initiated_via	No	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
partner	No	string	V2 id of the partner via which this plan is created. Every distributor/ria is given a FP Partner id. This id must be used here. For customers with only one distributor or ria configuration on FP, the default partner id is used by default if no partner id is provided.
euin	No	string	Unique identity number of the employee/relationship manager/ salesperson of the distributor who has advised or interacted with the investor in any other manner for this purchase_plan
user_ip	No	string	Provide IP address of the user who has initiated this plan creation.
server_ip	No	string	Provide IP address of the server through which the request to create this order is made
source_ref_id	No	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).

Automatic payment collection for purchase installments using mandates

You can collect payments for the installments created by MF Purchase Plans yourself or you can delegate that responsibility to FP. FP supports automatic payment collection for MF Purchase plan installments via mandates. To avail this facility, you have to associate a mandate with the purchase plan.

1) If gateway is BSE and installment_type = systematic_purchase_installment, you cannot opt out of the automatic payment collection facility. 2) If gateway is BSE and installment_type = normal_purchase_installment, automatic payment collection facility is not available. 3) If you are managing installment generation by yourselves, you cannot avail this facility. 4) Payments are always created and submitted to payment gateways on the day of installment irrespective of whether that particular day is a market day or not. 5) On the day of the installment if the mandate is yet to be APPROVED, the installment and payment for the installment will be marked as failed

Accepting payment for the first installment on the day of purchase plan creation

To accept the payment for the first installment of the SIP immediately after the SIP creation, the SIP must be created with generate_first_installment_now= true. If this flag is set, FP will generate the first installment immediately after the Purchase plan is created and the first installment will be in a pending state. You can fetch this installment and you can use Create a Payment API or Create a Nach Payment API to create a payment. Please note that even if the mandate is APPROVED during SIP creation, no payment will be created for the first installment that is generated because of generate_first_installment_now=true flag.

Examples (when generate_first_installment_now = true)

SIP Creation day	Start day	First installment date	Second installment date
August 11,2021	10	August 11,2021	October 10,2021
August 11,2021	11	August 11,2021	Septemeber 11,2021
August 11,2021	12	August 11,2021	Septemeber 12,2021
August 11,2021	28	August 11,2021	Septemeber 28,2021

Managing installment generation on your own

For some reason, if you want to generate installments on your own, you can create a purchase plan with auto_generate_installments=true. a) FP will not generate any installments for such plans b) You can only avail this option while creating a purchase plan. You cannot switch to the automatic installment generation facility once you have opted in for this facility. c) You can create an installment by using Create MF Purchase API and providing the V2 purchase plan id and all the purchase-related attribute values like scheme, folio number etc are derived from the purchase plan.

curl -X POST "https://s.finprim.com/v2/mf_purchases"
  -H "Authorization: Bearer ACCESS_TOKEN"

{
    "plan":"mfpp_dbabb25ba34c48329dbfbeff70c846f0"
}

d) The installment number is also calculated automatically. The first generated installment is treated as the first installment and so on. e) The order submission date is calculated just as order submission date is calculated for any normal lump-sum purchase order.

Fetch MF Purchase Plan

GET /v2/mf_purchase_plans/:id

curl -X GET "https://s.finprim.com/v2/mf_purchase_plans/mfpp_a23fa8ac59d54a861396af2193146011"
  -H "Authorization: Bearer JWTTOKEN"

This API used to fetch purchase plan by its id

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	Id of the purchase plan

RESPONSE:

{
  "object": "mf_purchase_plan",
  "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "installment_type": "systematic_withdrawal_installment",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "transaction_day": 1,
  "start_date": "2021-04-01",
  "end_date": "2021-11-01",
  "number_of_installments": 7,
  "next_installment_date": "2021-06-01",
  "previous_installment_date": "2021-05-01",
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2021-04-01T17:51:21+05:30",
  "activated_at": "2021-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null
}

List MF Purchase Plans

GET /v2/mf_purchase_plans

curl -X GET "https://s.finprim.com/v2/mf_purchases"
  -H "Authorization: Bearer JWTTOKEN"

This API used to search mf_purchase_plans.

RESPONSE:

{
  "object": "list",
  "data": [
    {
      "object": "mf_purchase_plan",
      "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "active",
      "installment_type": "systematic_withdrawal_installment",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "transaction_day": 1,
      "start_date": "2021-04-01",
      "end_date": "2021-11-01",
      "number_of_installments": 7,
      "next_installment_date": "2021-06-01",
      "previous_installment_date": "2021-05-01",
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2021-04-01T17:51:21+05:30",
      "activated_at": "2021-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null
    },
    {
      "object": "mf_purchase_plan",
      "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "active",
      "installment_type": "systematic_withdrawal_installment",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "transaction_day": 1,
      "start_date": "2022-01-01",
      "end_date": "2022-07-01",
      "number_of_installments": 7,
      "next_installment_date": "2022-04-01",
      "previous_installment_date": "2022-05-01",
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2021-04-01T17:51:21+05:30",
      "activated_at": "2021-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account	no	string	The investment account against which the purchase plans are created.

Note: The response can contain 100 latest orders at max.

Update a MF Purchase plan

API : PATCH https://s.finprim.com/v2/mf_purchase_plans

Request Parameters

Name	Mandatory	Type	Comments
id	Yes	string	V2 Id of the mf_purchase_plan
state	No	string	Allowed values are a. cancelled(Allowed only when a purchase plan is in active or paused state), b. paused(Allowed only when a purchase plan is in active state), c. active(Allowed only when a purchase plan is in paused state)
cancellation_reason	No	String	The reason for cancelling this purchase plan. This value must be provided only if value of state is cancelled
pause_from	No	string	Value must be provided only if state=paused See here for more details
pause_till	No	string	Value must be provided only if state=paused See here for more details
pause_installments	No	string	Value must be provided only if state=paused See here for more details
mandate_old_id	No	integer	Mandate update is allowed only if a) auto_generate_installments = false AND b) Order gateway is rta Note : a) The new mandate will be used to make payments for only those payments which are scheduled to be made after the change of mandate. b) If you want to stop using mandates for automatic payment collection, please explicitly set the mandate_old_id as null.Any installment generated after this change will be in pending state and no payment collection will happen.
amount	No	decimal	This facility is avaialbe only when installment_type = normal_purchase_installment. The amount validations that are applicable while creating a purchase plan are applicable while updating amount too.Please note that only installments generated after change of amount will have new amount as installment amount.
folio_number	No	string	You can update folio numbers of purchase plans with installment_type = normal_purchase_installment. New installments will be sent with the updated folio number. You can also set the folio_number as null. If folio number is null, AMC allots the folio number for each of the new installments.
number_of_installments	No	integer	See details here
end_date	No	string	See details here

Use cases

Regular SIPs

curl -X POST "https://s.finprim.com/v2/mf_purchase_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

 {
    "mf_investment_account":"mfia_189111b00566431db0dace5332db519c",
    "scheme":"INF173K01FQ0",
    "frequency":"monthly",
    "folio_number":"15075102",
    "amount":10000
    "transaction_day":2
    "number_of_installments":12
    "end_date":null
    "installment_type":"systematic_purchase_installment"
    "mandate_old_id":24
    "generate_first_installment_now":false
    "auto_generate_installments":true
    "activate_after":null
    "initiated_by":"investor"
    "initiated_via":"mobile_app"
    "partner":"mfd_xxxxxx"
    "euin":"E999999"
    "user_ip":null
    "server_ip":null
    "source_ref_id":null
}

Normal lump-sum purchases as SIP installments

curl -X POST "https://s.finprim.com/v2/mf_purchase_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

 {
    "mf_investment_account":"mfia_189111b00566431db0dace5332db519c",
    "scheme":"INF173K01FQ0",
    "frequency":"monthly",
    "folio_number":"15075102",
    "amount":10000
    "transaction_day":2
    "number_of_installments":12
    "installment_type":"normal_purchase_installment"
}

Pause and resuming SIPs

curl -X PATCH "https://s.finprim.com/v2/mf_purchase_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

 {
    "id":"mfpp_189111b00566431db0dace5332db519c",
    "state":"paused",
    "pause_from":"2022-02-01",
    "pause_till":null
    "pause_installments": 2
 }

SIP Topup

At present, you can change plan amount only when installment_type = normal_purchase_installment

curl -X PATCH "https://s.finprim.com/v2/mf_purchase_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

 {
    "id":"mfpp_189111b00566431db0dace5332db519c",
    "amount":1000
 }

SIP without mandates

Create an SIP

curl -X POST "https://s.finprim.com/v2/mf_purchase_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

{
  "mf_investment_account":"mfia_189111b00566431db0dace5332db519c",
  "scheme":"INF173K01FQ0",
  "frequency":"monthly",
  "amount":10000
  "transaction_day":2
  "number_of_installments":12
  "end_date":null
  "installment_type":"systematic_purchase_installment"
  "mandate_old_id":null
}

Daily, run a cron job and fetch installments for which payments must be made

curl -X POST "https://s.finprim.com/v2/mf_purchases/reports/mf_purchase_list"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
      "states" : ["pending"],
      "plans" : ["mfpp_189111b00566431db0dace5332db519c","mfpp_289111b00566431db0dace5332db519c",....]
      "installment_date":"<today>"
  }'

Create payment for each installment according to your preference.

For example:

curl -X POST "{base_url}/api/pg/payments/netbanking"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '
    {
  "amc_order_ids": [
    1,
    2
  ],
  "method":"UPI",
  "bank_account_id":2,
  "payment_postback_url": "https://example.com/"
}

Note: You can also handle payments by yourself.

Don't forget to confirm your order and provide settlement details if you are handling payments by yourself.

curl -X PATCH "https://s.finprim.com/v2/mf_purchases"
  -H "Authorization: Bearer ACCESS_TOKEN"

{
  "id": "mfp_177177219f634373b01072986d2eea7d",
  "state": "confirmed"
}

curl -X POST "https://s.finprim.com/v2/mf_settlement_details"
  -H "Authorization: Bearer ACCESS_TOKEN"

{
  "mf_purchase": "mfp_116a41de7cb243ca8f5eda15c3d8300aa",
  "payment_type": "netbanking",
  "utr_number": "889121212",
  "bank_account_number": "18603051137433",
  "beneficiary_account_number": "1143005051340",
  "beneficiary_account_title": "AMC Mutual Fund Pool AC",
  "settlement_processed_at": "2020-04-09T12:00:09"
}

First order SIPs

Create an SIP

curl -X POST "https://s.finprim.com/v2/mf_purchase_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

{
    "mf_investment_account":"mfia_189111b00566431db0dace5332db519c",
    "scheme":"INF173K01FQ0",
    "frequency":"monthly",
    "folio_number":"15075102",
    "amount":10000
    "transaction_day":2
    "number_of_installments":12
    "installment_type":"systematic_purchase_installment",
    "generate_first_installment_now":true
}

Fetch the first installment

curl -X GET "https://s.finprim.com/v2/mf_purchases?plan=mfpp_189111b00566431db0dace5332db519c"
  -H "Authorization: Bearer ACCESS_TOKEN"

Once you fetch the installment, you can handle payment using FP or by yourself. If you handle the payment, don't forget to to confirm the installment and provide the settlement details.

Cancellation of SIPs

curl -X PATCH "https://s.finprim.com/v2/mf_purchase_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

{
  "id":"mfpp_189111b00566431db0dace5332db519c",
  "state":"cancelled",
  "cancellation_reason":"Cancelling on investor's request"
}

Delayed registration of SIPs

curl -X POST "https://s.finprim.com/v2/mf_purchase_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

{
    "mf_investment_account":"mfia_189111b00566431db0dace5332db519c",
    "scheme":"INF173K01FQ0",
    "frequency":"monthly",
    "amount":10000
    "transaction_day":2
    "number_of_installments":12
    "end_date":null
    "installment_type":"systematic_purchase_installment"
    "mandate_old_id":24,
    "activate_after":"2022-12-01"
}

Changing number of SIP installments

curl -X PATCH "https://s.finprim.com/v2/mf_purchase_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

{
    "id":"mfpp_189111b00566431db0dace5332db519c",
    "number_of_installments":10
}

Changing EUIN

curl -X PATCH "https://s.finprim.com/v2/mf_purchase_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

 {
 "id":"mfpp_189111b00566431db0dace5332db519c",
 "euin":"EXXXXXX"
}

Installment generation on demand

Create a purchase plan with auto_generate_installments=false

curl -X POST "https://s.finprim.com/v2/mf_purchase_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

 {
    "mf_investment_account":"mfia_189111b00566431db0dace5332db519c",
    "scheme":"INF173K01FQ0",
    "frequency":"monthly",
    "folio_number":"15075102",
    "amount":10000
    "transaction_day":2
    "number_of_installments":12
    "end_date":null
    "installment_type":"systematic_purchase_installment"
    "auto_generate_installments":false
}

Create purchase order by providing the V2 plan id

curl -X POST "https://s.finprim.com/v2/mf_purchases"
  -H "Authorization: Bearer ACCESS_TOKEN"

{
      "plan":"mfpp_189111b00566431db0dace5332db519c"
}

Note: The purchase order created will be in a pending state if the plan is active. If the plan is paused, the purchase order created will be in a cancelled state. If the plan is neither active not paused, you will not be allowed to create a purchase order. Once you have created a purchase order, you can confirm the order and provide the settlement details if you are handling the payments by yourself.

Flexi SIP (Coming soon)

Changing SIP installment date (Coming soon)

Mf Redemption Plans

Redemption plan represents a plan defined to create redemption orders on a recurring basis. At present, you can create a redmeption plan to generate redemption orders on a monthly basis.

What is the difference between a redemption plan and a Systematic Withdrawal Plan?

A redemption plan is an FP entity. This entity allows you to define how the redemption orders must be generated on periodic basis. While registering a redemption plan with FP, you can ask FP to register the redemption plan as a Systematic Withdrawal Plan with AMCs. If not, we will not register a Systematic Withdrawal Plan and instead send normal redemption orders(not SWP installments) to RTA/BSE on a periodic basis according to the schedule of the plan. However, at present, any redemption plan defined at FP is always registered as a Systematic Withdrawal Plan with respective order gateways(RTA/BSE).

Endpoints:

POST /v2/mf_redemption_plans
PATCH /v2/mf_redemption_plans
GET /v2/mf_redemption_plans/:id
GET /v2/mf_redemption_plans

MF Redemption Plan Object

{
  "object": "mf_redemption_plan",
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "installment_type": "systematic_withdrawal_installment",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "transaction_day": 1,
  "start_date": "2021-04-01",
  "end_date": "2021-11-01",
  "number_of_installments": 7,
  "next_installment_date": "2021-06-01",
  "previous_installment_date": "2021-05-01",
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2021-04-01T17:51:21+05:30",
  "activated_at": "2021-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null
}

Attribute	Type	Comments
object	string	Value is mf_redemption_plan. String representing the object type. Objects of the same type share the same value
id	string	Unique identifier of the mf_redemption_plan object
state	string	State of the redemption plan. Possible values: created: The plan is created, but it is not active yet. As a user, you don't have to do anything to ensure the plan becomes active. FP will automatically handle the required actions to ensure that the plan becomes active active: Congrats! Your plan is now active and installments will be generated according to the plans schedule paused: The plan was active before. However, the plan has been put on hold temporarily, and installments will not be generated till the plan is in paused state. A paused plan can be made active again and installments will continue once the plan becomes active again. At present, you can't pause a plan cancelled: The plan has been stopped, and no installment will be generated failed: Whoops! We couldn't start a plan i.e. the plan couldn't be made active after it was created completed:The plan has completed its lifecycle, and no installments will be generated after a plan is marked as completed
installment_type	string	The value of this attribute indicates the way this redemption plan is registered with order gateways. If the value is systematic_withdrawal_installment, it means that the plan is registered as a Systematic Withdrawal Plan with RTA/BSE and every installment is considered as a systematic withdrawal installment. However, if the value is normal_redemption_installment, it means that FP will create redemption orders according to the defined schedule and send the installments as normal redemption orders to order gateways At present, only systematic_withdrawal_installment type is supported.
mf_investment_account	string	This id is the V2 id of the investment account, and you can identify the investment account associated with the redemption order using this id
folio_number	string	Indicates the folio in which the withdrawals resulting from this plan will be made
frequency	string	Frequency of the redemption plan. Possible values: monthly
scheme	string	The isin of the scheme from which the redemption wil be made
transaction_day	integer	If the frequency is monthly, the transaction_day specifies the day of the month on which the redemptions should be made
start_date	string	The date on which the first redemption will be processed
end_date	string	This is the date on which the plan will end and no installment will be generated after this particular date
number_of_installments	integer	The values specifies the number of times the redemptions must be made
next_installment_date	string	The date on which the next installment will be processed by the order gateway
previous_installment_date	string	The date on which the previous installment was processed by the order gateway
amount	decimal	Periodic withdrawal amount
source_ref_id	string	An identifier that is unique across orders of all types(purchase_plan, redemption_plan, and switch_plan). 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)
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 redemption_plan
distributor_id	string	The id of the distributor/ria associated with the redemption plan.
created_at	string	The time at which the plan is created
activated_at	string	The time at which the plan is activated
cancelled_at	string	The time at which the plan is cancelled
completed_at	string	The time at which the plan is completed
failed_at	string	The time at which the plan is failed
gateway	string	The gateway through which the order was submitted for processing. Possible values: rta, ,bse
user_ip	string	IP address of end user who has initiated the transaction.
server_ip	string	IP address of server through which the request to create this transaction was made.
initiated_by	string	The entity/person who has initiated this redemption. 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

Create a MF Redemption Plan

POST /v2/mf_redemption_plans

This Endpoint lets you create a redemption plan. When a redemption plan is created, the plan will be in the created state and once the registration is successful internally, the plan moves to the active state. Once you ensure that the plan is in active state, you can fetch the first installment of the plan using API.

Examples to understand when the first redemption plan installment will get processed

Redemption Plan Registration Date	Start day	First installment date
December 2nd, 2021 (Market day)	2	Jan 2nd, 2022(Since it is a Sunday, this installment will be processed on 3rd January.)
December 2nd, 2021 (Market day)	3	December 3rd, 2021(Market day)
December 4th, 2021 (Market holiday)	5	December 5th, 2021(Since it is a Sunday, this installment will be processed on 6th December 2021.)

curl -X POST "https://s.finprim.com/v2/mf_redemption_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Request:

{
  "mf_investment_account": "mfia_189111b00566431db0dace5332db519c",
  "folio_number": "15075102",
  "amount": 10000,
  "scheme": "INF173K01FQ0",
  "frequency": "monthly",
  "transaction_day": 2,
  "number_of_installments": 5,
  "initiated_by": null,
  "initiated_via": null,
  "user_ip": "10.0.128.12",
  "server_ip": "126.1.10.1",
  "source_ref_d": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "euin": null
}

JSON Response:

{
  "object": "mf_redemption_plan",
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "installment_type": "systematic_withdrawal_installment",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "transaction_day": 1,
  "start_date": "2021-04-01",
  "end_date": "2021-11-01",
  "number_of_installments": 7,
  "next_installment_date": "2021-06-01",
  "previous_installment_date": "2021-05-01",
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2021-04-01T17:51:21+05:30",
  "activated_at": "2021-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null
}

Request Parameters

Name	Mandatory	Type	Comments
mf_investment_account	yes	string	Provide the V2 id of the investment account against which this plan must be created
scheme	yes	string	Provide the isin of the scheme from which redemptions must be made
frequency	yes	string	Provide frequency of the redemption_plan. Possible values: monthly
folio_number	yes	string	Provide the folio number of the folio from which the redemption must be made. Please note that this folio number must be mapped against the investment account associated with this redemption plan
amount	yes	integer	Provide redemption amount in Rupees. If the installment_type is systematic_withdrawal_installment the amount should be between min_swp_amount and max_swp_amount and amount should be a multiple of swp_multiples of the scheme from which redemptions must be made. Else, the amount should be between min_withdrawal_amount and max_withdrawal_amount and amount should be a multiple of withdrawal_multiples of the scheme from which redemptions must be made
transaction_day	yes	integer	Specify the day on which the redemption must be made periodically. If the frequency is monthly, every month on the given transaction_day, redemption order will be processed. Please note that if for a given month, the transaction_day falls on a market holiday, the installment will be processed on the immediate market day that comes after the transaction_day. If installment_type is systematic_withdrawal_installment the value of transaction_day must be one of the days supported by the scheme and can be found in swp_frquency_data attribute of a scheme.
number_of_installments	no	integer	Total number of redemptions to be made. You can also specify an end_date instead and no_of_installments will be calculated automatically. Irrespective of whether the no_of_installments value is explicitly specified or implicitly derived from end_date, the no_of_installments must be greater than or equal to min_swp_installments of a scheme if installment_type is systematic_withdrawal_installment. The no_of_installments must be greater than or equal to 1 if installment_type is normal_redemption_installment
end_date	no	integer	The day after which no redemptions must be made. FP calculates the no_of_installments automatically from the end_date. The date must in yyyy-mm-dd format
initiated_by	no	string	The entity/person who has initiated this redemption. Possible values: investor, distributor
initiated_via	no	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
server_ip	no	string	Provide IP address of the server through which the request to create this order is made.
source_ref_id	no	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).
euin	no	string	Provide EUIN associated with the distributor through which the oder is being placed.

Fetch a MF Redemption Plan

GET /v2/mf_redemption_plans/:id

curl -X GET "https://s.finprim.com/v2/mf_redemption_plans/mfrp_dbabb25ba34c48329dbfbeff70c846f0"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch a redemption plan by its id

Query Parameters

Name	Mandatory	Type	Comments
id	yes	string	Id of the redemption plan.

JSON Response:

{
  "object": "mf_redemption_plan",
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "installment_type": "systematic_withdrawal_installment",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "transaction_day": 1,
  "start_date": "2021-04-01",
  "end_date": "2021-11-01",
  "number_of_installments": 7,
  "next_installment_date": "2021-06-01",
  "previous_installment_date": "2021-05-01",
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2021-04-01T17:51:21+05:30",
  "activated_at": "2021-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null
}

List all MF Redemptions Plans

GET /v2/mf_redemption_plans

curl -X GET "https://s.finprim.com/v2/mf_redemption_plans"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch all mf_redemption plans.

JSON Response:

{
  "object": "list",
  "data": [
    {
      "object": "mf_redemption_plan",
      "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "active",
      "installment_type": "systematic_withdrawal_installment",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "transaction_day": 1,
      "start_date": "2021-04-01",
      "end_date": "2021-11-01",
      "number_of_installments": 7,
      "next_installment_date": "2021-06-01",
      "previous_installment_date": "2021-05-01",
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2021-04-01T17:51:21+05:30",
      "activated_at": "2021-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null
    },
    {
      "object": "mf_redemption_plan",
      "id": "mfrp_1ba5b25b534c48329dbfbeff70c846f0",
      "state": "active",
      "installment_type": "systematic_withdrawal_installment",
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "5234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "transaction_day": 1,
      "start_date": "2021-04-01",
      "end_date": "2021-11-01",
      "number_of_installments": 7,
      "next_installment_date": "2021-06-01",
      "previous_installment_date": "2021-05-01",
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "distributor_id": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2021-04-01T17:51:21+05:30",
      "activated_at": "2021-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account	no	string	The investment account against which the redemption plans are created.

Note:

The response can contain 100 latest orders at max.

MF Folios

We offer data migration facilities for AMCs using which demographic information associated with the folios can be imported and accessed via FP APIs. This section describes the data model of a folio and the way to access such information.

Endpoints:

GET /v2/folios

MF Folio Object

{
  "object": "mf_folio",
  "amc": "103",
  "number": "61576584",
  "primary_investor_pan": "EWLPS1890F",
  "secondary_investor_pan": null,
  "third_investor_pan": null,
  "holding_pattern": "single",
  "primary_investor_name": "ANANDHAN S",
  "secondary_investor_name": null,
  "third_investor_name": null,
  "primary_investor_dob": "1993-04-07",
  "secondary_investor_dob": null,
  "third_investor_dob": null,
  "primary_investor_gender": null,
  "secondary_investor_gender": null,
  "third_investor_gender": null,
  "primary_investor_tax_status": "individual",
  "primary_investor_occupation": "service",
  "guardian_name": null,
  "guardian_gender": null,
  "guardian_pan": null,
  "guardian_dob": null,
  "guardian_relationship": null,
  "nominee1": null,
  "nominee1_allocation_percentage": null,
  "nominee2": null,
  "nominee2_allocation_percentage": null,
  "nominee3": null,
  "nominee3_allocation_percentage": null,
  "payout_details": [
    {
      "scheme_code": "FADP",
      "bank_account": {
        "name": null,
        "number": "SB 8132",
        "account_type": "savings",
        "ifsc": null
      }
    }
  ],
  "contact_details": [
    {
      "address": {
        "line1": "D/O LATE SHRI SUBHASH CHANDER CHHABRA",
        "line2": "PATWARIAN WALI BABA NAMDEV NAGAR",
        "line3": "ST NO-3 NR JODIYAN CHAHIYAN",
        "city": "KOTKAPURA",
        "state": "PUNJAB",
        "postal_code": "151204",
        "country_name": null,
        "country_ansi_code": null
      },
      "email": null,
      "mobile": null,
      "type": "correspondence"
    }
  ]
}

Attribute	Type	Comments
object	string	Value is mf_folio. String representing the object type. Objects of the same type share the same value
amc	string	A unique code to identify the AMC to which this folio belongs to
number	string	Folio number
primary_investor_pan	string	PAN of the first holder
secondary_investor_pan	string	PAN of the second holder
third_investor_pan	string	PAN of the third holder
holding_pattern	string	Holding nature of the investment account Possible values: single,joint,either_or_survivor,anyone_or_survivor,first_or_survivor
primary_investor_name	string	Name of the first holder
secondary_investor_name	string	Name of the second holder
third_investor_name	string	Name of the third holder
primary_investor_dob	string	Date of birth of the first holder
secondary_investor_dob	string	Date of birth of the second holder
third_investor_dob	string	Date of birth of the third holder
primary_investor_gender	string	Gender of the first holder
secondary_investor_gender	string	Gender of the second holder
third_investor_gender	string	Gender of the third holder
primary_investor_tax_status	string	Tax status of the first holder Possible values: individual,on_behalf_of_minor,others,nri_minor_nre,nri_minor_nro,qualified_foreign_investor_individual,qualified_foreign_investor_minors
primary_investor_occupation	string	Occupation of the first holder Possible values: business, service, professional,agriculture,retired,house_wife,student,doctor,private_sector_service,public_sector_service,forex_dealer,government_service,unknown_or_not_applicable,others
guardian_name	string	Name of the guardian. Please note that guardian details will be available only if the investor is a minor investor
guardian_gender	string	Gender of the guardian. Possible values: male,female,others
guardian_pan	string	PAN number of the guardian
guardian_dob	string	Date of birth of the guardian
guardian_relationship	string	Relationship of the guardian with primary investor
nominee1	object	Nominee 1 details
nominee1_allocation_percentage	string	Nominee 1 allocation percentage
nominee2	object	Nominee 2 details
nominee2_allocation_percentage	object	Nominee 2 allocation percentage
nominee3	string	Nominee 3 details
nominee3_allocation_percentage	string	Nominee 3 allocation percentage
payout_details	list	List of bank accounts defined at scheme level. These are the bank accounts to which dividend payouts and redemption proceeds will be deposited
contact_details	list	List of contact details

Nominee Detail

Attribute	Type	Comments
name	string	Nominee name
dob	string	Date of birth of the nominee
relationship	string	Relationship of the nominee with the primary investor
guardian	string	Guardian of the nominee in cases where nominee is a minor
guardian_relationship	string	Relationship of the nominee with the guardian

Payout Detail

Attribute	Type	Comments
scheme_code	string	This is unique identifier to identify a scheme in the folio. If there are dividend payouts or redemptions against this particular scheme in the folio, amount would be deposited to the bank account configured against this particular scheme in the folio
bank_account	object	Details of the bank account configured for payout purposes

Bank_Account

Attribute	Type	Comments
name	string	Account holder's name
number	string	Bank account number
account_type	string	Bank account type Possible values: savings,current,nre,nro
ifsc	string	IFSC of the bank branch where the bank account is present

Contact Detail

Attribute	Type	Comments
address	string	Address associated with the folio
email	string	Email address of the user
mobile	string	Mobile number of the user
type	string	Type of the contact details Possible values correspondence ,permanent,overseas

Address

Attribute	Type	Comments
line1	string	Address line one
line2	string	Address line two
line3	string	Address line three
city	string	City name
state	string	State name
postal_code	string	Postal code of the address may be zipcode or pincode
country_name	string	Country name
country_ansi_code	string	ANSI code of the country

List folios

GET /v2/mf_folios

curl -X GET "https://s.finprim.com/v2/mf_folios"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API is used to fetch all mf_folios.

Query Parameters

Name	Mandatory	Type	Comments
mf_investment_account	no	string	V2 id of the investment account
license_code	no	string	ARN or RIA code associated with the transactions in the folio

Note:

The response can contain 100 latest folios at max.

JSON Response:

{
  "object": "list",
  "data": [
    {
      "object": "mf_folio",
      "amc": "103",
      "number": "61576584",
      "primary_investor_pan": "EWLPS1890F",
      "secondary_investor_pan": null,
      "third_investor_pan": null,
      "holding_pattern": "single",
      "primary_investor_name": "ANANDHAN S",
      "secondary_investor_name": null,
      "third_investor_name": null,
      "primary_investor_dob": "1993-04-07",
      "secondary_investor_dob": null,
      "third_investor_dob": null,
      "primary_investor_gender": null,
      "secondary_investor_gender": null,
      "third_investor_gender": null,
      "primary_investor_tax_status": "individual",
      "primary_investor_occupation": "service",
      "guardian_name": null,
      "guardian_gender": null,
      "guardian_pan": null,
      "guardian_dob": null,
      "guardian_relationship": null,
      "nominee1": null,
      "nominee1_allocation_percentage": null,
      "nominee2": null,
      "nominee2_allocation_percentage": null,
      "nominee3": null,
      "nominee3_allocation_percentage": null,
      "payout_details": [
        {
          "scheme_code": "FADP",
          "bank_account": {
            "name": null,
            "number": "SB 8132",
            "account_type": "savings",
            "ifsc": null
          }
        }
      ],
      "contact_details": [
        {
          "address": {
            "line1": "D/O LATE SHRI SUBHASH CHANDER CHHABRA",
            "line2": "PATWARIAN WALI BABA NAMDEV NAGAR",
            "line3": "ST NO-3 NR JODIYAN CHAHIYAN",
            "city": "KOTKAPURA",
            "state": "PUNJAB",
            "postal_code": "151204",
            "country_name": null,
            "country_ansi_code": null
          },
          "email": null,
          "mobile": null,
          "type": "correspondence"
        }
      ]
    }
  ]
}

Reports

FP Reporting framework allows users to access information in an organized tabular format. We have defined a set of standard reports all of which follow a same well defined format. Depending upon the report type, FP also allows you to apply filters on the reports to narrow down the scope of the report information. At present, the maximum number of rows in a report is limited to 2000.

Report object

Attibute	Type	Comments
object	string	The value describes the category of a report. For example, transaction_report is category of reports which are primarily based on MF transactions. There might be multiple different reports under this category.
report	hash	Meta data about the report.
data	hash	Actual report data.
filter_by	hash	Filters applied while retrieving report data.

Report attributes

Attibute	Type	Description
type	string	At present, this will be standard which means that this is a standard report which has been predefined by FP for its users.
standard.name	string	Name of the standard report.
standard.desc	string	Human readable description of the standard report.

Data attributes

You can consider data attribute as an attribute whose value is a table containing the actual report data but in json format. Rows are represented by rows and coloumns are represented by columns

Attibute	Type	Description
rows	array	Each row is an array of values. The position of the value in the array determines the column to which this value belongs to. If there are multiple rows, rows attribute will contain array of such rows.
columns	array	List of column names. The details of the columns are defined the specific reports in detail.

Filter_by attributes

Please refer to specific report types for filter options.

Transaction type wise amount summary report

This report groups the transactions by their type and provides the consolidated amount against each such transaction type.

curl -X POST "https://s.finprim.com/v2/transactions/reports/transaction_type_wise_amount_summary"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
    "partner": "ARN-98783",
    "traded_on_from": "2000-01-01",
    "traded_on_to": "2021-07-07"
  }'

RESPONSE:

{
  "object": "transaction_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "transaction_type_wise_amount_summary",
      "desc": "This report exposes the sum of transaction amount per each transaction type."
    }
  },
  "data": {
    "rows": [
      [
        "redemption",
        4044374.07
      ],
      [
        "switch_out",
        6713373.75
      ],
      [
        "purchase",
        13411292.51
      ],
      [
        "transfer_in",
        42440.77
      ],
      [
        "switch_in",
        7029926.1
      ],
      [
        "dividend_payout",
        185723.7
      ],
      [
        "sip",
        2921466.03
      ]
    ],
    "columns": [
      "type",
      "value"
    ]
  },
  "filter_by": {
    "partner": "ARN-98783",
    "traded_on_from": "2000-01-01",
    "traded_on_to": "2021-07-07"
  }
}

Filter parameters

Name	Mandatory	Type	Comments
partner	No	string	ARN code or RIA code as it appears against the transaction
traded_on_from	No	string	Default value is traded_on_to - 30 days. Date must be in yyyy-mm-dd format. All transactions processed by RTAs on or after the traded_on_from would be considered for creating this report.
traded_on_to	No	string	Default value is current date. Date must be in yyyy-mm-dd format. All transactions processed by RTAs on or before the traded_on_to would be considered for creating this report.

Columns

Column	Type	Description
type	string	Represents transaction type. Transaction types are: purchase, sip, redemption, transfer_in, transfer_out, dividend_reinvestment, dividend_payout, bonus, switch_in, switch_out, demat, remat, pledging, un_pledging, demat_transfer_in, demat_transfer_out Please note that purchase amount includes all purchase transactions including sip installments.
value	decimal	Transaction amount.

Sort order

Transactions are sorted based on the trade date(i.e. the date on which these transactions were processed by RTAs) in descending order.

Fund scheme category wise AUM summary report

This report groups provides the AUM for each fund category

POST /v2/transactions/reports/fund_scheme_category_wise_aum_summary

curl -X POST "https://s.finprim.com/v2/transactions/reports/fund_scheme_category_wise_aum_summary"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
    "partner": "ARN-98783",
    "traded_on_from": "2021-06-01",
    "traded_on_to": "2021-07-07",
  }'

RESPONSE:

{
  "object": "transaction_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "fund_scheme_category_wise_aum_summary",
      "desc": "This report exposed the total AUM at fund scheme category level."
    }
  },
  "data": {
    "rows": [
      [
        "equity",
        102767.44
      ],
      [
        "debt",
        32060.2
      ]
    ],
    "columns": [
      "fund_category",
      "value"
    ]
  },
  "filter_by": {
    "partner": "ARN-98783",
    "traded_on_from": "2021-06-01",
    "traded_on_to": "2021-07-07"
  }
}

Filter parameters

Name	Mandatory	Type	Comments
partner	No	string	ARN code or RIA code as it appears against the transaction
traded_on_from	No	string	If traded_on_from is not specified, all transactions since inception are considered. Date must be in yyyy-mm-dd format. All transactions processed by RTAs on or after the traded_on_from would be considered for creating this report.
traded_on_to	No	string	Default value is current date. The date must be in yyyy-mm-dd format. All transactions processed by RTAs on or before the traded_on_to would be considered for creating this report.

Columns

Column	Type	Description
fund_category	string	Fund category. Possible values: equity debt liquid others
value	decimal	AUM for the fund_category

Sort order

Transactions are sorted based on the trade date(i.e. the date on which these transactions were processed by RTAs) in descending order.

Transaction list report

This report lists the transactions.

POST /v2/transactions/reports/transaction_list

curl -X POST "https://s.finprim.com/v2/transactions/reports/transaction_list"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
    "partner": "ARN-98783",
    "traded_on_to": "2021-08-20",
    "folio_number": "60270555"
  }'

RESPONSE:

{
  "object": "transaction_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "transaction_list",
      "desc": "List transactions matching the given filters."
    }
  },
  "data": {
    "rows": [
      [
        "60270555",
        "Sarath Sandeep",
        "INF173K01940",
        "purchase",
        3499.83,
        17.245,
        "2021-06-28",
        202.95,
        null,
        "103GFGPG",
        "GF60273155SIN825689",
        "GROWTH"
      ],
      [
        "60270555",
        "Sarath Sandeep",
        "INF173K01940",
        "purchase",
        3499.83,
        18.258,
        "2021-05-26",
        191.69,
        null,
        "103GFGPG",
        "GF60273155SIN792153",
        "GROWTH"
      ]
    ],
    "columns": [
      "folio_number",
      "primary_investor_name",
      "isin",
      "type",
      "amount",
      "units",
      "traded_on",
      "traded_at",
      "corporate_action",
      "rta_product_code",
      "rta_order_reference",
      "rta_investment_option"
    ]
  },
  "filter_by": {
    "partner": "ARN-98783",
    "traded_on_to": "2021-08-20",
    "folio_number": "60270555"
  }
}

Filter parameters

Name	Mandatory	Type	Comments
partner	No	string	ARN code or RIA code as it appears against the transaction
traded_on_from	No	string	If traded_on_from is not specified, all transactions since inception are considered. The date must be in yyyy-mm-dd format. All transactions processed by RTAs on or after the traded_on_from would be considered for creating this report.
traded_on_to	No	string	Default value is current date. The date must be in yyyy-mm-dd format. All transactions processed by RTAs on or before the traded_on_to would be considered for creating this report.
primary_investor_name	No	string	Name of the primary investor. Any transactions are done by investors having names that contain primary_investor_name as a substring will be considered in this report. Name matching is case insensitive.
folio_number	No	string	Filter transactions by folio number. The folio number should match exactly as it appears against the transaction
pan_number	No	string	Pan number of the primary investor. An exact case-insensitive match must happen.

Columns

Column	Type
folio_number	string
primary_investor_name	string
isin	string
type	string
amount	decimal
units	decimal
traded_on	string
traded_at	decimal
corporate_action	string
rta_product_code	string
rta_order_reference	string
rta_investment_option	string

Sort order

Transactions are sorted based on the trade date(i.e. the date on which these transactions were processed by RTAs) in descending order.

Investor list report

This report lists the investors.

POST /v2/investors/reports/investor_list

curl -X POST "https://s.finprim.com/v2/transactions/reports/transaction_list"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
      "partner" : "ARN-00341"
  }'

RESPONSE:

{
  "object": "investor_report",
  "report": {
    "type": "standard",
    "standard": {
      "name": "investor_list",
      "desc": "List of investors matching the given filters"
    }
  },
  "data": {
    "rows": [
      [
        "veena.gos@gmail.com",
        "9822222271",
        "Veena Nandlal Goswami",
        "ABBPG3634E"
      ],
      [
        "sujaydey_new@gmail.com",
        "9876789872",
        "SUJAY SARAT DEY",
        "AMMPD2369R"
      ]
    ],
    "columns": [
      "email",
      "mobile",
      "investor_name",
      "pan_number"
    ]
  },
  "filter_by": {
    "partner": "ARN-00341"
  }
}

Filter parameters

Name	Mandatory	Type	Comments
partner	Yes	string	ARN code or RIA of the partner

Columns

Column	Type	Description
email	string	Email id of the investor.
mobile	string	Mobile number of the investor.
investor_name	string	Primary investor name
pan_number	string	Pan number of the primary investor.

Mf Purchase list report

This report lists mf_purchases.

POST /v2/mf_purchases/reports/mf_purchase_list

curl -X POST "https://s.finprim.com/v2/mf_purchases/reports/mf_purchase_list"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
      "states" : ["successful", "submitted"],
      "plan_old_ids" : ["1001"]
  }'

RESPONSE:

{
  "object": "mf_purchase_list",
  "report": {
    "type": "standard",
    "standard": {
      "name": "mf_purchase_list",
      "desc": "List mf_purchases matching the given filters."
    }
  },
  "data": {
    "rows": [
      [
        "mf_purchase",
        "mfp_ad0145004e6949bd92ae41ecfc0ec21b",
        17276,
        "mfia_4742fd0a211b414ba0cae0f2519130f9",
        "62707385",
        "successful",
        1000,
        72.565,
        999.95,
        13.78,
        "INF173K01OW0",
        "additional_purchase",
        "mfpp_c470ab238bcd466cb12c22493e7ad5f0",
        "2021-08-11"
      ],
      [
        "mf_purchase",
        "mfp_142201fcd67d4e4c821bd6dec4ae8c69",
        14153,
        "mfia_4742fd0a211b414ba0cae0f2519130f9",
        "62707385",
        "successful",
        1000,
        75.525,
        999.95,
        13.24,
        "INF173K01OW0",
        "additional_purchase",
        "mfpp_c470ab238bcd466cb12c22493e7ad5f0",
        "2021-07-12"
      ]
    ],
    "columns": [
      "object",
      "id",
      "old_id",
      "mf_investment_account",
      "folio_number",
      "state",
      "amount",
      "allotted_units",
      "purchased_amount",
      "purchased_price",
      "scheme",
      "type",
      "plan",
      "traded_on"
    ]
  },
  "filter_by": {
    "states": [
      "successful",
      "submitted"
    ],
    "plan_old_ids": [
      "1001"
    ]
  }
}

Filter parameters

Name	Mandatory	Type	Comments
ids	No	string[]	IDs of mf purchases.
states	No	string[]	Supportes states are pending, confirmed, submitted, successful, failed, cancelled, refunded and reversed.
plans	No	string[]	V2 id of mf purchase plans.
plan_old_ids	No	string[]	Old IDs of plans.

Columns

Column	Type
object	string
id	string
old_id	integer
mf_investment_account	string
folio_number	string
state	string
amount	decimal
allotted_units	decimal
purchased_amount	decimal
purchased_price	decimal
scheme	string
type	string
plan	string
scheduled_on	string
traded_on	string

Mf Redemption list report

This report lists mf_redemptions.

POST /v2/mf_redemptions/reports/mf_redemption_list

curl -X POST "https://s.finprim.com/v2/mf_purchases/reports/mf_redemption_list"
  -H "Authorization: Bearer JWT_TOKEN"
  -d '{
      "states" : ["successful"],
    "plans" : ["mfrp_1e43165c56114f5989e94df73d28cb7d"]
  }'

RESPONSE:

{
  "object": "mf_redemption_list",
  "report": {
    "type": "standard",
    "standard": {
      "name": "mf_redemption_list",
      "desc": "List mf_redemptions matching the given filters."
    }
  },
  "data": {
    "rows": [
      [
        "mf_redemption",
        "mfr_7e5419b8797a4a3e8e2e03d7c5182c99",
        18187,
        "mfia_5b67630c5d214fcd9b22c1c9b82bf5bd",
        "55719454",
        "successful",
        1500,
        14.555,
        1500.04,
        103.06,
        "INF173K01189",
        "redemption",
        "mfrp_1e43165c56114f5989e94df73d28cb7d",
        "2021-08-20",
        "2021-08-20"
      ],
      [
        "mf_redemption",
        "mfr_afa8763b85a14d87a87a156008578daf",
        18133,
        "mfia_46c668adfb214fd59edcdba3b694a35c",
        "53736674",
        "successful",
        null,
        1276.447,
        215898.27,
        169.14,
        "INF173K01155",
        "redemption",
        "mfrp_1e43165c56114f5989e94df73d28cb7d",
        "2021-08-18",
        "2021-08-18"
      ]
    ],
    "columns": [
      "object",
      "id",
      "old_id",
      "mf_investment_account",
      "folio_number",
      "state",
      "amount",
      "redeemed_units",
      "redeemed_amount",
      "redeemed_price",
      "scheme",
      "type",
      "plan",
      "scheduled_on",
      "traded_on"
    ]
  },
  "filter_by": {
    "states": [
      "successful"
    ],
    "plans": [
      "mfrp_1e43165c56114f5989e94df73d28cb7d"
    ]
  }
}

Filter parameters

Name	Mandatory	Type	Comments
ids	No	string[]	IDs of mf redemptions.
states	No	string[]	Supportes states are pending, confirmed, submitted, successful, failed, cancelled, refunded and reversed.
plans	No	string[]	V2 id of mf redemption plans.
plan_old_ids	No	string[]	Old IDs of plans.

Columns

Column	Type
object	string
id	string
old_id	integer
mf_investment_account	string
folio_number	string
state	string
amount	decimal
redeemed_units	decimal
redeemed_amount	decimal
redeemed_price	decimal
scheme	string
type	string
plan	string
scheduled_on	string
traded_on	string

Transactions

Representation of transactions populated and processed from the RTA reverse feeds which have been uploaded. More information on transaction processing and data points can be found on Technical documentation

APIs:

GET /transactions

Transaction Object

{
  "object": "transaction",
  "folio_number": "1562150537200",
  "isin": "INF760K01100",
  "type": "redemption",
  "amount": 2250,
  "units": 150,
  "traded_on": "2019-01-07",
  "traded_at": 15,
  "order": null,
  "corporate_action": null,
  "related_transaction_id": null,
  "rta_order_reference": "1562150537207",
  "rta_product_code": "101ETGP",
  "rta_investment_option": "GROWTH",
  "rta_scheme_name": "Test Canara Robeco Equity Tax Saver Fund - Regular Growth",
  "sources": [
    {
      "days_held": 7,
      "units": 100,
      "purchased_on": "2019-01-01",
      "purchased_at": 10,
      "gain": 500
    },
    {
      "days_held": 6,
      "units": 50,
      "purchased_on": "2019-01-02",
      "purchased_at": 12,
      "gain": 150
    }
  ]
}

Attribute	Type	Comments
object	string	Value is transaction. String representing the object type. Objects of the same type share the same value.
folio_number	string	Folio number
isin	string	ISIN of the scheme. This can be used to fetch more details about the scheme from Fund schemes end point.
type	string	Transaction type : purchase, redemption, switch_in, switch_out, transfer_in, transfer_out, dividend_payout, dividend_reinvestment, bonus
amount	decimal	Transaction amount
units	decimal	Number of units
traded_on	string	Date on which this transaction happened (yyyy-MM-dd)
traded_at	decimal	NAV at which the trade happened
order	string	This will be null if the order has not been processed through the fintech primitives platform. Else, the value will be the order id.
corporate_action	string	This field will specify the corporate action due to which the transaction happened. If the transaction was user initiated, the value for this attribute will be null. Supported Corporate actions : scheme_merger
related_transaction_id	string	If a transaction is related to another transaction, the id of such transaction will be present here. For example, for a purchase rejection, a related transaction would be the original purchase transaction.
rta_order_reference	string	Order reference number as obtained from the RTA reverse feed.
rta_product_code	string	Scheme product code as obtained from the RTA reverse feed.
rta_investment_option	string	Investment option as obtained from the RTA reverse feed.
rta_scheme_name	string	Scheme name as obtained from the RTA reverse feed.
sources	List	This will be populated in cases of redemption,switch_out or transfer_out transaction types. This attribute will give the information of the purchases from which the redeemed units were sourced from. We follow FIFO logic to populate the source. For example:Let T1 = Purchase of 100 units at NAV=10Rs. T2 = Purchase of 100 units at NAV=15Rs. T3 = Redemption of 150 units at NAV=20Rs. If T3 is concerned, out of the 150 units that were sold, 100 units came from T1 and 50 units came from T2. So, the source of T3 are T1 and T2.

Sources

Attribute	Type	Comments
days_held	Integer	Number of days for which the units were held before being redeemed
units	decimal	Number of units
purchased_on	string	Date of purchase of units (yyyy-MM-dd)
purchased_at	decimal	NAV per unit at which the units were purchased.
gain	decimal	The resulting Gain/Loss because of the redemption. The value will be positive, if there is a gain. If there is a loss, the value will be negative.

List All Transactions

GET /transactions

curl -X GET "https://s.finprim.com/transactions"
  -H "Authorization: Bearer JWTTOKEN"

RESPONSE:

{
  "object": "list",
  "data": [
    {
      "object": "transaction",
      "folio_number": "1562150537200",
      "isin": "INF760K01100",
      "type": "redemption",
      "amount": 2250,
      "units": 150,
      "traded_on": "2019-01-07",
      "traded_at": 15,
      "order": null,
      "corporate_action": null,
      "related_transaction_id": null,
      "rta_order_reference": "1562150537207",
      "rta_product_code": "101ETGP",
      "rta_investment_option": "GROWTH",
      "rta_scheme_name": "Test Canara Robeco Equity Tax Saver Fund - Regular Growth",
      "sources": [
        {
          "days_held": 7,
          "units": 100,
          "purchased_on": "2019-01-01",
          "purchased_at": 10,
          "gain": 500
        },
        {
          "days_held": 6,
          "units": 50,
          "purchased_on": "2019-01-02",
          "purchased_at": 12,
          "gain": 150
        }
      ]
    },
    {
      "object": "transaction",
      "folio_number": "1562150537200",
      "isin": "INF760K01100",
      "type": "purchase",
      "amount": 1200,
      "units": 100,
      "traded_on": "2019-01-02",
      "traded_at": 12,
      "order": null,
      "corporate_action": null,
      "related_transaction_id": null,
      "rta_order_reference": "1562150537202",
      "rta_product_code": "101ETGP",
      "rta_investment_option": "GROWTH",
      "rta_scheme_name": "Test Canara Robeco Equity Tax Saver Fund - Regular Growth",
      "sources": [

      ]
    },
    {
      "object": "transaction",
      "folio_number": "1562150537200",
      "isin": "INF760K01100",
      "type": "purchase",
      "amount": 1000,
      "units": 100,
      "traded_on": "2019-01-01",
      "traded_at": 10,
      "order": null,
      "corporate_action": null,
      "related_transaction_id": null,
      "rta_order_reference": "1562150537201",
      "rta_product_code": "101ETGP",
      "rta_investment_option": "GROWTH",
      "rta_scheme_name": "Test Canara Robeco Equity Tax Saver Fund - Regular Growth",
      "sources": [

      ]
    }
  ]
}

Returns a list of transactions associated with the given folio(s). The transactions are returned, and sorted by transaction date, with the most recent transactions appearing first.

ARGUMENTS

Name	Mandatory	Type	Comments
folios	yes	list	multiple folio_numbers separated by a comma
types	no	list	valid transaction types separated by a comma
from	no	string	from date in yyyy-MM-dd
to	no	string	to date in yyyy-MM-dd

Note:

Following table describes the behavior of API depending on the values of from and to date.

from	to	Behavior
Null	Null	All transactions of the given folio(s) for the current financial year are returned.
Null	Not Null	Transactions starting from an year before to date till to date are returned.
Not Null	Null	All transactions starting from from date till from+1 year are displayed. Note : If from+1 year is greater than current date transactions from from to current date are displayed.
Not Null	Not Null	All transactions in the date range from to to date are displayed. Note : If the date range specified by from and to is greater than an year, it will result in an error.

RESPONSE

A list of transactions sorted by transaction date, with the most recent transactions appearing first.

File Operations

Represents a file operation. File operations are those operations which are performed on a file. A typical file operation workflow starts with a file being uploaded using Create File api. Once a file is uploaded a file operation can be created for this file using the file id obtained after creating a file.

At present transaction_processing file operation type is supported. More Info

APIs:

POST /file_operations

GET /file_operations/{id}

File Operation Object

{
  "object": "file_operation",
  "id": "53307e81-f417-4428-93ad-a855c7c0d962",
  "file": "bf8253b0-c302-4715-974b-87a8d7a9efc3",
  "type": "transaction_processing",
  "status": "processed",
  "processed": 15,
  "failed": 3,
  "succeeded": 12
}

Attribute	Type	Comments
object	string	Value is file_operation. String representing the object type. Objects of the same type share the same value.
id	string	Unique identifier for the file_operation object created
file	string	File id created using create file api.
type	string	Processing will differ based on the type of the file operation. Supported types : transaction_processing
status	string	Status of the file_operation created. Possible status: pending, processed, failed
processed	integer	Number of processed records inside the file object.
failed	integer	Number of records for which processing failed inside the file object.
succeeded	integer	Number of records successfully processed.

Create File Operation

POST /file_operations

curl -X POST "https://s.finprim.com/file_operations"
  -H "Authorization: Bearer JWTTOKEN"
  -d '{json_request}'

REQUEST

{
  "type": "transaction_processing",
  "file": "bf8253b0-c302-4715-974b-87a8d7a9efc3"
}

RESPONSE:

{
  "object": "file_operation",
  "id": "53307e81-f417-4428-93ad-a855c7c0d962",
  "file": "bf8253b0-c302-4715-974b-87a8d7a9efc3",
  "type": "transaction_processing",
  "status": "pending",
  "processed": null,
  "failed": null,
  "succeeded": null
}

Returns a file_operation object holding details of the file operation along with the processed information. Initially once the request to file_operation is submitted, the status will be pending. Eventually the file will be processed in the background. Use the GET api to get further details.

Attributes

Attribute	Mandatory	Type	Comments
type	yes	string	Supported types : transaction_processing
file	yes	string	File id obtained using the Create File api.

RESPONSE

Return the file_operation id along with other data in the object defined.

Get Single File Operation

GET /file_operations/{id}

curl -X GET "https://s.finprim.com/file_operations/{id}"
  -H "Authorization: Bearer JWTTOKEN"

RESPONSE:

{
  "object": "file_operation",
  "id": "53307e81-f417-4428-93ad-a855c7c0d962",
  "file": "bf8253b0-c302-4715-974b-87a8d7a9efc3",
  "type": "transaction_processing",
  "status": "processed",
  "processed": 15,
  "failed": 3,
  "succeeded": 12
}

Returns a file_operation object holding details of the file operation along with the processed information.

ARGUMENTS

Name	Mandatory	Type	Comments
id	yes	string	file_operation id

RESPONSE

Single file_operation object holding details of the status of the file_operation along with details of records processed.

Bank Account Verification ^{(Early Access)}

The primary purpose of FP Bank verification APIs is to provide you with mechanisms to answer following questions

• Does this bank account exists?
• Does this bank account belong to a particular person?

Also, we provide multiple ways of verifying a bank account. Every way of verification has pros and cons of its own. You can incorporate any one of the ways to verify bank accounts or you can incorporate multiple verification mechanisms, to form a robust strategy for verifying bank accounts.

Penny drop verification:

In this type of verification, an attempt is made to deposit a small amount (a random amount between Rs 1 and 2). If the amount can be successfully deposited to the bank account and we receive the transaction reference number for the transaction, we consider the account as an existing account.

If the account exists, we also compare the registered name with bank account against the investo's name and calculate a score. This score tells us how confident are we(on a scale of 1 - 100) about investor's possession of the bank account. If a deposit cannot be made because of invalid account number, invalid ifsc, acccount block, account closure, or unsupported account type, the account_exists will be set as false. If the deposit cannot be made because of issues and banks or NPCI, the verification status will be set as failed.

Note: Once the deposit is successful, you can also ask investor to enter the deposit amount and compare it with the acutal deposit amount to verify whether the investor has access to the bank account statements of the said bank account.

Expiry:

If the verification cannot be carried out within a stipulated amount of time, the verification status will be marked as expired. The expiry time varies depending on the verification type employed and the provider used for verification.

Verification type	Expiry remarks
penny_drop	Depends on the provider used for doing penny drop verification.

Endpoints:

POST /v2/bank_account_verifications

GET /v2/bank_account_verifications/:id

GET /v2/bank_account_verifications

Bank account verification object

{
  "object": "bank_account_verification",
  "id": "bav_1c989d2ecc5b11ec9d640242ac120002",
  "bank_account": "4123",
  "verification_type": "penny_drop",
  "status": "completed",
  "account_exists": "true",
  "account_possession_confidence": "95.30",
  "penny_drop": {
    "expected_first_holder_name": "Ashok kumar",
    "registered_first_holder_name": "Ashok R Kumar",
    "ifsc": "ICIC0002843",
    "account_number": "108903476897",
    "deposit_amount": "1.20",
    "transaction_reference": "AICN0074800897",
    "failure_remarks": null
  },
  "created_at": "2022-02-03T11:30:50+05:30",
  "completed_at": "2022-02-03T11:31:20+05:30",
  "failed_at": null,
  "expired_at": null
}

Attribute	Type	Nullable	Remarks
id	string	no	Unique identifier of the bank account verification transaction
object	string	no	Indicates the type of object. bank_account_verification
bank_account	string	no	Bank account id of the investor
verification_type	string	no	Type of verification to be done on the bank account. Possible values: - penny_drop
status	string	no	The status of the bank account verification. Possible values - pending: Verification request has been registered. -completed:Verification process is completed. Please check account_exists and account_possession_confidence for details. -failed: Attempt to verify bank account failed. -expired: Verification attempt could not be completed on time.
account_exists	boolean	yes	If true, it means that the provided bank account existed(not closed) at the moment of verification. If false, it means that the provided bank account did not exist at the moment of verification. If null it means that, it cannot be determined whether this bank account exists or not.
account_possession_confidence	double	yes	This is the score which tells us how confident are we(on a scale of 1 - 100) about investor's possession of the bank account.
penny_drop	hash	yes	This hash contains details about penny drop verification
created_at	string	no	Verification request creation timestamp
failed_at	string	yes	Failure timestamp
expired_at	string	yes	Expiration timestamp
completed_at	string	yes	Completion timestamp

Penny drop hash

Attribute	Type	Nullable	Remarks
expected_first_holder_name	string	no	The name of the investor against which the the name registered against bank account is compared to
registered_first_holder_name	string	yes	Name registered at bank against the bank account. Value will be present only if account_exists=true
ifsc	string	no	Bank account ifsc
account_number	string	no	Bank account number
deposit_amount	double	yes	Amount deposited in the account.Value will be present only if account_exists=true
transaction_reference	string	yes	Transaction reference number.
failure_remarks	string	yes	Remarks specifying the reason for failure in penny drop verification

Create Bank Verification Transaction

Use the below endpoint to create bank account verification transaction.

curl -X POST "https://s.finprim.com/v2/bank_account_verifications"
  -H "Authorization: Bearer ACCESS_TOKEN"

REQUEST:

{
  "bank_account": "4123",
  "verification_type": "penny_drop"
}

RESPONSE:

{
  "object": "bank_account_verification",
  "id": "bav_1c989d2ecc5b11ec9d640242ac120002",
  "bank_account": "4123",
  "verification_type": "penny_drop",
  "status": "completed",
  "account_exists": "true",
  "account_possession_confidence": "95.30",
  "penny_drop": {
    "expected_first_holder_name": "Ashok kumar",
    "registered_first_holder_name": "Ashok R Kumar",
    "ifsc": "ICIC0002843",
    "account_number": "108903476897",
    "deposit_amount": "1.20",
    "transaction_reference": "AICN0074800897",
    "failure_remarks": null
  },
  "created_at": "2022-02-03T11:30:50+05:30",
  "completed_at": "2022-02-03T11:31:20+05:30",
  "failed_at": null,
  "expired_at": null
}

Request:
POST /v2/bank_account_verifications

Request parameters:

Name	Mandatory	Type	Comments
bank_account	yes	string	At present, this API accepts an id of a bank account created via Create Investor API.
verification_type	yes	string	Allowed values are penny_drop

Fetch all Bank Account Verification Transactions

Use the below endpoint to fetch details of bank account verification transactions based on the filters applied.

GET /v2/bank_account_verifications

curl -X POST "https://s.finprim.com/v2/bank_account_verifications"
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
  "object": "list",
  "data": [
    {
      "object": "bank_account_verification",
      "id": "bav_ce77fcc71b1a48299784b653bd74c0e3",
      "bank_account": "5200",
      "verification_type": "penny_drop",
      "status": "completed",
      "account_exists": "true",
      "account_possession_confidence": "100",
      "penny_drop": {
        "expected_first_holder_name": "Ashok Kumar",
        "registered_first_holder_name": "Ashok Kumar",
        "ifsc": "SBIN0070002",
        "account_number": "700023468248",
        "deposit_amount": "1.45",
        "transaction_reference": "UTR9834599941",
        "failure_remarks": null
      },
      "manual_verification": null,
      "created_at": "2022-04-06T15:32:52+05:30",
      "completed_at": "2022-04-06T15:35:20+05:30",
      "failed_at": null,
      "expired_at": null
    },
    {
      "object": "bank_account_verification",
      "id": "bav_1c989d2ecc5b11ec9d640242ac120002",
      "bank_account": "4123",
      "verification_type": "penny_drop",
      "status": "completed",
      "account_exists": "true",
      "account_possession_confidence": "95.30",
      "penny_drop": {
        "expected_first_holder_name": "Ashok kumar",
        "registered_first_holder_name": "Ashok R Kumar",
        "ifsc": "ICIC0002843",
        "account_number": "108903476897",
        "deposit_amount": "1.20",
        "transaction_reference": "AICN0074800897",
        "failure_remarks": null
      },
      "created_at": "2022-02-03T11:30:50+05:30",
      "completed_at": "2022-02-03T11:31:20+05:30",
      "failed_at": null,
      "expired_at": null
    }
  ]
}

Query Parameters

Name	Mandatory	Type	Comments
statuses	no	string []	Possible Values: - pending - completed - expired - failed.
types	no	string []	Possible Values: - penny_drop
account_number	no	string	Bank account number of the account against which verification attempt was made
ifsc	no	string	IFSC of the account against which verification attempt was made

Fetch Bank Account Verification Transaction by ID

Use the below endpoint to fetch details of the required account validation transaction.

GET /v2/bank_account_verifications/:id

curl -X POST "https://s.finprim.com/v2/bank_account_verifications/bav_1c989d2ecc5b11ec9d640242ac120002"
  -H "Authorization: Bearer ACCESS_TOKEN"

RESPONSE:

{
  "object": "bank_account_verification",
  "id": "bav_1c989d2ecc5b11ec9d640242ac120002",
  "bank_account": "4123",
  "verification_type": "penny_drop",
  "status": "completed",
  "account_exists": "true",
  "account_possession_confidence": "95.30",
  "penny_drop": {
    "expected_first_holder_name": "Ashok kumar",
    "registered_first_holder_name": "Ashok R Kumar",
    "ifsc": "ICIC0002843",
    "account_number": "108903476897",
    "deposit_amount": "1.20",
    "transaction_reference": "AICN0074800897",
    "failure_remarks": null
  },
  "created_at": "2022-02-03T11:30:50+05:30",
  "completed_at": "2022-02-03T11:31:20+05:30",
  "failed_at": null,
  "expired_at": null
}

Path Parameters

Name	Mandatory	Type	Comments
id	yes	string	This is the unique identifier linked to the account validation transaction. For example bav_1c989d2ecc5b11ec9d640242ac120002

Errors

Validation Error:

{
  "error": {
    "status": 400,
    "message": "some description message",
    "errors": [
      {
        "field": "name",
        "message": "validation / error message"
      }
    ]
  }
}

Json Parse Error:

{
  "error": {
    "status": 400,
    "message": "JSON parse error",
    "errors": null
  }
}

Fintech Primitives use standard HTTP error codes. Please refer to HTTP error codes documentation.

All errors will be emitted in the following structure.

attribute	Type	Comments
status	integer	same as http status code
message	string	descriptive message
errors	array of objects	list of errors on each field