NAV Navbar
shell

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

MasterData

Pincode

curl "https://s.finprim.com/api/onb/pincodes/560102"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "code": "560102",
  "city": "Bangalore South",
  "district": "Bangalore",
  "state_name": "Karnataka",
  "country_ansi_code": "IN",
  "_links": [
    {
      "href": "https://s.finprim.com/api/onb/pincodes/560102",
      "rel": "self",
      "method": "GET"
    }
  ]
}

This endpoint retrieves details of the given pincode

HTTP Request

GET https://s.finprim.com/api/onb/pincodes/{pincode}

States

curl "https://s.finprim.com/api/onb/states"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "states": [
    {
      "name": "Karnataka",
      "state_code": "KA",
      "country_ansi_code": "IN"
    }
  ]
}

This endpoint retrieves all states of India which are updated in the system

HTTP Request

GET https://s.finprim.com/api/onb/states

Countries

curl "https://s.finprim.com/api/onb/countries"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "countries": [
    {
      "name": "India",
      "ansi_code": "IN"
    }
  ]
}

This endpoint retrieves the list of countries updated in the system

HTTP Request

GET https://s.finprim.com/api/onb/countries

IFSC

curl "https://s.finprim.com/api/onb/ifsc_code/ICIC0000611"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "ifsc_code": "ICIC0000611",
  "micr_code": "0000000",
  "branch_name": "gudivada",
  "branch_address": "ICICI BANK LTD , D NO-11-218, NENIPLAZA, ELURU ROAD, GUDIVADA. 521301",
  "bank_name": "ICICI",
  "contact": "SUMANTH SAGI 08674-247355",
  "city": "guivada",
  "district": "KRISHNA",
  "state": "ANDHRA PRADESH"
}

This endpoint retrieves details of the given ifsc_code updated in the system

HTTP Request

GET https://s.finprim.com/api/onb/ifsc_codes/{ifsc_code}

Fund Scheme

curl "https://s.finprim.com/api/oms/fund_schemes/{isin}"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "isin": "INF760K01DF2",
  "active": true,
  "name": "Canara Robeco Treasury Advantage Fund - Regular Plan- Weekly Div Reinvest",
  "investment_option": "DIV_REINVESTMENT",
  "min_initial_investment": 500,
  "min_additional_investment": 500,
  "initial_investment_multiples": 1,
  "max_initial_investment": 99999999,
  "max_additional_investment": 99999999,
  "additional_investment_multiples": 1,
  "min_withdrawal_amount": 100,
  "min_withdrawal_units": 1,
  "max_withdrawal_amount": null,
  "max_withdrawal_units": null,
  "withdrawal_multiples": 1,
  "sip_allowed": true,
  "min_sip_amount": 500,
  "max_sip_amount": 99999999,
  "min_sip_installments": 6,
  "sip_multiples": 1,
  "sip_frequency_data": {
    "MONTHLY": "1,5,15,20,25"
  },
  "swp_frequency_data": {
    "MONTHLY": "1,2,3,4,5,6,7,8,9,10,11,12,13,14,15,16,17,18,19,20,21,22,23,24,25,26,27,28"
  },
  "switch_in_allowed": false,
  "switch_in_min_amt": null,
  "switch_multiples": null,
  "fund_category": "DEBT",
  "plan_type": "REGULAR",
  "amfi_code": "109366",
  "sub_category": null,
  "scheme_code": "TASW",
  "close_ended": false,
  "lock_in": false,
  "lock_in_period": null,
  "long_term_period": null,
  "purchase_allowed": true,
  "redemption_allowed": true,
  "insta_redemption_allowed": true,
  "amc_id": 6,
  "rta_id": 2,
  "merged": false,
  "merged_to_isin": null,
  "name_changes": null,
  "swp_allowed": true,
  "min_swp_amount": 100,
  "max_swp_amount": 99999999,
  "min_swp_installments": 12,
  "swp_multiples": 10,
  "_links": {
    "self": {
      "href": "https://s.finprim.com/oms/api/fund_schemes/INF760K01DF2"
    }
  }
}

This endpoint retrieves any particular fund scheme information

HTTP Request

GET https://s.finprim.com/api/oms/fund_schemes/{isin}

AMCs

curl "https://s.finprim.com/api/oms/amcs"
  -H "Authorization: Bearer JWTTOKEN"

The above command returns JSON structured like this:

{
  "_links": {
    "self": {
      "href": "https://s.finprim.com/oms/api/amcs"
    }
  },
  "amcs": [
    {
      "id": 1,
      "name": "Axis MF",
      "active": true,
      "amc_code": null
    }
  ]
}

This endpoint retrieves all the AMCs.

HTTP Request

GET https://s.finprim.com/api/oms/amcs

Authentication

Overview

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

Types of authentication

Endpoints for authentication:

GET /v2/auth/{tenant_name}/auth
POST /v2/auth/{tenant_name}/token

Endpoints for user management:

POST /v2/auth/{tenant_name}/users
GET /v2/auth/{tenant_name}/users/self
PATCH /v2/auth/{tenant_name}/users
GET /v2/auth/{tenant_name}/users/search

Token Object

Token object encapsulates the access_token that is required to access FP APIs. You get a token object after successful authentication(Tenant authentication or Investor authentication or Partner authentication).

{
  "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.

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.

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 \
-H 'accept: application/json' \
-H 'content-type: application/x-www-form-urlencoded' \
-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"
}

Headers

Parameter Mandatory Default value
accept yes - application/json
content-type yes - application/x-www-form-urlencoded

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

Users (Early Access)

For any entity that you wish to authenticate on FP(investor or partner), you need to ensure that there is an account created for that entity at FP Auth server just like you need a Google account before you can login to Google. This account is known as User in FP parlance. This means that before you can authenticate an investor or partner, you have to ensure that there is one User entry for that investor or partner in FP's Auth server.

Endpoints:

POST /v2/auth/{tenant_name}/users
GET /v2/auth/{tenant_name}/users/self
PATCH /v2/auth/{tenant_name}/users
GET /v2/auth/{tenant_name}/users/search

Users Object

{
  "enabled": "true",
  "username": "PAN",
  "firstName": "FN",
  "lastName": "LN",
  "email": "test@cybrilla.com",
  "attributes": {
    "fp_identifier": "1",
    "fp_user_type": "investor",
    "mobile_number": "7777776666",
    "key1": "value1"
  }
}
Parameter Type Comments
enabled boolean It represents status of user
username string Unique username of the user
firstName string First name of user
lastName string Last name of user
email string Email id of the user
attributes hash Attributes contains fp_identifier, fp_user_type and mobile_number. Other than that attributes can accept any key-value pair.

Create User

POST /v2/auth/admin/{tenant_name}/users (Deprecated)

POST /v2/auth/{tenant_name}/users

This API is used to create a user for authentication purpose. You need tenant token obtained via tenant authentication to access this API.

curl -X POST "{baseUrl}/v2/auth/{tenant_name}/users"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request:

{
  "enabled": "true",
  "username": "PAN",
  "firstName": "FN",
  "lastName": "LN",
  "email": "test@cybrilla.com",
  "attributes": {
    "fp_identifier": "1",
    "fp_user_type": "investor",
    "mobile_number": "7777776666",
    "key1": "value1"
  }
}

Headers

Parameter Mandatory Default value
content-type yes - application/json
Authorization yes - Bearer {ACCESS_TOKEN}

Parameters

Parameter Mandatory Default Description
enabled yes - true
username yes - Unique username of the user
firstName optional - First name
lastName optional - Last name
email optional - email
attributes.fp_identifier optinal - This must be FP Investor id if attributes.fp_user_type is investor (use id from response of Create investor)
attributes.fp_user_type yes - investor
attributes.mobile_number yes - This number will be used to send OTP if fp_identifier is not provided.

A note on attributes.fp_identifier : This id uniquely identifies an investor or a partner. This means that this id links a User on FP Auth server with an investor or a partner. The implication of this setup is that if you want to access FP APIs in the context of an investor or a partner, you must ensure that the particular User that you authenticate must be associated with a particular investor or partner so that the token that you get after authentication will have a specifi investor or partner context. If there is no value for attributes.fp_identifier and if you authenticate such users, you will not be able to use such tokens to access FP APIs.

Response 201 is success resposne code

Fetch User

GET /v2/auth/{tenant_name}/users/self

This API is used to fetch a user by its access_token.

curl -X GET '{baseUrl}/v2/auth/{tenant_name}/users/self' \
--H 'Accept: application/json' \
--H 'Content-Type: application/json' \
--H 'Authorization: Bearer ACCESS_TOKEN'

JSON Response:

{
  "id": "8c93ff8e-d36a-457d-a9a8-8e92c693fff3",
  "username": "6",
  "emailVerified": false,
  "userProfileMetadata": {
    "attributes": [
      {
        "name": "username",
        "displayName": "${username}",
        "required": true,
        "readOnly": true,
        "validators": {
        }
      },
      {
        "name": "email",
        "displayName": "${email}",
        "required": true,
        "readOnly": false,
        "validators": {
          "email": {
            "ignore.empty.value": true
          }
        }
      },
      {
        "name": "firstName",
        "displayName": "${firstName}",
        "required": true,
        "readOnly": false,
        "validators": {
        }
      },
      {
        "name": "lastName",
        "displayName": "${lastName}",
        "required": true,
        "readOnly": false,
        "validators": {
        }
      }
    ]
  },
  "attributes": {
    "mobile_number": [
      "7777776666"
    ],
    "fp_user_type": [
      "investor"
    ]
  }
}

Headers

Parameter Mandatory Default value
Accept yes - application/json
content-type yes - application/json
Authorization yes - Bearer {ACCESS_TOKEN}

Note: Use tenant token generated in investor authentication.

Update User

PATCH /v2/auth/{tenant_name}/users

This API is used to update an existing user by its access_token.

curl --X PATCH '{baseUrl}/v2/auth/{tenant_name}/users' \
-H 'Accept: application/json' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer ACCESS_TOKEN'
-D '{json_request}'

JSON Request:

{
  "username": "PAN",
  "firstName": "FN",
  "lastName": "LN",
  "email": "test@cybrilla.com",
  "attributes": {
    "fp_identifier": "1",
    "fp_user_type": "investor",
    "mobile_number": "7777776666",
    "key1": "value1"
  }
}

Headers

Parameter Mandatory Default value
Accept yes - application/json
content-type yes - application/json
Authorization yes - Bearer {ACCESS_TOKEN}

Parameters

Parameter Mandatory Default Description
username yes - Username
firstName optional - First name
lastName optional - Last name
email optional - email
attributes.fp_identifier optinal - FP Investor id (use id from response of Create investor)
attributes.fp_user_type yes - investor
attributes.mobile_number yes - This number will be used to send OTP if fp_identifier is not provided.

Response 204 is success resposne code

Note:

Search User

GET /v2/auth/{tenant_name}/users/search

This API is used to search users by username. It will retirn empty list if no user is found with provided username

curl -X GET "{baseUrl}/v2/auth/{tenant_name}/users/search?exact=true&username={user_name}" 
-H "Authorization: Bearer ACCESS_TOKEN"

JSON Response:

[
  {
    "id": "78d30227-d07c-46d4-a227-cb5516c412ed",
    "createdTimestamp": 1657871715236,
    "username": "729",
    "enabled": true,
    "totp": false,
    "emailVerified": false,
    "attributes": {
      "fp_identifier": [
        "729"
      ],
      "mobile_number": [
        "7777776666"
      ],
      "fp_user_type": [
        "investor"
      ]
    },
    "disableableCredentialTypes": [

    ],
    "requiredActions": [

    ],
    "notBefore": 0,
    "access": {
      "manageGroupMembership": true,
      "view": true,
      "mapRoles": true,
      "impersonate": false,
      "manage": true
    }
  }
]

Headers

Parameter Mandatory Default value
content-type yes - application/json
Authorization yes - Bearer {ACCESS_TOKEN}

Query Parameters

Name Mandatory Type Comments
exact yes boolean Recomened to use true
username yes string Username

Note: Use tenant token generated in tenant authentication.

Authenticating a user via OAuth 2.0 PKCE flow from browser based clients

Oauth 2 0 (Image courtesy : scottbrady91.com)

Step1: Generate a PKCE pair (code verifier and code challenge)

Resources for testing purposes

Please visit this site to easily generate PKCE pair (make sure you have selected SHA-256 as Code Challenge Method) or use the below sample PKCE pair.

Sample PKCE pair

NOTE !!!: Appropriate code needs to be added in the native or spa app to create the code_verifier and code_challenge. The app should save the code_verifier for later use, and should send the code_challenge along with the authorization request to /auth URL.

Step2: Authenticate the user and get authorization code.

There are two ways to manage user authentication.

Default Mode: Delegate the entire responsibility of authentication to FP. In this mode, you will have to redirect your user to the FP Auth server, and upon successful authentication, you can get the authorization code. In this mode, you don't have to worry about managing UI for authentication as FP handles everything. This is the default mode.

Advanced Mode: For advanced use cases, where you want to have control over the authentication user experience, you can ask us to disable the default mode of authentication while registering your OAuth 2.0 client with us. In this mode you have to build your own user experience and make API calls to FP to complete authentication.

GET /v2/auth/{tenant_name}/auth 

curl -X GET "{baseUrl}/v2/auth/{tenant_name}/auth"

Query Parameters

Parameter Mandatory Default Description
client_id yes - The client_id of your application that is provided by FP during client registration.
response_type yes - Use code for browser side flows
state yes - An opaque string that is round-tripped in the protocol. The state parameter is used to protect against XSRF
login_hint yes - username
code_challenge yes - that is generated in step1
code_challenge_method yes - Use S256
redirect_uri yes - one of the valid redirect urls provided at time of onbording

Default mode behaviour:

Case 1: If the user does not have an existing session, making this request via browser opens the login page. OTP will be sent to the mobile number linked to the User and investor has to enter the OTP. Once the authentication is successful, user will be redirect to the redirect_url with authorization code.
Case 2: If user has an existing session, they will be immediately redirected to redirect_uri with authorization code.

Response {redirect_uri}/?state={state}&session_state={session_state}&code={CODE}

Advanced mode behaviour:

In contrast to the default mode, you wouldn't be redirected to FP's auth server, when you make GET /v2/auth/{tenant_name}/auth API call. Instead, you will get the following response.

JSON Response:

{
  "challenge": "OTP",
  "session_code": "helmn0ufS61w1yu9xwsdyl0vd9hzVkmGzYmVLrcE6B8",
  "execution": "f146345f-f395-4e2f-9330-a2d97198b1c4",
  "auth_session_id": "3782e9da-4944-4996-b579-396d79550382",
  "tab_id": "_51fDo_FFAs"
}

Response Parameters

Parameter Type Description
challenge string Challenge is the next step that user should perform. Currently we only support OTP.
session_code string This is code of current session.
execution string This is id of current execution in the flow.
auth_session_id string This is id of the authentication session
tab_id string ID of this subsession (in other words, usually browser tab)

The challenge attribute in the response tells you, how the investor must be authenticated. For example, if it is OTP, you can display your custom page to accept OTP from the investor. (Note: OTP is automatically sent by FP to the users). Once you have completed collecting details required to complete the challenge process from you users, you can call the below API.

POST /v2/auth/{tenant_name}/authenticate

curl --location --request POST '{baseUrl}/v2/auth/{tenant}/authenticate?session_code={SESSION_CODE}&client_id={CLIENT_ID}&execution={EXECUTION}&auth_session_id={AUTH_SESSION_ID}&tab_id={TAB_ID}' \
--header 'accept: application/json' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'otp={OTP}'

Query Parameters

Name Mandatory Type Comments
session_code yes string This is code of current session.
execution yes string This is id of current execution in the flow.
auth_session_id yes string This is id of the authentication session
tab_id yes string ID of this subsession (in other words, usually browser tab)

Value for query params should be picked from reponse of above step.

Parameters

Name Mandatory Type Comments
otp yes string Collected from investor. Mandatory only if challenge is OTP.

Response

If the challenge is completed successfully, it means that one factor of authentication is complete. If there are no more factors of authentication required, you will get a 302 response. On the contrary, if another factor of authentication is required, you will get challenge, session_code, execution, auth_session_id and tab_id again as response for next factor of authentication. If you get a new challenge as a response(indicating that you have to do an additional factor of authentication), you have to make an API call to POST /v2/auth/{tenant_name}/authenticate to complete the new challenge. Upon completing all required factors of authentication, you will get 302 response. Read the location from response header and extract the code.
Example: location: {redirect_uri}/?state={state}&session_state={session_state}&code={CODE}

Note:

Irrespective of whether you use default mode or advanced mode, after Step 2, you will get an authorization code, and this authorisation code remains valid for 300 seconds. Within 300 seconds, you will have to exchange this authorization code with the auth server to get access token.

Step3: Exchange authorisation code to get access token

Use POST /token API to exchange a valid authorization code and get access_token. You will also get a refresh_token in addition to the access_token. Both access_token and refresh_token will have expiry times associated with them. If the access_token is expired or if you want to get a new access token before it expires, you can use refresh_token (provided that refres_token is not expired) to regenerate a new access_token and a new refresh_token without requiring users to authenticate again. To exchange an code for an access_token, and a refresh_token pass it to the /token endpoint as follows:

POST /v2/auth/{tenant_name}/token

curl \
-H 'accept: application/json' \
-H 'content-type: application/x-www-form-urlencoded' \
-d "client_id=XXX" \
-d "code=a4ab74f9-15a9-49bf-992d-0b701509d51c.4d7d775b-65d1-4dfe-b21b-dfeca3e820dc.3c6bd12c-d581-4a1f-94f4-2a438967fc72" \
-d "code_verifier=XXXXXXX" \
-d "grant_type=authorization_code" \
-d "redirect_uri=http://localhost:8080/callback" \
"{baseUrl}/v2/auth/{tenant}/token"

JSON response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJPSnVJZWpIdHYtMERpTWFRVUpoR0hWbGJmTU1vVjhNM1I1b21jWExRYkpjIn0.eyJleHAiOjE2NTA0Mzc2NjMsImlhdCI6MTY1MDQzNTg2MywiYXV0aF90aW1lIjoxNjUwNDM1ODMyLCJqdGkiOiJjYTVjNjhhNi1lMzBhLTQ1ZGEtYmZmZC1iNWQwNGNhY2YxNjMiLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvY3liZXJpb24iLCJzdWIiOiJlODYwNWJkMS03NzUzLTQxM2EtYjU0OC04MGIyMDMzM2VkMDAiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjeWJlcmlvbl90ZXN0X2ludmVzdG9yX2FwcF9icm93c2VyIiwic2Vzc2lvbl9zdGF0ZSI6IjMzNzM5NzU2LTVlNGQtNGRmOC1iYjlkLTIwOGY2NmU2ODAyMiIsImFjciI6IjEiLCJzY29wZSI6ImRlZmF1bHQiLCJzaWQiOiIzMzczOTc1Ni01ZTRkLTRkZjgtYmI5ZC0yMDhmNjZlNjgwMjIiLCJ0eXBlIjoiaW52ZXN0b3IiLCJmcF9pZGVudGlmaWVyIjoiNjM5IiwidGVuYW50IjoiY3liZXJpb24ifQ.lMN2_vn25b55ztiI7a99ZeuOClCpBwdla2roQeiAsE4NHBTjgj89XeXVN9XALCCLqxgsn9XNJekc6257qEEszGT_gqr1FRCax8wpu24B8tlHw7mLTsUjIFyDmrpX9iy5z5E0ShcwUVB47yaI02blUcHluy0LTJj6ivijtEjaPDV7fIcrm7tLHF9kmOQcg8uoytiJskog7A7NdNS38Imx90pYxNyROGV87yLUG3ZX1Sjm9djqoUeKzpbK22x8PN_lb46qo9lxdu8MAu-bJskv_aO7GpB4LFnA3fG-cua3M8DCyndLTArsuhaHLcb5WZNoAkibDVVlYPnEBE74Etlqwg",
  "expires_in": 1800,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiNjhmNjM0OS04NjMzLTRjN2ItOGIwNy0zZGRiNjdmMmMwOTMifQ.eyJleHAiOjE2NTA0Mzc2NjMsImlhdCI6MTY1MDQzNTg2MywianRpIjoiODY4NTVhYTMtMDhmYi00ODMyLTljZWEtZjcyMzZmNWFkYmVhIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL2N5YmVyaW9uIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL2N5YmVyaW9uIiwic3ViIjoiZTg2MDViZDEtNzc1My00MTNhLWI1NDgtODBiMjAzMzNlZDAwIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImN5YmVyaW9uX3Rlc3RfaW52ZXN0b3JfYXBwX2Jyb3dzZXIiLCJzZXNzaW9uX3N0YXRlIjoiMzM3Mzk3NTYtNWU0ZC00ZGY4LWJiOWQtMjA4ZjY2ZTY4MDIyIiwic2NvcGUiOiJkZWZhdWx0Iiwic2lkIjoiMzM3Mzk3NTYtNWU0ZC00ZGY4LWJiOWQtMjA4ZjY2ZTY4MDIyIn0.R3fWUw4BQpeChPmRKPvOnX5VgH8fCgskjr5VkZWeGBo",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "33739756-5e4d-4df8-bb9d-208f66e68022",
  "scope": "default"
}

Headers

Parameter Mandatory Default value
accept yes - application/json
content-type yes - application/x-www-form-urlencoded

Parameters

Parameter Mandatory Default Description
client_id yes - The client_id of your application that is provided by FP during client registration.
code yes - authorization code received after successful authentication.
code_verifier yes - This is one of the values of PKCE pair generated in step 1.
grant_type yes - authorization_code
redirect_uri yes - one of valid redirect url provided at time of onbording

Note: Irrespective of whether you are able to successfully exchange the authorization_code to get access_token or not, a authorization code can be used only one time in an exchange. Post that, you cannot use that authorization_code to get access_token again. If you fail to exchange authorization_code to get access_token, you will have to authenticate the investor again(i.e from Step 1).

Regenerating an access token from a refresh token

This api can be used to regenerate access token when it is expired or if you want to get a new access token before it expires, you can use refresh_token (provided that refres_token is not expired) to regenerate a new access_token and a new refresh_token without requiring users to authenticate again.

POST /v2/auth/{tenant_name}/token

curl \
-H 'accept: application/json' \
-H 'content-type: application/x-www-form-urlencoded' \
-d "client_id=XXX" \
-d "refresh_token=XXXXXXX" \
-d "grant_type=refresh_token" \
"{baseUrl}/v2/auth/{tenant_name}/token"

Headers

Parameter Mandatory Default value
accept yes - application/json
content-type yes - application/x-www-form-urlencoded

Parameters

Parameter Mandatory Default Description
client_id yes - provided by fintechprimitives
refresh_token yes - refresh_token received as responce from /token endpoint.
grant_type yes - refresh_token

Note: This api cannot be used in case of tenant authentication.

JSON response:

{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJPSnVJZWpIdHYtMERpTWFRVUpoR0hWbGJmTU1vVjhNM1I1b21jWExRYkpjIn0.eyJleHAiOjE2NTA0Mzc2NjMsImlhdCI6MTY1MDQzNTg2MywiYXV0aF90aW1lIjoxNjUwNDM1ODMyLCJqdGkiOiJjYTVjNjhhNi1lMzBhLTQ1ZGEtYmZmZC1iNWQwNGNhY2YxNjMiLCJpc3MiOiJodHRwOi8vbG9jYWxob3N0OjgwODAvYXV0aC9yZWFsbXMvY3liZXJpb24iLCJzdWIiOiJlODYwNWJkMS03NzUzLTQxM2EtYjU0OC04MGIyMDMzM2VkMDAiLCJ0eXAiOiJCZWFyZXIiLCJhenAiOiJjeWJlcmlvbl90ZXN0X2ludmVzdG9yX2FwcF9icm93c2VyIiwic2Vzc2lvbl9zdGF0ZSI6IjMzNzM5NzU2LTVlNGQtNGRmOC1iYjlkLTIwOGY2NmU2ODAyMiIsImFjciI6IjEiLCJzY29wZSI6ImRlZmF1bHQiLCJzaWQiOiIzMzczOTc1Ni01ZTRkLTRkZjgtYmI5ZC0yMDhmNjZlNjgwMjIiLCJ0eXBlIjoiaW52ZXN0b3IiLCJmcF9pZGVudGlmaWVyIjoiNjM5IiwidGVuYW50IjoiY3liZXJpb24ifQ.lMN2_vn25b55ztiI7a99ZeuOClCpBwdla2roQeiAsE4NHBTjgj89XeXVN9XALCCLqxgsn9XNJekc6257qEEszGT_gqr1FRCax8wpu24B8tlHw7mLTsUjIFyDmrpX9iy5z5E0ShcwUVB47yaI02blUcHluy0LTJj6ivijtEjaPDV7fIcrm7tLHF9kmOQcg8uoytiJskog7A7NdNS38Imx90pYxNyROGV87yLUG3ZX1Sjm9djqoUeKzpbK22x8PN_lb46qo9lxdu8MAu-bJskv_aO7GpB4LFnA3fG-cua3M8DCyndLTArsuhaHLcb5WZNoAkibDVVlYPnEBE74Etlqwg",
  "expires_in": 1800,
  "refresh_expires_in": 1800,
  "refresh_token": "eyJhbGciOiJIUzI1NiIsInR5cCIgOiAiSldUIiwia2lkIiA6ICJiNjhmNjM0OS04NjMzLTRjN2ItOGIwNy0zZGRiNjdmMmMwOTMifQ.eyJleHAiOjE2NTA0Mzc2NjMsImlhdCI6MTY1MDQzNTg2MywianRpIjoiODY4NTVhYTMtMDhmYi00ODMyLTljZWEtZjcyMzZmNWFkYmVhIiwiaXNzIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL2N5YmVyaW9uIiwiYXVkIjoiaHR0cDovL2xvY2FsaG9zdDo4MDgwL2F1dGgvcmVhbG1zL2N5YmVyaW9uIiwic3ViIjoiZTg2MDViZDEtNzc1My00MTNhLWI1NDgtODBiMjAzMzNlZDAwIiwidHlwIjoiUmVmcmVzaCIsImF6cCI6ImN5YmVyaW9uX3Rlc3RfaW52ZXN0b3JfYXBwX2Jyb3dzZXIiLCJzZXNzaW9uX3N0YXRlIjoiMzM3Mzk3NTYtNWU0ZC00ZGY4LWJiOWQtMjA4ZjY2ZTY4MDIyIiwic2NvcGUiOiJkZWZhdWx0Iiwic2lkIjoiMzM3Mzk3NTYtNWU0ZC00ZGY4LWJiOWQtMjA4ZjY2ZTY4MDIyIn0.R3fWUw4BQpeChPmRKPvOnX5VgH8fCgskjr5VkZWeGBo",
  "token_type": "Bearer",
  "not-before-policy": 0,
  "session_state": "33739756-5e4d-4df8-bb9d-208f66e68022",
  "scope": "default"
}

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.

Investor Authentication (Early Access)

Overview

If you use investor authentication via FP you are delegating authentication of investor to FP. This means that investors will be redirected to FP Auth server for authentication and once the authentication is completed, investor will be redirected to the redirect_url provided by you. If authentication is successful, you can request FP to issue investor token. Once investor token is available you can use this token to access FP APIs.

Step 1: Enabling investor authentication

  1. Write an email to fpsupport@cybrilla.com and request to enable investor authentication. You need to share following details with us.
    a) Details about the client (Example: Android mobile app, mobile web app etc).
    b) redirect urls : You can provided multiple redirect urls for whitelisting. While initiating investor authentication, you can provide any one of the whitelisted redirect urls. Investor will be redirected to this redirect url after successful authentication.
    c)
  2. We will enable investor authentication and share the client_id, and tenant_name that must be used while authenticating investors via FP.

Step 2: Ensure that there is user for investor

For any entity that you wish to authenticate on FP(investor or partner), you need to ensure that there is an account created for that entity at FP Auth server just like you need a Google account before you can login to Google. This account is known as User in FP parlance. This means that before you can authenticate an investor, you have to ensure that there is one User entry for that investor in FP's Auth server. You can user Search User API to check whether there is a User created for an investor and use Create User API to create a User if there is no User for the investor whom you wish to authenticate. Please note that you will require a tenant token to access Search User API or Create User API.

Step 3: Authenticate investor via FP auth server using OAuth 2.0 PKCE flow

Please refer to Authenticating a user via OAuth 2.0 PKCE flow to authenticate investors.

As present investor token is accepted by below APIs:

Partners

Represents a FP Partner entity on the behalf of which mutual fund transaction will be made. The partner can be a Distributor or Advisor.

Endpoints:

GET /partners/:id
GET /partners

Partner Object

{
  "object": "partner",
  "id": "ptnr_20751c37c0a548c3baf12a18bc72187b",
  "type": "distributor",
  "name": "Tony Soprano",
  "display_name": "Tony",
  "license_code": "ARN-13452",
  "created_at": "2022-06-14T08:07:36+05:30",
  "other_broker_codes": null,
  "default_broker_codes": {
    "karvy": "ARN-13452",
    "cams": "TONYMF"
  },
  "location": "Bengaluru",
  "ref_no": null,
  "mobile": null,
  "email": "",
  "contact_person_name": null,
  "expiry_date": "2024-05-05",
  "euins": [
    "E13452"
  ]
}
Attribute Type Comments
object string Value is partner. String representing the object type. Objects of the same type share the same value
id string Unique identifier of the partner object
type string This value indicates whether the partner is the distributor or adviser
Possible values: distributor, adviser
name string Full name of the partner
display_name string Name used to display on the transaction portal
license_code string License code of the partner (RIA/ARN code)
created_at string The time at which the partner is created
default_broker_codes string Default RTA broker codes of the partner
other_broker_codes string In case any other broker codes assigned to the partner a part from the default one's will be present here
location string Partner registration location
ref_no string This is the unique identification number of the partner populated from upstreams
mobile string Mobile number of the partner
email string Email ID of the partner
contact_person_name string Contact person name of the partner office
expiry_date string License expiration date of the partner
euins string Unique identity number of the partner can be used while placing the purchase order

Fetch a Partner

GET /partners/:id

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

This API is used to fetch a partner by its identifier.

Query Parameters

Name Mandatory Type Comments
id yes string id of the partner

JSON Response:

{
  "object": "partner",
  "id": "ptnr_20751c37c0a548c3baf12a18bc72187b",
  "type": "distributor",
  "name": "Tony Soprano",
  "display_name": "Tony",
  "license_code": "ARN-13452",
  "created_at": "2022-06-14T08:07:36+05:30",
  "other_broker_codes": null,
  "default_broker_codes": {
    "karvy": "ARN-13452",
    "cams": "TONYMF"
  },
  "location": "Bengaluru",
  "ref_no": null,
  "mobile": null,
  "email": "",
  "contact_person_name": null,
  "expiry_date": "2024-05-05",
  "euins": [
    "E13452"
  ]
}

Search a Partner

GET /partners

curl -X GET "https://s.finprim.com/partners?code=ARN-13452"
  -H "Authorization: Bearer ACCESS_TOKEN"

This API can be use to search partner.

JSON Response:

{
  "object": "partner",
  "id": "ptnr_20751c37c0a548c3baf12a18bc72187b",
  "type": "distributor",
  "name": "Tony Soprano",
  "display_name": "Tony",
  "license_code": "ARN-13452",
  "created_at": "2022-06-14T08:07:36+05:30",
  "other_broker_codes": null,
  "default_broker_codes": {
    "karvy": "ARN-13452",
    "cams": "TONYMF"
  },
  "location": "Bengaluru",
  "ref_no": null,
  "mobile": null,
  "email": "",
  "contact_person_name": null,
  "expiry_date": "2024-05-05",
  "euins": [
    "E13452"
  ]
}

Query Parameters

Name Mandatory Type Comments
code yes string Licence code of the partner

KYC Checks

This API will allow you to check the KYC compliance status of an investor and also display his demographic information as present in the KRA (KYC Registration Agency) databases.

Endpoints:

POST /api/kyc/check
GET /api/kyc/:id
PUT /api/kyc/:id/refetch

Create a kyc check

Status 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": {
    "name": "Tony Soprano"
  },
  "status": false,
  "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",
  "action": "modify",
  "reason": "onhold"
}

POST /api/kyc/check

Fetch KYC Data

curl -X POST "https://s.finprim.com/api/kyc/check"
-H "Authorization: Bearer JWTTOKEN"
-d
'
{
"pan": "AAAPA3751A",
"date_of_birth": "25/10/1955"
}
'

The above command returns JSON structured like this:

{
  "id": "429f998a-6488-428b-adbd-1c7abdf2a42a",
  "source_ref_id": null,
  "pan": "AAAPA3751A",
  "entity_details": {
    "name": "Tony Soprano",
    "gender": "male",
    "date_of_birth": "25/10/1955",
    "father_name": "Murli Dhar Narang",
    "marital_status": "married",
    "nationality": "indian",
    "residential_status": "resident_individual",
    "correspondence_address": {
      "line_1": "19th main, 33rd cross",
      "line_2": "Jayanagar 4th T block",
      "line_3": null,
      "city": "Bengaluru",
      "pincode": "560041",
      "state": "Karnataka",
      "country": "India"
    },
    "permanent_address": {
      "line_1": "19th main, 33rd cross",
      "line_2": "Jayanagar 4th T block",
      "line_3": null,
      "city": "Bengaluru",
      "pincode": "560041",
      "state": "Karnataka",
      "country": "India"
    },
    "email": "suresh.nrg@gmail.com",
    "mobile": "9809879878"
  },
  "status": true,
  "constraints": [

  ],
  "sources": [
    {
      "name": "kra-cvl",
      "response_verbatim": "<xml></xml>",
      "fetched_at": "2021-08-10T12:32:25+05:30"
    }
  ],
  "created_at": "2021-08-10T12:32:25+05:30",
  "updated_at": "2021-08-10T12:32:25+05:30",
  "action": null,
  "reason": null
}

Creating a KYC Check fetches the investor's kyc status from different sources. We offer below listed two solutions here.

Status Check

This will allow you to check the KYC status of an investor using his / her PAN number. The status can be true or false which will indicate if he / she is KYC compliant or not. If the investor has some investment constraints, they would be listed under the constraints list.

Fetch KYC Data

This will allow you to check and fetch the KYC details of an investor as recorded in the KRA databases. You need to send the investor's PAN number and the date of birth as the input parameters in the request body. The response would contain the KYC status along with the demographic (Identity, Address and Contact) information of the investor under entity_details list.

Query Parameters

Parameter Mandatory Default Description
pan yes - A valid PAN number to check the kyc status for
Parameter Mandatory Default Description
pan yes - A valid PAN number to check the kyc status for
date_of_birth yes - A valid date of birth for the above mentioned PAN number in DD/MM/YYYY format

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": {
    "name": "Tony Soprano"
  },
  "status": false,
  "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",
  "action": "modify",
  "reason": "onhold"
}

GET /api/kyc/:id

Retrieve the KYC Check object

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": {
    "name": "Tony Soprano"
  },
  "status": false,
  "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",
  "action": "modify",
  "reason": "onhold"
}

PUT /api/kyc/:id/refetch

Force the platform to refetch the kyc information from the sources

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",
  "permanent_address": {
    "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.

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.

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 must be in jpg, jpeg, png, mp4, pdf and tiff format and size should not exceed 10MB.
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

Investors

Investor holds the personal, demographic and financial information about your customer. The API allows you to create, update an investor and also list investors.

Endpoints:

POST /api/onb/investors
POST /api/onb/investors/:id
GET /api/onb/investors/:id
GET /api/onb/investors
GET /api/onb/investors/search

Create an investor

curl -X POST "https://s.finprim.com/api/onb/investors"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

{
  "display_name": "tony",
  "perm_addr_is_corres_addr": true,
  "ip_address": "192.168.29.100",
  "bank_accounts": [
    {
      "account_holder_name": "tony",
      "number": "00000001234455",
      "primary_account": true,
      "type": "SAVINGS",
      "ifsc_code": "ICIC0000611",
      "cancelled_cheque": "3867a9c6-8a7c-4605-a31d-98367e8972b4"
    }
  ],
  "contact_detail": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  },
  "fatca_detail": {
    "country_of_birth_ansi_code": "IN",
    "no_other_tax_residences": true,
    "source_of_wealth": "business",
    "gross_annual_income": 100000
  },
  "nomination": {
    "skip_nomination": false,
    "nominee1": {
      "allocation_percentage": 100,
      "date_of_birth": "1990-10-10",
      "name": "nandam",
      "relationship": "spouse"
    }
  },
  "kyc_identity_detail": {
    "pan_number": "AFZPN3001P",
    "country_of_citizenship_ansi_code": "IN",
    "date_of_birth": "1980-10-10",
    "father_or_spouse_name": "tonys wife",
    "kyc_relation": "spouse",
    "gender": "female",
    "marital_status": "single",
    "name": "tony Soprano ms",
    "occupation": "BUSINESS",
    "residential_status": "resident_individual",
    "pep_exposed": false,
    "pep_related": false,
    "signature": "beed6916-cec6-4f4f-bcc8-ed4d93b55660"
  },
  "correspondence_address": {
    "line1": "1082 harlur road",
    "pincode": "560102"
  }
}

JSON Reponse

{
  "id": 1,
  "display_name": "tony",
  "perm_addr_is_corres_addr": true,
  "ip_address": "192.168.1.1",
  "created_at": "2018-05-22T10:14:19.072Z",
  "updated_at": "2018-05-22T10:14:19.072Z",
  "meta": null,
  "nomination": {
    "skip_nomination": false,
    "nominee1": {
      "date_of_birth": "1990-10-10",
      "name": "Tony Stark",
      "pan": null,
      "relationship": "nandam",
      "guardian_name": null,
      "guardian_pan": null,
      "guardian_relationship": null,
      "allocation_percentage": 100
    },
    "nominee2": null,
    "nominee3": null
  },
  "contact_detail": {
    "email": "mfp@cybrilla.com",
    "isd_code": 91,
    "mobile": "9008580644",
    "office_telephone_no": null,
    "residence_telephone_no": null
  },
  "fatca_detail": {
    "country_of_birth_ansi_code": "IN",
    "source_of_wealth": "BUSINESS",
    "first_trc_ansi_code": null,
    "first_trc_taxid_type": null,
    "first_trc_taxid_number": null,
    "second_trc_ansi_code": null,
    "second_trc_taxid_type": null,
    "second_trc_taxid_number": null,
    "third_trc_ansi_code": null,
    "third_trc_taxid_type": null,
    "third_trc_taxid_number": null,
    "gross_annual_income": 1000000,
    "no_other_tax_residences": true
  },
  "kyc_identity_detail": {
    "name": "tony Soprano ms",
    "father_or_spouse_name": "tonys wife",
    "mothers_name": null,
    "ckyc_number": null,
    "kyc_relation": "spouse",
    "date_of_birth": "1980-10-10",
    "marital_status": "MARRIED",
    "pan_number": "AFZPN3001P",
    "gender": "female",
    "occupation": "BUSINESS",
    "residential_status": "RESIDENT_INDIVIDUAL",
    "country_of_citizenship_ansi_code": "IN",
    "pan_exempt": false,
    "pep_exposed": false,
    "pep_related": false,
    "guardian_relationship": null,
    "guardian_name": null,
    "guardian_date_of_birth": null,
    "guardian_pan_number": null,
    "signature": "beed6916-cec6-4f4f-bcc8-ed4d93b55660"
  },
  "bank_accounts": [
    {
      "id": 1,
      "account_holder_name": "tony",
      "type": "SAVINGS",
      "primary_account": true,
      "number": "00000001214415",
      "created_at": "2019-05-22T10:14:19.082Z",
      "updated_at": "2019-05-22T10:14:19.082Z",
      "branch": {
        "ifsc_code": "ICIC0000611",
        "micr_code": null,
        "branch_name": "GUDIVADA",
        "bank_name": "ICICI BANK LIMITED",
        "branch_address": "ICICI BANK LTD , D NO11218, NENIPLAZA, ELURU ROAD, GUDIVADA 521301",
        "contact": null,
        "city": "GUDIVADA",
        "district": "KRISHNA",
        "state": "ANDHRA PRADESH"
      },
      "cancelled_cheque": "3867a9c6-8a7c-4605-a31d-98367e8972b4"
    }
  ],
  "correspondence_address": {
    "line1": "1082 road",
    "line2": null,
    "line3": null,
    "type": "CORRESPONDENCE",
    "zipcode": "560112",
    "city": "Bengaluru",
    "state": "KARNATAKA",
    "country_ansi_code": "IN"
  },
  "_links": [
    {
      "href": "https://s.finprim.com/onb/investors/229",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://s.finprim.com/onb/investors/229",
      "rel": "update",
      "method": "POST"
    }
  ]
}

POST /api/onb/investors

Create a new investor so you can allow him to make investments and see reports. The information from the investor object is used while creating a new folio.

Parameters

Name Mandatory type Comments
display_name no string
perm_addr_is_corres_addr yes boolean flag to determine if permanent_address is same as correspondence_address
bank_accounts yes array of objects this is a list of banks accounts that can be added for the investor. You can mark only one account as Primary. For more details please refer bank account parameters.
contact_detail yes object contact details of the investor
fatca_detail yes object FATCA details of the investor
nomination yes object nominee details of the investor
kyc_identity_detail yes object identity details of the investor for KYC and Registration with AMCs
correspondence_address yes object
permanent_address no object mandatory if perm_addr_is_corres_addr is false
overseas_address no object mandatory for NRI investor
ip_address no string 192.099.10.10

BankAccount params

Name Mandatory type Comments
account_holder_name yes string name of the bank account holder
number yes string bank account number
primary_account yes boolean whether the bank_account is primary or not
type yes enum select one from - "SAVINGS", "CURRENT", "NRE", "NRO"
ifsc_code yes select one of the ifsc code from ifsc codes api
cancelled_cheque no string File Id of uploaded cancelled cheque image using files api. Mandatory to create Investment Account when order gateway provider is BSE

ContactDetail params

Name Mandatory type Comments
email yes string email ID of the investor to be reported to AMC
isd_code yes string ISD code of the mobile / telephone number
mobile yes string mobile number of the investor
office_telephone_no no string
residence_telephone_no no string

FatcaDetail params

Name Mandatory type Comments
country_of_birth_ansi_code yes string ANSI code of the country, eg ANSI code of India is IN
no_other_tax_residences yes boolean flag to determine if the investor is a tax-resident in countries other than India. If set to false, atleast one tax residency details is mandatory.
source_of_wealth yes enum values permitted: SALARY, BUSINESS, GIFT, ANCESTRAL_PROPERTY, RENTAL_INCOME, PRIZE_MONEY, ROYALTY, OTHERS
gross_annual_income yes integer should be greater than zero
first_trc_ansi_code no string ANSI code of the tax residency country. Mandatory if no_other_tax_residences is false
first_trc_taxid_type no string type of tax identification (SSN Card etc..). Mandatory if first_trc_ansi_code is given
first_trc_taxid_number no string number of the tax identification (SSN etc..). Mandatory if first_trc_ansi_code is given
second_trc_ansi_code no string ansi code of the tax residency country
second_trc_taxid_type no string type of tax identification (SSN Card etc..). Mandatory if second_trc_ansi_code is given
second_trc_taxid_number no string number of the tax identification (SSN etc..). Mandatory if second_trc_ansi_code is given
third_trc_ansi_code no string ansi code of the tax residency country
third_trc_taxid_type no string type of tax identification (SSN Card etc..). Mandatory if third_trc_ansi_code is given
third_trc_taxid_number no string number of the tax identification (SSN etc..). Mandatory if third_trc_ansi_code is given

Nomination params

Name Mandatory type Comments
skip_nomination yes boolean Flag to determine is the investor wants to declare nominee
nominee1 no object mandatory if skip_nomination is false
nominee2 no object mandatory if allocation percentage of nominee1 is less than 100%
nominee3 no object mandatory if total allocation percentage of nominee1 & nominee2 is less than 100%

Nominee params

Name Mandatory type Comments
name yes string name of the ominee
pan no string PAN of the nominee
date_of_birth yes string date formatted as "YYYY-MM-DD"
relationship yes string can be any relationship like (spouse/father/mother etc..)
allocation_percentage yes integer should be from 0-100
guardian_name no string mandatory if nominee is a minor
guardian_pan no string PAN of the guardian, applicable only if the nominee is a minor
guardian_relationship no string relationship of nominee with the guardian. Mandatory if nominee is a minor

KYC IdentityDetail params

Name Mandatory type Comments
name yes string name of the investor as printed in the identity_proof
father_or_spouse_name no string
mothers_name no string
kyc_relation no enum relationship of the investor with person mentioned in father_or_spouse_name field. Values permitted: FATHER, SPOUSE
country_of_citizenship_ansi_code yes string ANSI code of the country of citizenship of the investor
date_of_birth yes string date of birth of the investor in "YYYY-MM-DD" format
gender yes enum gender of the investor. Values permitted: MALE, FEMALE, OTHERS
marital_status yes enum marital status of the investor. Values permitted: MARRIED, SINGLE, OTHERS
residential_status yes enum residential status of the investor. Values permitted: RESIDENT_INDIVIDUAL, NON_RESIDENT_INDIVIDUAL
occupation yes enum occupation of the investor. Values permitted: AGRICULTURE, BUSINESS, DOCTOR, FOREX_DEALER, GOVERNMENT_SERVICE, HOUSE_WIFE, OTHERS, PRIVATE_SECTOR_SERVICE, PROFESSIONAL, PUBLIC_SECTOR_SERVICE, RETIRED, SERVICE, STUDENT.
pan_number no string should be valid pan_number and mandatory if pan_exempt is false
pan_exempt no boolean default to be false
pep_exposed yes boolean flag to determine if the person is politically exposed
pep_related yes boolean flag to determine if the person is related to a politically exposed person
guardian_name no string mandatory if investor is minor
guardian_relationship no string mandatory if investor is minor
guardian_date_of_birth no string mandatory if investor is minor. Date of birth in format "YYYY-MM-DD".
guardian_pan_number no string mandatory if investor is minor. PAN number of the guardian should be a valid PAN number.
signature no string File Id of uploaded signature image using files api. Mandatory to create Investment Account when order gateway provider is BSE

Address _params

Name Mandatory type Comments
line1 yes string
line2 no string
line3 no string
city no string mandatory if zipcode is given
state no string mandatory if zipcode is given
pincode no string mandatory if zipcode is not given
zipcode no string mandatory if pincode is not given
country_ansi_code no string mandatory if zipcode is given

A note on BSE order gateway

Mandatory fields validation for BSE

Field Mandatory Remarks
perm_addr_is_corres_addr yes
kyc_identity_detail.name yes
kyc_identity_detail.date_of_birth yes
bank_accounts yes At least one bank account. For each bank account type, number and ifsc_code are mandatory
correspondence_address.line1 yes
correspondence_address.city yes
correspondence_address.state yes
correspondence_address.pincode yes
correspondence_address.country_ansi_code yes
contact_detail.email yes
contact_detail.mobile yes

Tax status specific validations for BSE

Tax Status 4th character of PAN Bank Account Type Guardian Name Guardian PAN Gender
Individual P SAVINGS/CURRENT/NRE/NRO mandatory
On behalf of minor P SAVINGS/CURRENT mandatory mandatory mandatory

Maximum length validations for BSE

Field Maximum length
kyc_identity_detail.name 70
kyc_identity_detail.guardian_name 35
kyc_identity_detail.date_of_birth 10
nominee.name 35
nominee.relationship 20
bank_account.number 16
bank_account.ifsc 11
address.line1 40
address.line2 40
address.line3 40
address.city 35
contact_detail.office_telephone_no 15
contact_detail.residence_telephone_no 15
contact_detail.email 50
contact_detail.mobile 10

Update an investor

curl -X POST "https://s.finprim.com/api/onb/investors/12435"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

JSON Request

Same parameters as the request for create investor endpoint

JSON Reponse

{
  "id": 1,
  "display_name": "tony",
  "perm_addr_is_corres_addr": true,
  "ip_address": "192.168.1.1",
  "created_at": "2018-05-22T10:14:19.072Z",
  "updated_at": "2018-05-22T10:14:19.072Z",
  "meta": null,
  "nomination": {
    "skip_nomination": false,
    "nominee1": {
      "date_of_birth": "1990-10-10",
      "name": "Tony Stark",
      "pan": null,
      "relationship": "nandam",
      "guardian_name": null,
      "guardian_pan": null,
      "guardian_relationship": null,
      "allocation_percentage": 100
    },
    "nominee2": null,
    "nominee3": null
  },
  "contact_detail": {
    "email": "mfp@cybrilla.com",
    "isd_code": 91,
    "mobile": "9008580644",
    "office_telephone_no": null,
    "residence_telephone_no": null
  },
  "fatca_detail": {
    "country_of_birth_ansi_code": "IN",
    "source_of_wealth": "BUSINESS",
    "first_trc_ansi_code": null,
    "first_trc_taxid_type": null,
    "first_trc_taxid_number": null,
    "second_trc_ansi_code": null,
    "second_trc_taxid_type": null,
    "second_trc_taxid_number": null,
    "third_trc_ansi_code": null,
    "third_trc_taxid_type": null,
    "third_trc_taxid_number": null,
    "gross_annual_income": 1000000,
    "no_other_tax_residences": true
  },
  "kyc_identity_detail": {
    "name": "tony Soprano ms",
    "father_or_spouse_name": "tonys wife",
    "mothers_name": null,
    "ckyc_number": null,
    "kyc_relation": "spouse",
    "date_of_birth": "1980-10-10",
    "marital_status": "MARRIED",
    "pan_number": "AFZPN3001P",
    "gender": "female",
    "occupation": "BUSINESS",
    "residential_status": "RESIDENT_INDIVIDUAL",
    "country_of_citizenship_ansi_code": "IN",
    "pan_exempt": false,
    "pep_exposed": false,
    "pep_related": false,
    "guardian_relationship": null,
    "guardian_name": null,
    "guardian_date_of_birth": null,
    "guardian_pan_number": null,
    "signature": "beed6916-cec6-4f4f-bcc8-ed4d93b55660"
  },
  "bank_accounts": [
    {
      "id": 1,
      "account_holder_name": "tony",
      "type": "SAVINGS",
      "primary_account": true,
      "number": "00000001214415",
      "created_at": "2019-05-22T10:14:19.082Z",
      "updated_at": "2019-05-22T10:14:19.082Z",
      "branch": {
        "ifsc_code": "ICIC0000611",
        "micr_code": null,
        "branch_name": "GUDIVADA",
        "bank_name": "ICICI BANK LIMITED",
        "branch_address": "ICICI BANK LTD , D NO11218, NENIPLAZA, ELURU ROAD, GUDIVADA 521301",
        "contact": null,
        "city": "GUDIVADA",
        "district": "KRISHNA",
        "state": "ANDHRA PRADESH"
      },
      "cancelled_cheque": "3867a9c6-8a7c-4605-a31d-98367e8972b4"
    }
  ],
  "correspondence_address": {
    "line1": "1082 road",
    "line2": null,
    "line3": null,
    "type": "CORRESPONDENCE",
    "zipcode": "560112",
    "city": "Bengaluru",
    "state": "KARNATAKA",
    "country_ansi_code": "IN"
  },
  "_links": [
    {
      "href": "https://s.finprim.com/onb/investors/229",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://s.finprim.com/onb/investors/229",
      "rel": "update",
      "method": "POST"
    }
  ]
}

POST /api/onb/investors/:id

Update an existing investor's details. Existing folios for this investor doesn't affect with this change. Any new folios created after the update will contain the updated investor's details.

Parameters

All query parameters are same as create investor. Refer to create investor documentation

In bank_accounts array, id of each bank account needs to be sent to update existing bank account. Otherwise, a new bank account will be added to the investor.

Note:

When you update the details of an investor at FP,investor demographic information is only updated at FP. The investor demographic information wouldn't change at
a) Existing folios for the investor
b) Existing investor information stored at BSE(For BSE customers)

Fetch an investor

curl "https://s.finprim.com/api/onb/investors/1"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Reponse

{
  "id": 1,
  "display_name": "tony",
  "perm_addr_is_corres_addr": true,
  "ip_address": "192.168.1.1",
  "created_at": "2018-05-22T10:14:19.072Z",
  "updated_at": "2018-05-22T10:14:19.072Z",
  "meta": null,
  "nomination": {
    "skip_nomination": false,
    "nominee1": {
      "date_of_birth": "1990-10-10",
      "name": "Tony Stark",
      "pan": null,
      "relationship": "nandam",
      "guardian_name": null,
      "guardian_pan": null,
      "guardian_relationship": null,
      "allocation_percentage": 100
    },
    "nominee2": null,
    "nominee3": null
  },
  "contact_detail": {
    "email": "mfp@cybrilla.com",
    "isd_code": 91,
    "mobile": "9008580644",
    "office_telephone_no": null,
    "residence_telephone_no": null
  },
  "fatca_detail": {
    "country_of_birth_ansi_code": "IN",
    "source_of_wealth": "BUSINESS",
    "first_trc_ansi_code": null,
    "first_trc_taxid_type": null,
    "first_trc_taxid_number": null,
    "second_trc_ansi_code": null,
    "second_trc_taxid_type": null,
    "second_trc_taxid_number": null,
    "third_trc_ansi_code": null,
    "third_trc_taxid_type": null,
    "third_trc_taxid_number": null,
    "gross_annual_income": 1000000,
    "no_other_tax_residences": true
  },
  "kyc_identity_detail": {
    "name": "tony Soprano ms",
    "father_or_spouse_name": "tonys wife",
    "mothers_name": null,
    "ckyc_number": null,
    "kyc_relation": "spouse",
    "date_of_birth": "1980-10-10",
    "marital_status": "MARRIED",
    "pan_number": "AFZPN3001P",
    "gender": "female",
    "occupation": "BUSINESS",
    "residential_status": "RESIDENT_INDIVIDUAL",
    "country_of_citizenship_ansi_code": "IN",
    "pan_exempt": false,
    "pep_exposed": false,
    "pep_related": false,
    "guardian_relationship": null,
    "guardian_name": null,
    "guardian_date_of_birth": null,
    "guardian_pan_number": null,
    "signature": "beed6916-cec6-4f4f-bcc8-ed4d93b55660"
  },
  "bank_accounts": [
    {
      "id": 1,
      "account_holder_name": "tony",
      "type": "SAVINGS",
      "primary_account": true,
      "number": "00000001214415",
      "created_at": "2019-05-22T10:14:19.082Z",
      "updated_at": "2019-05-22T10:14:19.082Z",
      "branch": {
        "ifsc_code": "ICIC0000611",
        "micr_code": null,
        "branch_name": "GUDIVADA",
        "bank_name": "ICICI BANK LIMITED",
        "branch_address": "ICICI BANK LTD , D NO11218, NENIPLAZA, ELURU ROAD, GUDIVADA 521301",
        "contact": null,
        "city": "GUDIVADA",
        "district": "KRISHNA",
        "state": "ANDHRA PRADESH"
      },
      "cancelled_cheque": "3867a9c6-8a7c-4605-a31d-98367e8972b4"
    }
  ],
  "correspondence_address": {
    "line1": "1082 road",
    "line2": null,
    "line3": null,
    "type": "CORRESPONDENCE",
    "zipcode": "560112",
    "city": "Bengaluru",
    "state": "KARNATAKA",
    "country_ansi_code": "IN"
  },
  "_links": [
    {
      "href": "https://s.finprim.com/onb/investors/229",
      "rel": "self",
      "method": "GET"
    },
    {
      "href": "https://s.finprim.com/onb/investors/229",
      "rel": "update",
      "method": "POST"
    }
  ]
}

GET /api/onb/investors/:id

Retrieve an investor with the investor id

List all investors

curl "https://s.finprim.com/api/onb/investors"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "last": false,
  "first": false,
  "total_pages": 5,
  "number": 2,
  "size": 10,
  "total_elements": 41,
  "investors": [
    {
      "id": 1,
      "display_name": "tony",
      "perm_addr_is_corres_addr": true,
      "ip_address": "192.168.1.1",
      "created_at": "2018-05-22T10:14:19.072Z",
      "updated_at": "2018-05-22T10:14:19.072Z",
      "meta": null,
      "nomination": {
        "skip_nomination": false,
        "nominee1": {
          "date_of_birth": "1990-10-10",
          "name": "Tony Stark",
          "pan": null,
          "relationship": "nandam",
          "guardian_name": null,
          "guardian_pan": null,
          "guardian_relationship": null,
          "allocation_percentage": 100
        },
        "nominee2": null,
        "nominee3": null
      },
      "contact_detail": {
        "email": "mfp@cybrilla.com",
        "isd_code": 91,
        "mobile": "9008580644",
        "office_telephone_no": null,
        "residence_telephone_no": null
      },
      "fatca_detail": {
        "country_of_birth_ansi_code": "IN",
        "source_of_wealth": "BUSINESS",
        "first_trc_ansi_code": null,
        "first_trc_taxid_type": null,
        "first_trc_taxid_number": null,
        "second_trc_ansi_code": null,
        "second_trc_taxid_type": null,
        "second_trc_taxid_number": null,
        "third_trc_ansi_code": null,
        "third_trc_taxid_type": null,
        "third_trc_taxid_number": null,
        "gross_annual_income": 1000000,
        "no_other_tax_residences": true
      },
      "kyc_identity_detail": {
        "name": "tony Soprano ms",
        "father_or_spouse_name": "tonys wife",
        "mothers_name": null,
        "ckyc_number": null,
        "kyc_relation": "spouse",
        "date_of_birth": "1980-10-10",
        "marital_status": "MARRIED",
        "pan_number": "AFZPN3001P",
        "gender": "female",
        "occupation": "BUSINESS",
        "residential_status": "RESIDENT_INDIVIDUAL",
        "country_of_citizenship_ansi_code": "IN",
        "pan_exempt": false,
        "pep_exposed": false,
        "pep_related": false,
        "guardian_relationship": null,
        "guardian_name": null,
        "guardian_date_of_birth": null,
        "guardian_pan_number": null,
        "signature": "beed6916-cec6-4f4f-bcc8-ed4d93b55660"
      },
      "bank_accounts": [
        {
          "id": 1,
          "account_holder_name": "tony",
          "type": "SAVINGS",
          "primary_account": true,
          "number": "00000001214415",
          "created_at": "2019-05-22T10:14:19.082Z",
          "updated_at": "2019-05-22T10:14:19.082Z",
          "branch": {
            "ifsc_code": "ICIC0000611",
            "micr_code": null,
            "branch_name": "GUDIVADA",
            "bank_name": "ICICI BANK LIMITED",
            "branch_address": "ICICI BANK LTD , D NO11218, NENIPLAZA, ELURU ROAD, GUDIVADA 521301",
            "contact": null,
            "city": "GUDIVADA",
            "district": "KRISHNA",
            "state": "ANDHRA PRADESH"
          },
          "cancelled_cheque": "3867a9c6-8a7c-4605-a31d-98367e8972b4"
        }
      ],
      "correspondence_address": {
        "line1": "1082 road",
        "line2": null,
        "line3": null,
        "type": "CORRESPONDENCE",
        "zipcode": "560112",
        "city": "Bengaluru",
        "state": "KARNATAKA",
        "country_ansi_code": "IN"
      },
      "_links": [
        {
          "href": "https://s.finprim.com/onb/investors/229",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://s.finprim.com/onb/investors/229",
          "rel": "update",
          "method": "POST"
        }
      ]
    }
  ]
}

GET /api/onb/investors

Retrieve all the investors

Query Parameters

Parameter Mandatory Default Description
page no 0 page number of the result set
size no 20 number of results per page, size should not be greater than 100



Search Investors

GET /api/onb/investors/search

curl "https://s.finprim.com/api/onb/investors/search?query=user@cybrilla.com&bank_account_ids=1,22"
  -H "Authorization: Bearer ACCESS_TOKEN"

JSON Response

{
  "last": false,
  "first": false,
  "total_pages": 5,
  "number": 2,
  "size": 10,
  "total_elements": 41,
  "investors": [
    {
      "id": 1,
      "display_name": "tony",
      "perm_addr_is_corres_addr": true,
      "ip_address": "192.168.1.1",
      "created_at": "2018-05-22T10:14:19.072Z",
      "updated_at": "2018-05-22T10:14:19.072Z",
      "meta": null,
      "nomination": {
        "skip_nomination": false,
        "nominee1": {
          "date_of_birth": "1990-10-10",
          "name": "Tony Stark",
          "pan": null,
          "relationship": "nandam",
          "guardian_name": null,
          "guardian_pan": null,
          "guardian_relationship": null,
          "allocation_percentage": 100
        },
        "nominee2": null,
        "nominee3": null
      },
      "contact_detail": {
        "email": "mfp@cybrilla.com",
        "isd_code": 91,
        "mobile": "9008580644",
        "office_telephone_no": null,
        "residence_telephone_no": null
      },
      "fatca_detail": {
        "country_of_birth_ansi_code": "IN",
        "source_of_wealth": "BUSINESS",
        "first_trc_ansi_code": null,
        "first_trc_taxid_type": null,
        "first_trc_taxid_number": null,
        "second_trc_ansi_code": null,
        "second_trc_taxid_type": null,
        "second_trc_taxid_number": null,
        "third_trc_ansi_code": null,
        "third_trc_taxid_type": null,
        "third_trc_taxid_number": null,
        "gross_annual_income": 1000000,
        "no_other_tax_residences": true
      },
      "kyc_identity_detail": {
        "name": "tony Soprano ms",
        "father_or_spouse_name": "tonys wife",
        "mothers_name": null,
        "ckyc_number": null,
        "kyc_relation": "spouse",
        "date_of_birth": "1980-10-10",
        "marital_status": "MARRIED",
        "pan_number": "AFZPN3001P",
        "gender": "female",
        "occupation": "BUSINESS",
        "residential_status": "RESIDENT_INDIVIDUAL",
        "country_of_citizenship_ansi_code": "IN",
        "pan_exempt": false,
        "pep_exposed": false,
        "pep_related": false,
        "guardian_relationship": null,
        "guardian_name": null,
        "guardian_date_of_birth": null,
        "guardian_pan_number": null,
        "signature": "beed6916-cec6-4f4f-bcc8-ed4d93b55660"
      },
      "bank_accounts": [
        {
          "id": 1,
          "account_holder_name": "tony",
          "type": "SAVINGS",
          "primary_account": true,
          "number": "00000001214415",
          "created_at": "2019-05-22T10:14:19.082Z",
          "updated_at": "2019-05-22T10:14:19.082Z",
          "branch": {
            "ifsc_code": "ICIC0000611",
            "micr_code": null,
            "branch_name": "GUDIVADA",
            "bank_name": "ICICI BANK LIMITED",
            "branch_address": "ICICI BANK LTD , D NO11218, NENIPLAZA, ELURU ROAD, GUDIVADA 521301",
            "contact": null,
            "city": "GUDIVADA",
            "district": "KRISHNA",
            "state": "ANDHRA PRADESH"
          },
          "cancelled_cheque": "3867a9c6-8a7c-4605-a31d-98367e8972b4"
        }
      ],
      "correspondence_address": {
        "line1": "1082 road",
        "line2": null,
        "line3": null,
        "type": "CORRESPONDENCE",
        "zipcode": "560112",
        "city": "Bengaluru",
        "state": "KARNATAKA",
        "country_ansi_code": "IN"
      },
      "_links": [
        {
          "href": "https://s.finprim.com/onb/investors/229",
          "rel": "self",
          "method": "GET"
        },
        {
          "href": "https://s.finprim.com/onb/investors/229",
          "rel": "update",
          "method": "POST"
        }
      ]
    }
  ]
}

Retrieve a list of investors by applying certain filters

Query Parameters

Parameter Mandatory Default Description
query no - it can be name, email or PAN number
bank_account_ids no - multiple bank account IDs separated by a comma
ids no - multiple investors IDs separated by a comma
guardian_pan_numbers no - Guardian Pan numbers
page no 0 page number of the result set
size no 20 number of results per page, size should not be greater than 100

Bank Accounts (Early Access)

Endpoints:

POST /v2/bank_accounts

GET /v2/bank_accounts

GET /v2/bank_accounts/:id

Bank account object

{
  "id": "bac_98367e8972b43867a9c68a7c4605a31d",
  "object": "bank_account",
  "investor": "156",
  "account_holder_name": "Tony",
  "account_number": "00000001214415",
  "type": "savings",
  "ifsc_code": "ICIC0000611",
  "cancelled_cheque": "file_e2d360e8c79f4143867fbf1665a5caee",
  "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.
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.
cancelled_cheque string yes File ID of the cancelled_cheque associated with the bank. Will be used as proof for verification
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",
  "account_holder_name": "Tony",
  "account_number": "00000001234455",
  "type": "savings",
  "ifsc_code": "ICIC0000611",
  "cancelled_cheque": "file_e2d360e8c79f4143867fbf1665a5caee"
}

RESPONSE: 

{
  "id": "bac_98367e8972b43867a9c68a7c4605a31d",
  "object": "bank_account",
  "investor": "156",
  "account_holder_name": "Tony",
  "account_number": "00000001214415",
  "type": "savings",
  "ifsc_code": "ICIC0000611",
  "cancelled_cheque": "file_e2d360e8c79f4143867fbf1665a5caee",
  "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.
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
cancelled_cheque string yes File ID of the cancelled_cheque associated with the bank

Useful Tips:

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",
      "account_holder_name": "Tony",
      "account_number": "00000001214415",
      "type": "savings",
      "ifsc_code": "ICIC0000611",
      "cancelled_cheque": "file_e2d360e8c79f4143867fbf1665a5caee",
      "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",
  "account_holder_name": "Tony",
  "account_number": "00000001214415",
  "type": "savings",
  "ifsc_code": "ICIC0000611",
  "cancelled_cheque": "file_e2d360e8c79f4143867fbf1665a5caee",
  "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

Bank Account Verification

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

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_bca82dad078a43e38b853058c8ab48dc",
  "bank_account": "bac_98367e8972b43867a9c68a7c4605a31d",
  "status": "pending",
  "confidence": null,
  "reason": "digital_verification",
  "created_at": "2022-07-07T10:28:53+05:30",
  "updated_at": "2022-07-07T10:28:53+05:30",
  "failed_at": null,
  "completed_at": null
}
Attribute Type Nullable Remarks
id string no Unique identifier of the bank account verification
object string no Indicates the type of object. bank_account_verification
bank_account string no Bank account id of the investor
status string No pending : Bank account verification is in progress.
failed : Failed to verify the bank account.
completed : Verification completed.
If verification is completed, check the confidence value to determine the likelihood of this bank account belonging to the investor.
confidence string Yes The value tells us how confident are we about the likelihood of a bank account belonging to a particular investor. Possible values are very_high, high,uncertain,low,very_low,and zero
reason string Yes Describes the reason for the current status of the verification.
created_at string no Verification request creation timestamp
failed_at string yes Failure timestamp
completed_at string yes Completion timestamp
updated_at string yes Last updated timestamp

Create Bank Verification

Use the below endpoint to create bank account verification.

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

REQUEST:

{
  "bank_account": "bac_98367e8972b43867a9c68a7c4605a31d"
}

RESPONSE:

{
  "object": "bank_account_verification",
  "id": "bav_bca82dad078a43e38b853058c8ab48dc",
  "bank_account": "bac_98367e8972b43867a9c68a7c4605a31d",
  "status": "pending",
  "confidence": null,
  "reason": "digital_verification",
  "created_at": "2022-07-07T10:28:53+05:30",
  "updated_at": "2022-07-07T10:28:53+05:30",
  "failed_at": null,
  "completed_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.

Fetch Bank Account Verification by ID

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

GET /v2/bank_account_verifications/:id

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

RESPONSE:

{
  "object": "bank_account_verification",
  "id": "bav_bca82dad078a43e38b853058c8ab48dc",
  "bank_account": "bac_98367e8972b43867a9c68a7c4605a31d",
  "status": "pending",
  "confidence": null,
  "reason": "digital_verification",
  "created_at": "2022-07-07T10:28:53+05:30",
  "updated_at": "2022-07-07T10:28:53+05:30",
  "failed_at": null,
  "completed_at": null
}

Path Parameters

Name Mandatory Type Comments
id yes string This is the unique identifier linked to the account verification. For example bav_bca82dad078a43e38b853058c8ab48dc

Fetch all Bank Account Verifications

Use the below endpoint to fetch details of bank account verifications 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_bca82dad078a43e38b853058c8ab48dc",
      "bank_account": "bac_98367e8972b43867a9c68a7c4605a31d",
      "status": "completed",
      "confidence": "very_high",
      "reason": null,
      "created_at": "2022-07-07T08:59:58+05:30",
      "failed_at": null,
      "completed_at": "2022-07-07T09:00:06+05:30",
      "updated_at": "2022-07-07T09:00:06+05:30"
    }
  ]
}

Query Parameters

Name Mandatory Type Comments
status no string [] Possible Values:
- pending
- completed
- failed
reason no string [] Possible Values:
- digital_verification
- expiry
confidence no string [] Possible Values:
- very_high
- high
- uncertain
- low
- very_low
- zero
bank_accounts no string [] Bank account ids of an investor. For example, [bac_666929e99b7b4c9c94d4f838990eef89,bac_666929e99b7b4c9c94d4f838990eef89]

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, .me, .uk)

    • 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 records ordered by the created date desc

    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.

    Create a MF Purchase Plan Installment (Early Access)

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

    JSON Request:

    {
  "plan": "mfpp_dbabb25ba34c48329dbfbeff70c846f0"
}

    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": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
  "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
}

    POST /v2/mf_purchases

    For an existing mf_purchase_plan with auto_generate_installments = false, pass the plan v2 id to generate the installment. More about installment generation.

    Note:

    In the sandbox environment (non-production), even if auto_generate_installments = true, you can use this API to simulate installment generation.

    Request Parameters

    Name Mandatory Type Comments
    plan yes string (Early Access) Provide the V2 id of the mf_purchase_plan for which installment must be generated

    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.
    plan_basket no string (Early Access) Provide the plan basket id to fetch purchase orders that belong to a particular plan basket.
    skip_instruction no string (Early Access) Provide skip instruction id to fetch purchase orders that belong to the particular skip instruction.
    plan no string (Early Access) mf_purchase_plan id
    states no string (Early Access) Comma separated values of purchase states

    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.

    Create a MF Redemption Plan Installment (Early Access)

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

    JSON Request:

    {
  "plan": "mfrp_dbabb25ba34c48329dbfbeff70c846f0"
}

    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": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "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"
}

    POST /v2/mf_redemptions

    For an existing mf_redemption_plan with auto_generate_installments = false, pass the plan v2 id to generate the installment. More about installment generation.

    Note:

    In the sandbox environment (non-production), even if auto_generate_installments = true, you can use this API to simulate installment generation.

    Request Parameters

    Name Mandatory Type Comments
    plan yes string (Early Access) Provide the V2 id of the mf_redemption_plan for which installment must be generated

    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",
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  }
}

    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. Possible values:
    - confirmed
    consent conditional hash Consent from investor for confirming the redemption order

    As per SEBI regulations, investor consent must be obtained by sending a One-Time Password to the investor at his/her email/phone number registered against the folio before the redemption order can be sent to rtas.

    Name Mandatory Type Comments
    email conditional string Mandatory if consent is obtained via email.
    The value must be one of the email addresses registered against the folio.
    isd conditional string Supported value
    - 91
    mobile conditional string Mandatory if consent is obtained via mobile.
    The value must be one of the mobile numbers registered against the folio.

    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.
    plan_basket no string (Early Access) Provide the plan basket id to fetch redemption orders that belong to a particular plan basket.
    skip_instruction no string (Early Access) Provide skip instruction id to fetch redemption orders that belong to the particular skip instruction.
    plan no string (Early Access) mf_redemption_plan id
    states no string (Early Access) Comma separated values of redemption states

    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.

    Create a MF Switch Plan Installment (Early Access)

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

    JSON Request:

    {
  "plan": "mfsp_dbabb25ba34c48329dbfbeff70c846f0"
}

    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": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "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
}

    POST /v2/mf_switches

    For an existing mf_switch_plan with auto_generate_installments = false, pass the plan v2 id to generate the installment. More about installment generation.

    Note:

    In the sandbox environment (non-production), even if auto_generate_installments = true, you can use this API to simulate installment generation.

    Request Parameters

    Name Mandatory Type Comments
    plan yes string (Early Access) Provide the V2 id of the mf_switch_plan for which installment must be generated

    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",
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  }
}

    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
    consent yes hash Consent from investor for confirming the redemption

    As per SEBI regulations, investor consent must be obtained by sending a One-Time Password to the investor at his/her email/phone number registered against the folio before the switch order can be sent to rtas.

    Name Mandatory Type Comments
    email conditional string Mandatory if consent is obtained via email.
    The value must be one of the email addresses registered against the folio.
    isd conditional string Supported value
    - 91
    mobile conditional string Mandatory if consent is obtained via mobile.
    The value must be one of the mobile numbers registered against the folio.

    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.
    plan_basket no string (Early Access) Provide the plan basket id to fetch switch orders that belong to a particular plan basket.
    skip_instruction no string (Early Access) Provide skip instruction id to fetch switch orders that belong to the particular skip instruction.
    plan no string (Early Access) mf_switch_plan id
    states no string (Early Access) Comma separated values of switch states

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

    SIPs

    Plan represents the recurring investment orders scheduled on a monthly basis (monthly SIPs). The API allows you to create, update and cancel the SIPs for an investment account.

    Endpoints:

    POST /api/oms/investment_accounts/:id/orders/sips
    PATCH /api/oms/investment_accounts/:id/orders/sips/:id
    GET /api/oms/investment_accounts/:id/orders/sips/:id
    GET /api/oms/investment_accounts/:id/orders/sips/:id/installments
    GET /api/oms/investment_accounts/:id/orders/sips

    Create a SIP

    curl -X POST "https://s.finprim.com/api/oms/investment_accounts/123/orders/sips"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

    JSON request

    {
  "orders": [
    {
      "isin": "INF204KA1B64",
      "amount": 10000,
      "start_day": "2",
      "frequency": "MONTHLY",
      "installments": 20,
      "mandate_id": 23,
      "source_ref_id": "0876789",
      "user_ip": "192.168.2.92",
      "server_ip": "192.168.2.95"
    }
  ]
}

    JSON response

    {
  "orders": [
    {
      "id": 2654461373273791985,
      "isin": "INF204KA1B64",
      "folio_number": "sgerhh2422343424",
      "user_ip": "192.168.2.92",
      "server_ip": "192.168.2.95",
      "source_ref_id": "0987656"
    },
    {
      "id": 798881668533720940,
      "isin": "INF204KA1B84",
      "source_ref_id": "0876789",
      "user_ip": "192.168.2.92",
      "server_ip": "192.168.2.95"
    }
  ]
}

    POST /api/oms/investment_accounts/:id/orders/sips

    Create a monthly systematic investment plan (SIP). SIP is allowed only for certain schemes (refer sip_allowed attribute in the fund scheme api)

    Note : The fund parameters mentioned in the comments below are availabe in Single Fund Schemes Detail API response

    Parameters

    Name Mandatory Type Comments
    isin yes string fund ISIN number
    amount yes integer amount should be in multiple of sip_multiples and between min_sip_amount and max_sip_amount
    start_day yes string start_day should be one of the values received in sip_frequency_data
    frequency yes string currently only "MONTHLY" frequency is supported
    installments yes integer installments should be between min_sip_installments and 1200 inclusive
    folio_number no string mandatory if you need to place an additional sip in the given folio number
    mandate_id yes integer mandate ID returns in Create Mandate API response
    generate_first_installment_now no boolean By default, the value of this flag is false. If this flag is true, the first installment is generated immediately after SIP creation and the first installment will be in PENDING state (Coming soon on BSE gateway)
    source_ref_id no string this is a source reference ID which will unique across system for a sip (ideally an auto generate identifier / uuid to identify a SIP in the tenant's application)
    user_ip no string IP address of user
    server_ip no string IP address of server

    Accepting payment for first installment on the day of SIP 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 SIP is created and the first installment will be in PENDING state. This installment can then be fetched using Fetch_Installments_API. After the installment is fetched 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

    Modify a SIP

    curl -X PATCH "https://s.finprim.com/api/oms/investment_accounts/123/orders/sips/345"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '{json_request}'

    JSON request

    {
  "operation": "update",
  "data": {
    "mandate_id": "DQ12"
  }
}

    JSON response

    For `update` operation

    {
  "message": "successfully updated the sip"
}

    For `deactivate` operation

    {
  "sip_id": 1,
  "active": false,
  "amount": 10000,
  "frequency": "MONTHLY",
  "start_date": "2017-10-25",
  "installments": 20,
  "folio_number": null,
  "mandate_id": "DF23",
  "fund_scheme_id": 1,
  "fund_type": "GROWTH",
  "_links": {
    "self": {
      "href": "http://dev.mfpro.cybrilla.io/api/oms/investment_accounts/1/orders/sips/1"
    }
  }
}

    For `cancel_next_installment` operation

    {
  "id": 2,
  "type": "PURCHASE",
  "status": "CANCELLED",
  "amount": 10000,
  "reverse_amount": null,
  "reverse_units": null,
  "nav": null,
  "stt": null,
  "trade_date": null,
  "investment_date": "2017-10-25",
  "folio_number": null,
  "bank_account_id": null,
  "fund_scheme": {
    "id": 1,
    "name": "Motilal Oswal MOSt Focused Multicap 35 Fund Growth",
    "scheme_code": "CPGP"
  }
}

    PATCH /api/oms/investment_accounts/:id/orders/sips/:id

    Update the payment mandate for a SIP, cancel the next installment or all the future installments of a SIP

    Parameters

    Name Mandatory Type Comments
    operation yes string Allowed values for RTA Gateway: update, deactivate, cancel_next_installment
    Allowed values for BSE Gatweay: deactivate
    mandate_id conditional string ID of the mandate object. Required if the operation is update

    BSE SIP Deactivation Note :

    Fetch a SIP

    curl -X GET "https://s.finprim.com/api/oms/investment_accounts/123/orders/sips/434
  -H "Authorization: Bearer ACCESS_TOKEN"

    JSON response

    {
  "sip_id": 34,
  "active": true,
  "amount": 12000,
  "frequency": "MONTHLY",
  "start_date": "2018-05-21",
  "installments": 189,
  "folio_number": null,
  "mandate_id": "7",
  "isin": "INF204K01VA4",
  "source_ref_id": "O_40570"
}

    GET /api/oms/investment_accounts/:id/orders/sips/:id

    Fetch the details of a particular SIP

    Fetch installments of a SIP

    curl -X GET "https://s.finprim.com/api/oms/investment_accounts/123/orders/sips/345/installments"
  -H "Authorization: Bearer ACCESS_TOKEN"

    JSON response

    [
  {
    "id": 978,
    "type": "PURCHASE",
    "status": "SUCCESSFUL",
    "amount": 25000,
    "reverse_amount": null,
    "reverse_units": null,
    "price": null,
    "trade_date": null,
    "investment_date": "2017-09-10",
    "folio_number": "799515310622345",
    "bank_account_id": null,
    "source_ref_id": "AMC_36089",
    "sip_id": 425,
    "fund_scheme": {
      "id": 803,
      "name": "Mirae Asset Emerging Bluechip Fund - Regular Plan - Growth Option",
      "isin": "INF769K01101",
      "scheme_code": "EBRG"
    }
  }
]

    Retrieve all the installments of a particular SIP

    HTTP Request

    GET /api/oms/investment_accounts/:id/orders/sips/:id/installments

    List all SIPs

    curl -X GET "https://s.finprim.com/api/oms/investment_accounts/123/orders/sips"
  -H "Authorization: Bearer ACCESS_TOKEN"

    JSON response

    {
  "sip_orders": [
    {
      "sip_id": 15,
      "active": true,
      "amount": 80000,
      "frequency": "MONTHLY",
      "start_date": "2018-02-10",
      "installments": 11,
      "folio_number": null,
      "mandate_id": "7",
      "isin": "INF204K01UN9",
      "source_ref_id": "O_40526"
    },
    {
      "sip_id": 16,
      "active": true,
      "amount": 1000,
      "frequency": "MONTHLY",
      "start_date": "2017-12-12",
      "installments": 36,
      "folio_number": "143RGY45679",
      "mandate_id": "45",
      "isin": "INF903J01538",
      "source_ref_id": "O_35626"
    }
  ],
  "last": false,
  "total_pages": 2,
  "total_elements": 31,
  "size": 20,
  "number": 0,
  "first": true,
  "number_of_elements": 20,
  "_links": {
    "self": {
      "href": "https://tenant.s.finprim.com/api/oms/investment_accounts/1111111/orders/sips"
    }
  }
}

    GET /api/oms/investment_accounts/:id/orders/sips

    Retreive all the SIPs for an investment account

    Query Parameters

    Parameter Mandatory Default Description
    page no 0 page number of the result set
    size no 20 number of results per page, size should not be greater than 100

    FP Transaction Plans(Early Access)

    Transaction plans are used to generate orders on a recurring basis. FP supports 3 types of orders: Mutual fund purchase orders, Mutual fund redemption orders, and Mutual fund switch orders. If you want to generate these orders on a recurring basis, there are transaction plans for each order type viz. MF Purchase plans, MF Redemption plans, and MF Switch plans. All these plans (Purchase plan, Redemption plan, or Switch plan) have certain common characteristics. A solid understanding of these common characteristics will aid in implementing any kind of plan.

    Plan mode

    By default, an MF Purchase plan generates lump sum purchases as installments, an MF Redemption plan generates redemption orders as installments and an MF switch plan generates switch orders as installments. The validations that are applicable when you create such orders manually are also applicable for installments generated via such plans. Apart from these validations, there are no restrictions on such plans. However, you can also register a plan as systematic. In such cases, an MF Purchase plan will be treated as a SIP, an MF Redemption plan will be treated as an SWP, and an MF Switch plan will be treated as STP. When a plan's mode is systematic, there will be some restrictions depending on the order gateway and other factors.

    Plan states

    State Description
    created The plan has been registered on FP but is yet to be activated. Irrespective of the type of plan, activation is automatically attempted by FP without any further intervention.
    active The plan is active. Only installments of an active plan can be generated and processed.
    canceled The plan has been deactivated. No further installments will be generated.
    completed Lifecycle of a plan is completed i.e all the installments have been generated.
    failed Failure to activate a plan.

    State transitions

    created active canceled completed failed
    created NA Yes Yes No Yes
    active No NA Yes Yes No
    canceled No No NA No No
    completed No No No NA No
    failed No No No No NA

    1. Transitioning from created to active

    Restrictions when the mode is systematic - If the order gateway is BSE, the plan must be registered at BSE also, and only after successful plan registration at BSE, the plan transitions from created to active - If the order gateway is BSE, and delayed activation has been requested, the plan activation will happen on or after the date on which activation was requested while creating the plan

    2. Transitioning from created to failed

    As noted earlier, if the mode is systematic, and order gateway = BSE, the plan becomes active only if the plan is registered at BSE also. If for some reason, the plan registration at BSE fails, the plan transitions from created ⇒ failed state.

    3. Transitioning from created to canceled

    In cases of plans where delayed activation is opted for, you can request a cancellation before the plan becomes active, and the plan will transition from created to canceled state.

    Note: As noted earlier, if mode = systematic, and order gateway = BSE, it takes time for a plan to become active. In such cases, if you choose to cancel a plan even before activation, the plan can have a created to canceled transition.

    4. Transitioning from active to completed

    This transition happens automatically once all installments of a plan are generated. If the last installment of a plan is generated but is yet to be processed completely, the plan will still be marked as completed.

    5. Transitioning from active to canceled

    Installments that are already generated, will not be impacted by the cancellation of a transaction plan. However, no installments of the plan can be generated after a plan reaches a canceled state. Also, no modification can be made to a plan after a plan reaches the canceled state. The cancellation of the plan happens immediately.

    Restrictions when the mode is systematic

    If mode is systematic, and order gateway = BSE, the cancellation happens asynchronously and will take some time. We will cover more on this topic when we discuss Purchase plans, Redemption plans, and Switch plans.

    Attribute Data type Nullable? Remarks
    state string No Plan's state
    created_at timestamp No Plan creation timestamp
    activated_at timestamp Yes Plan activation timestamp
    cancelled_at timestamp Yes Plan cancellation timestamp
    failed_at timestamp Yes Plan failure timestamp
    completed_at timestamp Yes Plan completion timestamp
    reason string Yes Reason for the state of the plan. For example, if the state is canceled, the reason might contain a cancellation reason.

    Managing recurrence of a plan.

    Any transaction plan will let you specify the following - How often a transaction must be generated (Ex: Monthly, Quarterly etc). This is known as the frequency of a transaction plan. - On what specific day a transaction must be generated (Ex: 25th of every month) - This is known as installment_day of a transaction plan - From what point in time must the transactions start getting processed (Ex: 25th August 2024) - This is known as the requested_activation_date of a transaction plan. By default, no requested_activation_date is required and FP will automatically start the plan on an immediately possible date. - How many times a plan must generate installments according to the frequency? - This is known as the number_of_installments of a transaction plan.

    Different frequencies of a transaction plan

    Frequency Remarks
    daily Transactions will be processed every business day. Transactions are not processed on market holidays.installment_day value is not applicable in this case.
    day_in_a_week You can select installment_day as any day between Monday=1 to Friday=5. On every selected day of the week, installments will be processed. For example, if you choose Monday as the installment_day, every Monday, installments will be processed. If a particular Monday falls on a market holiday, the installment will be processed on the immediate next working day. Also, in a particular month, there are 5 Mondays and in another month, there are 4 Mondays, installments will be processed 5 times and 4 times in those months respectively.
    four_times_a_month This is a variation of weekly SIP where every month, a fixed number of installments(4 per month) is processed.installment_day value can range from 1 - 28
    day_in_a_fortnight You can select installment_day as any day between Monday to Friday. On every selected day of the alternate week, installments will be processed. For example, if you choose Monday as the installment_day, every alternate Monday, installments will be processed. If a particular Monday falls on a market holiday, the installment will be processed on the immediate next working day. Also, in a particular month, if there are 5 Mondays, installments will be processed 3 times for that month if the first installment of that month is processed on the first Monday.
    twice_a_month This is a variation of fortnightly SIP where every month, a fixed number of installments(2 per month) is processed. In such cases, the installment_day is treated as the day in the calendar month and not a day in a week such as Monday or Friday. installment_day value can range from 1 - 28
    monthly 1 installment per month on the day specified via installment_day. If the day of installment happens to be a market holiday, the installment will be processed on the next business day.If the installment_day is 29,30 or 31 and in a particular month those days are not present, the installments will be processed on day 1 of the next month. If day 1 of next month is a market holiday, the transaction will be processed on the immediate next working day.
    quarterly 1 installment per quarter on the day specified via installment_day. If the day of installment happens to be a market holiday, the installment will be processed on the next business day.If the installment_day is 29,30 or 31 and in a particular month of the quarter those days are not present, the installments will be processed on day 1 of the next month. If day 1 of next month is a market holiday, the transaction will be processed on the immediate next working day. When quarterly plans are registered, FP will automatically try to generate the first installment on installment_day in the current month of the quarter. If that is not possible, an installment will be generated in the next quarter. From there, installments are generated after every quarter. However, using requested_activation_date, you can choose the month of the quarter on which the first installment should start.For example:
    SIP Registration date:July 21st 2022
    Requested activation date:August 15th 2022
    installment_day:1
    First installment date:September 1st 2022
    half-yearly Very similar to quarterly in behavior. 1 installment per 6 months on the day specified via installment_day.
    yearly Very similar to quarterly in behavior. 1 installment per year on the day specified via installment_day.
    sporadic This is a special type of frequency where you can generate installments whenever you want. Not available if the mode is systematic

    Using number_of_installments to specify when to complete a plan.

    Special considerations when the mode is systematic - In cases of systematic plans, RTAs expect the installment count to be greater than a certain threshold. For example, this threshold is 6 minimum installments for SIPs usually. If you register an RTA SIP on FP with number_of_installments = 1, we internally register the SIP with RTAs with installment count as 6(which is the threshold.). However, after 1 installment is processed, we stop sending further installments to RTAs. - If the order gateway is BSE, the minimum number_of_installments must be greater than or equal to the minimum number_of_installments expected by that scheme/plan type. For example, in the case of SIPs, number_of_installments must be greater than or equal to 6 usually.

    Never-ending plans

    You can also keep the number_of_installments as null, and installments will be generated perpetually. This feature is not available if the mode is systematic

    Attribute Data type Nullable
    frequency string No
    installment_day integer Yes
    requested_activation_date date Yes
    number_of_installments integer Yes

    Installment generation

    Types of installment generation

    Attribute Data type Can be null? Remarks
    auto_generate_installments boolean No If true, FP generates installments. If not, you will have to generate installments.

    Definition of the day of the installment

    The definition of the day of installment depends on the plan type. FP supports 3 types of plans and the day installment definition is as follows

    Plan type Definition
    MF Purchase plan The day on which the payment collection happens
    MF Redemption plan The day on which redemption orders are submitted to RTA
    MF Switch plan The day on which redemption orders are submitted to RTA

    Behavior when you delegate installment generation to FP

    Examples

    Plan Installment type Gateway Frequency Installment day Registration date First installment date
    Purchase plan Systematic RTA Monthly 15 August 15th, 2022 September 15th, 2022
    Purchase plan Systematic RTA Monthly 16 August 15th, 2022 August 16th, 2022
    Purchase plan Systematic BSE Monthly 15 August 15th, 2022 September 15th, 2022
    Purchase plan Systematic BSE Monthly 17 August 15th, 2022 September 17th, 2022
    Purchase plan Normal RTA Monthly 15 August 15th, 2022 September 15th, 2022
    Purchase plan Normal RTA Monthly 16 August 15th, 2022 August 16th, 2022
    Purchase plan Normal BSE Monthly 15 August 15th, 2022 September 15th, 2022
    Purchase plan Normal BSE Monthly 16 August 15th, 2022 August 16th, 2022
    Redemption/Switch plan Any Any Monthly 15 August 15th. 2022 September 15th, 2022
    Redemption/Switch plan Any Any Monthly 16 August 15th, 2022 August 16th, 2022

    Overcoming the minimum gap restrictions

    Simulate installment generation

    To help developers with testing in sandbox (non-production), for a plan with auto_generate_installments = true, below respective manual installment generation apis can be used to simulate generating installments.

    MF Purchase Plan Installment Generation
    MF Redemption Plan Installment Generation
    MF Switch Plan Installment Generation

    Installment information exposed by every transaction plan

    start_date - Date of installment of the first installment of the plan. - Will be available post plan activation if auto_generate_installments=true. - In the case of auto_generate_installments=false, the start_date will be populated only after you generate the first installment and it will be the date of generation of the first installment.

    end_date - Date of installment of the last installment of the plan. - Will be available post plan activation if auto_generate_installments=true. - In the case of auto_generate_installments=false, the end_date will be populated only when the plan is marked as completed. - This date will not be available if number_of_installments=null

    previous_installment_date - Date of installment of the previous installment - After plan completion, the value will equal end_date - Will be null at first. If FP is managing installment generation, once the date of installment of the nth (where n>=1) installment of the plan is passed, the previous_installment_date is set as the date of installment of nth installment. - If you are managing the installment generation, once you generate nth (where n>=2) installment, the previous_installment_date is set as the date of installment of n-1th installment.

    next_installment_date - Date of installment of the next installment - Will always be null if auto_generate_installments = false. - If FP is managing installment generation, next_installment_date will be set as the date of the first installment once the plan becomes active. After that, once the date of installment of the nth (where n>=1) installment of the plan is passed, the next_installment_date is set as date of installment of n+1th installment. - If a plan is completed, the next_installment_date will be null.

    remaining_installments - The number of installments yet to be generated. - Will be null if state = created or failed - Will always be null if number_of_installments = null (Perpetual plans) - Will be equal to number_of_installments when the plan becomes active. - Will always be null if the frequency is sporadic - Will become 0 once the plan is completed.

    Other common plan attributes

    Attribute Data type Can be null? Remarks
    object string No Name of the transaction plan type object : Example: mf_purchase_plan, mf_redemption_plan etc
    id string No Unique id assigned by FP to identify the plan
    mf_investment_account string No Id of the investment account against which this plan is created.
    folio_number string Yes If the plan is a mutual fund transaction plan, every plan will also have this attribute to specify the folio against which the installments will be mapped.
    source_ref_id string Yes A unique identifier generated by API consumer to identity a particular plan. This is unique across plans of all types(purchase_plan, redemption_plan, and switch_plan).
    partner string No The id of the distributor/ria associated with the plan.
    gateway string No 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 No 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

    Modifying plans

    Changing number_of_installments

    Restrictions when the mode is systematic - You can't change number_of_installments if the mode is systematic and order gateway = BSE - If the order gateway is RTA, The new value cannot be greater than the original number_of_installments with which the systematic plan was registered with the order gateway. This means that when modifying, the new value can range from [number_of_installments - remaining_installments + 1] to [original number_of_installments reported during registration]. If the new value is less than the original number_of_installments reported during registration, we will mark the plan as completed once the total number of installments generated = new value and we will not send any more installments. - You can't set number_of_installments = null if mode is systematic

    Skipping installments via skip instructions

    Restrictions when the mode is systematic - This facility is not available for systematic plans registered via BSE gateway - If you skip installments beyond a certain threshold, the RTAs might cancel the systematic plan registration at their end. For example, if you skip 3 or more SIP installments, RTA might cancel the registration depending on the scheme and frequency. Please note that FP doesn't' block creation of skip instructions if you are trying to skip installments beyond allowed threshold set by RTAs.

    Skip instruction object attributes

    Attribute Data type Can be null? Remarks
    object string No Will always be skip_instruction
    id string No Unique id assigned by FP to identify skip instruction
    plan string No Transaction plan identifier
    state string No Values : pending,active,completed, canceled
    from string No The date from which the installments must be skipped
    to string Yes The date till which the installments must be skipped.
    remaining_installments int No The number of installments remaining to be skipped.
    skipped_installments int No The number of installments skipped already.
    created_at date No The date on which this skip instruction is created.
    canceled_at date Yes The date on which this skip instruction was canceled.
    completed_at date Yes The date on which this skip instruction was canceled.

    Create a skip instruction

    POST /v2/<plan_type>s/:id/skip_instructions

    Request parameters

    Name Mandatory Type Comments
    from Yes date The date from which the installments must be skipped.
    to No date The date till which the installments must be skipped.

    Fetch a skip instruction by its id

    GET /v2/<plan_type>s/skip_instructions/:id

    This API is used to fetch a skip instruction by its id

    Query Parameters

    Name Mandatory Type Comments
    id yes string Id of the skip instruction.

    Cancel a skip instruction

    POST /v2/<plan_type>s/skip_instructions/:id/cancel

    This API is used to cancel a skip instruction.

    List all skip instructions

    GET /v2/<plan_type>s/:id/skip_instructions

    This API is used to list all skip instructions against a plan.

    Query Parameters

    Name Mandatory Type Comments
    statuses no string array Skip instruction statues. By default, the value will be null i.e. skip instructions of all statuses against a particular plan will be displayed. You can provide status values like pending,active,completed, canceled to filter by statuses

    Marking the plan as completed

    In the case of perpetual plans or plans with frequency = sporadic, you can explicitly mark the plan as completed, to let FP know that no more installment generation should be allowed against this plan.

    Cancelling a plan

    Restrictions when the mode is systematic - In the case of MFPurchase plan and mode=systematic and order gateway = BSE, gap is 3 working days. i.e. only if you cancel the plan before 3 working days from the date of the next installment, the next installment will not be processed. If not, the next installment will be processed and subsequent installments after that will not be processed. - In the case of MFRedemption plan/MFSwitch plan and the mode is systematic and order gateway = BSE, gap is 1 working day.

    Scheduling cancellation

    Other modifications

    You can also modify the values of the following attributes of a plan - amount - scheme (switch in & switch out scheme in case of MF Switch plans) - folio_number - euin

    Any update will only impact installments that will be generated after the modification and not the installments generated already.

    Transaction Plan Baskets(Early Access)

    Endpoints

    POST /v2/plan_baskets/
    PATCH /v2/plan_baskets/
    GET /v2/plan_baskets/:id
    GET /v2/plan_baskets
    POST /v2/plan_baskets/:id/cancel

    Transaction plan basket object

    {
  "object": "plan_basket",
  "id": "mfpb_14bafabfbfbc423d9b54412dd577981b",
  "mf_investment_account": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "plans": [
    "mfpp_189111b00566431db0dace5332db519c",
    "mfpp_289111b00566431db0dace5332db519c"
  ],
  "created_at": "2022-04-06T15:32:52+05:30"
}
    Attribute Data type Can be null? Remarks
    object string No Will always be plan_basket
    id string No Unique id assigned by FP to identify the basket
    mf_investment_account string No Id of the investment account against which this plan basket is created.
    source_ref_id string Yes Unique identifier. 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)
    plans string [] Yes Ids of transaction plans present in the basket.
    created_at Timestamp No Basket creation timestamp

    Create a transaction plan basket

    POST /v2/plan_baskets/

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

    JSON Request:

    {
  "mf_investment_account": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "plans": [
    "mfpp_189111b00566431db0dace5332db519c",
    "mfpp_289111b00566431db0dace5332db519c"
  ]
}

    JSON Response:

    {
  "object": "plan_basket",
  "id": "mfpb_14bafabfbfbc423d9b54412dd577981b",
  "mf_investment_account": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "plans": [
    "mfpp_189111b00566431db0dace5332db519c",
    "mfpp_289111b00566431db0dace5332db519c"
  ],
  "created_at": "2022-04-06T15:32:52+05:30"
}

    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.
    plans Yes string List of plan ids. Note: This can be the V2 id of MF Purchase plan/MF Redemption plan or MF Switch plan

    Update a transaction plan basket

    PATCH /v2/plan_baskets/

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

    JSON Request:

    {
  "id": "mfpb_14bafabfbfbc423d9b54412dd577981b",
  "plans": [
    "mfpp_189111b00566431db0dace5332db519c",
    "mfrp_289111b00566431db0dace5332db520c"
  ]
}

    JSON Response:

    {
  "object": "plan_basket",
  "id": "mfpb_14bafabfbfbc423d9b54412dd577981b",
  "mf_investment_account": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "plans": [
    "mfpp_189111b00566431db0dace5332db519c",
    "mfrp_289111b00566431db0dace5332db520c"
  ],
  "created_at": "2022-04-06T15:32:52+05:30"
}

    Request Parameters

    Name Mandatory Type Comments
    id Yes string Plan basket id
    plans Yes string List of plan ids.

    Fetch a plan basket by its id

    GET /v2/plan_baskets/:id

    This API can be used to fetch a plan basket by its id.

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

    JSON Response:

    {
  "object": "plan_basket",
  "id": "mfpb_14bafabfbfbc423d9b54412dd577981b",
  "mf_investment_account": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "plans": [
    "mfpp_189111b00566431db0dace5332db519c",
    "mfpp_289111b00566431db0dace5332db519c"
  ],
  "created_at": "2022-04-06T15:32:52+05:30"
}

    List all plan baskets

    This API can be used to list all plan baskets against an investment account.

    curl -X GET "https://s.finprim.com/v2/plan_baskets?investment_account=mfia_14bafabfbfbc423d9b54412dd577981b"
  -H "Authorization: Bearer ACCESS_TOKEN"

    JSON Response:

    {
  "object": "list",
  "data": [
    {
      "object": "plan_basket",
      "id": "mfpb_14bdfabfbfbc423d9b54412dd566981b",
      "mf_investment_account": "mfia_14bafabfbfbc423d9b54412dd577981b",
      "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
      "plans": [
        "mfpp_189111b00566431db0dace5332db519c",
        "mfpp_289111b00566431db0dace5332db519c"
      ],
      "created_at": "2022-04-06T15:32:52+05:30"
    },
    {
      "object": "plan_basket",
      "id": "mfpb_15bafabfbfbc423d9b54412dd577981b",
      "mf_investment_account": "mfia_14bafabfbfbc423d9b54412dd577981b",
      "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
      "plans": [
        "mfpp_189111b00566431db0dace5332db519c",
        "mfrp_289222b00566431db0dace5332db519c"
      ],
      "created_at": "2022-04-06T15:32:52+05:30"
    }
  ]
}

    Query Parameters

    Name Mandatory Type Comments
    investment_account yes string V2 Id of the investment account whose plan baskets must be listed.

    Cancel a plan basket

    POST /v2/plan_baskets/:id/cancel

    This API can be used to cancel all plans of a plan basket in one shot. 

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

    JSON Response:

    {
  "object": "plan_basket",
  "id": "mfpb_14bafabfbfbc423d9b54412dd577981b",
  "mf_investment_account": "mfia_14bafabfbfbc423d9b54412dd577981b",
  "source_ref_id": "fad6ca01-a002-46ab-8e5c-ea6fe195a5de",
  "plans": [
    "mfpp_189111b00566431db0dace5332db519c",
    "mfpp_289111b00566431db0dace5332db519c"
  ],
  "created_at": "2022-04-06T15:32:52+05:30",
  "cancelled_at": "2022-04-08T15:32:52+05:30"
}

    MF Purchase Plans(Early Access)

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

    Endpoints

    POST /v2/mf_purchase_plans
    PATCH /v2/mf_purchase_plans
    GET /v2/mf_purchase_plans/:id
    GET /v2/mf_purchase_plans
    POST /v2/mf_purchase_plans/:id/cancel
    POST /v2/mf_purchase_plans/:id/complete
    POST /v2/mf_purchase_plans/:id/skip_instructions
    GET /v2/mf_purchase_plans/skip_instructions/:id
    POST /v2/mf_purchase_plans/skip_instructions/:id/cancel
    GET /v2/mf_purchase_plans/:id/skip_instructions

    Purchase Plan Object Structure

    {
  "object": "mf_purchase_plan",
  "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "systematic": true,
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "auto_generate_instalments": true,
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "requested_activation_date": null,
  "number_of_installments": 7,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "payment_method": null,
  "payment_source": null,
  "purpose": "children_education",
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_at": null,
  "reason": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app"
}
    Attribute Data type Can be null? Remarks
    object string No Will always be mf_purchase_plan
    id string No Unique identifier of the mf_purchase_plan object
    mf_investment_account string No 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 Yes Indicates the folio in which the purchases resulting from this plan will be made
    scheme string No ISIN of the scheme against whose units must be purchased periodically.
    amount decimal No Periodic purchase amount
    systematic boolean No The value of this attribute indicates the way this purchase plan is registered with order gateways. If the true, 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 false, it means that FP will create purchase orders according to the defined schedule and send the installments as normal purchase orders to order gateways.
    gateway string No The gateway through which the order must be processed. Possible values: rta, ,bse
    frequency string No See details here
    installment_day integer Yes See details here
    requested_activation_date date Yes See details here
    number_of_installments integer No See details here
    start_date date Yes See details here
    end_date date Yes See details here
    next_installment_date date Yes See details here
    previous_installment_date date Yes See details here
    remaining_installments Yes integer See details here
    state string No See details here
    auto_generate_installments boolean No See details here
    payment_method Yes string The payment method that must be used for collecting payments against the installments.Possible value:mandate.
    payment_source Yes string Unique identifier identifying the payment collection instrument. For example, If payment_method is mandate, payment_source will be the mandate id.
    purpose string Yes Why was this purchase plan created? Possible values can be children_education, children_marriage, house, car, travel, retirement, others
    source_ref_id string Yes See details here
    partner string No See details here
    gateway string No See details here
    euin string Yes See details here
    user_ip string Yes See details here
    server_ip string Yes See details here
    initiated_by string Yes See details here
    initiated_via string Yes See details here
    created_at timestamp No See details here
    activated_at timestamp Yes See details here
    cancelled_at timestamp Yes See details here
    cancellation_scheduled_on date Yes See details here
    failed_at timestamp Yes See details here
    completed_at timestamp Yes See details here
    reason string Yes See details here

    Create a purchase plan

    POST /v2/mf_purchase_plans

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

    JSON Request:

    {
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "scheme": "INF204KA1B64",
  "frequency": "monthly",
  "folio_number": "1234567890",
  "amount": 1000.0,
  "installment_day": 1,
  "number_of_installments": 7,
  "systematic": true,
  "payment_method": "mandate",
  "payment_source": "man_89111b00566431db0dace538hgc",
  "purpose": "children_education",
  "generate_first_installment_now": true,
  "auto_generate_installments": true,
  "activate_after": null,
  "euin": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app",
  "user_ip": null,
  "server_ip": null,
  "source_ref_id": null
}

    JSON Response:

    {
  "object": "mf_purchase_plan",
  "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "systematic": true,
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "auto_generate_instalments": true,
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "requested_activation_date": null,
  "number_of_installments": 7,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "payment_method": null,
  "payment_source": null,
  "purpose": "children_education",
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_at": null,
  "reason": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app"
}

    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 See details here. Please note that the frequencies weekly, fortnightly, and half_yearly are not supported when order gateway is bse and systematic=true
    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 systematic = true, amount should be in multiples of sip_multiples and between min_sip_amount and max_sip_amount
    2) If systematic = false 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 systematic = false 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
    installment_day No integer See details here
    number_of_installments No integer See details here
    systematic Yes string If true, the plan is registered as a SIP. Else, normal purchase orders are generated as installments.
    payment_method No string The payment method that must be used for collecting payments against the installments.Possible value:mandate. Mandatory if payment_source is not null.
    payment_source No string Unique identifier identifying the payment collection instrument. For example, If payment_method is mandate, payment_source will be the mandate id. Mandatory if payment_method is not null.
    purpose No string Why was this purchase plan created? Possible values can be children_education, children_marriage, house, car, travel, retirement, others
    generate_first_installment_now No boolean The value is false by default. This option is not available if you have opted to generate installments by yourself OR if you have opted for delayed activation of the plan.
    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 systematic=true, this value must be false. By default, the value is true
    activate_after No string A date in the 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(systematic=true) 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 See details here
    initiated_via No string See details here
    euin No string See details here
    user_ip No string See details here
    server_ip No string See details here
    source_ref_id No string See details here

    Update a purchase plan

    PATCH /v2/mf_purchase_plans

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

    JSON Request:

    {
  "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
  "amount": 1500.0,
  "folio_number": "1234567899"
}

    JSON Response:

    {
  "object": "mf_purchase_plan",
  "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567899",
  "systematic": false,
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "auto_generate_instalments": true,
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "requested_activation_date": null,
  "number_of_installments": 7,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1500.0,
  "payment_method": null,
  "payment_source": null,
  "purpose": "children_education",
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_at": null,
  "reason": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app"
}

    Request Parameters

    Name Mandatory Type Comments
    id Yes string Plan id
    amount No decimal Allowed only if systematic=false
    scheme No string Allowed only if systematic=false
    folio_number No string Allowed only if systematic=false
    euin No string See details here
    cancellation_scheduled_on No date See details here
    payment_source No string Can be used to change the mandate against the plan. If the value is null, only installments will be generated, and no payments will be created.

    Fetch a purchase plan by its id

    GET /v2/mf_purchase_plans/:id

    This API can be used to fetch a purchase plan by its id.

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

    JSON Response:

    {
  "object": "mf_purchase_plan",
  "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "systematic": true,
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "auto_generate_instalments": true,
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "requested_activation_date": null,
  "number_of_installments": 7,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "payment_method": null,
  "payment_source": null,
  "purpose": "children_education",
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_at": null,
  "reason": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app"
}

    List all purchase plans

    GET /v2/mf_purchase_plans

    This API is used to fetch all purchase plans.

    curl -X GET "https://s.finprim.com/v2/mf_purchase_plans?mf_investment_account=mfia_798fa03aba614840b983609e89ed16f2&states=active"
  -H "Authorization: Bearer ACCESS_TOKEN"

    JSON Response:

    {
  "object": "list",
  "data": [
    {
      "object": "mf_purchase_plan",
      "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "active",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "installment_day": 1,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "requested_activation_date": null,
      "auto_generate_instalments": true,
      "number_of_installments": 7,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "payment_method": null,
      "payment_source": null,
      "purpose": "children_education",
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null
    },
    {
      "object": "mf_purchase_plan",
      "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "active",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "installment_day": 1,
      "start_date": "2022-01-01",
      "end_date": "2022-07-01",
      "requested_activation_date": null,
      "auto_generate_instalments": true,
      "number_of_installments": 7,
      "next_installment_date": "2022-04-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "payment_method": null,
      "payment_source": null,
      "purpose": "children_education",
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": 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.
    states no string-array Multiple plan states separated by comma.

    Cancel a purchase plan

    POST /v2/mf_purchase_plans/:id/cancel

    This API can be used to cancel a plan. For more details, please see here

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

    JSON Response:

    {
  "object": "mf_purchase_plan",
  "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "systematic": true,
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "auto_generate_instalments": true,
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "requested_activation_date": null,
  "number_of_installments": 7,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "payment_method": null,
  "payment_source": null,
  "purpose": "children_education",
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_at": null,
  "reason": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app"
}

    Mark a purchase plan as complete

    POST /v2/mf_purchase_plans/:id/complete

    This API can be used to mark a plan as completed. For more details, please see here

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

    JSON Response:

    {
  "object": "mf_purchase_plan",
  "id": "mfpp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "completed",
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "systematic": true,
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "auto_generate_instalments": true,
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "requested_activation_date": null,
  "number_of_installments": 7,
  "next_installment_date": null,
  "previous_installment_date": "2022-10-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "payment_method": null,
  "payment_source": null,
  "purpose": "children_education",
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "cancelled_at": null,
  "completed_at": "2022-11-01T19:51:21+05:30",
  "failed_at": null,
  "cancellation_scheduled_at": null,
  "reason": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": "investor",
  "initiated_via": "mobile_app"
}

    MF Redemption Plans(Early Access)

    MF Redemption plan represents a plan defined to create redemption orders on a recurring basis.

    Endpoints

    POST /v2/mf_redemption_plans
    PATCH /v2/mf_redemption_plans
    GET /v2/mf_redemption_plans/:id
    GET /v2/mf_redemption_plans
    POST /v2/mf_redemption_plans/:id/cancel
    POST /v2/mf_redemption_plans/:id/complete
    POST /v2/mf_redemption_plans/:id/skip_instructions
    GET /v2/mf_redemption_plans/skip_instructions/:id
    POST /v2/mf_redemption_plans/skip_instructions/:id/cancel
    GET /v2/mf_redemption_plans/:id/skip_instructions

    Redemption Plan Object Structure

    {
  "object": "mf_redemption_plan",
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "number_of_installments": 7,
  "auto_generate_installments": true,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "requested_activation_date": null,
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_on": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd": "91",
    "mobile": "9008580644"
  }
}
    Attribute Data type Can be null? Remarks
    object string No Will always be mf_redemption_plan
    id string No Unique identifier of the mf_redemption_plan object
    mf_investment_account string No 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 Yes Indicates the folio from which the redemptions must be made.
    scheme string No ISIN of the scheme from which units must be sold.
    amount decimal No Periodic redemption amount
    systematic boolean No The value of this attribute indicates the way this redemption plan is registered with order gateways. If the true, it means that the plan is registered as a Systematic Withdrawal Plan with RTA/BSE and every installment is considered as a traditional swp installment. However, if the value is false, it means that FP will create redemption orders according to the defined schedule and send the installments as normal redemption orders to order gateways.
    frequency string No See details here
    installment_day integer Yes See details here
    requested_activation_date date Yes See details here
    number_of_installments integer No See details here
    start_date date Yes See details here
    end_date date Yes See details here
    next_installment_date date Yes See details here
    previous_installment_date date Yes See details here
    remaining_installments Yes integer See details here
    state string No See details here
    auto_generate_installments boolean No See details here
    source_ref_id string Yes See details here
    partner string No See details here
    gateway string No See details here
    euin string Yes See details here
    user_ip string Yes See details here
    server_ip string Yes See details here
    initiated_by string Yes See details here
    initiated_via string Yes See details here
    created_at timestamp No See details here
    activated_at timestamp Yes See details here
    cancelled_at timestamp Yes See details here
    cancellation_scheduled_on date Yes See details here
    failed_at timestamp Yes See details here
    completed_at timestamp Yes See details here
    reason string Yes See details here
    consent object No Consent from investor for confirming the redemption

    As per SEBI regulations, investor consent must be obtained by sending a One-Time Password to the investor at his/her email/phone number registered against the folio before the redemption order can be sent to rtas.

    Name Mandatory Type Comments
    email conditional string Mandatory if consent is obtained via email. The value must be one of the email addresses registered against the folio.
    isd conditional string Supported value - 91
    mobile conditional string Mandatory if consent is obtained via mobile. The value must be one of the mobile numbers registered against the folio.

    Create a redemption plan

    POST /v2/mf_redemption_plans

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

    JSON Request:

    {
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "amount": 1000.0,
  "scheme": "INF204KA1B64",
  "frequency": "monthly",
  "installment_day": 1,
  "number_of_installments": 7,
  "generate_first_installment_now": true,
  "auto_generate_installments": true,
  "activate_after": null,
  "initiated_by": null,
  "initiated_via": null,
  "user_ip": null,
  "server_ip": null,
  "source_ref_d": null,
  "euin": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  }
}

    JSON Response:

    {
  "object": "mf_redemption_plan",
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "number_of_installments": 7,
  "auto_generate_installments": true,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "requested_activation_date": null,
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_on": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd": "91",
    "mobile": "9008580644"
  }
}

    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 redemptions must be made.
    frequency Yes string See details here. Please note that the frequencies weekly, fortnightly, and half_yearly are not supported when order gateway is bse and systematic=true
    folio_number Yes string Folio from which the redemptions must be made
    amount Yes decimal The installment amount.
    1) If systematic = true, amount should be in multiples of swp_multiples and between min_swp_amount and max_swp_amount
    2) If systematic = false and folio number is not provided,the amount should be between min_swp_amount and max_swp_amount and should be a multiple of swp_multiples
    3) If systematic = false, the amount should be between min_withdrawal_amount and max_withdrawal_amount and should be a multiple of withdrawal_multiples
    installment_day No integer See details here
    number_of_installments No integer See details here
    systematic Yes string If true, the plan is registered as an SWP. Else, normal redemption orders are generated as installments.
    generate_first_installment_now No boolean The value is false by default. This option is not available if you have opted to generate installments by yourself OR if you have opted for delayed activation of the plan.
    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 systematic=true, this value must be false. By default, the value is true
    activate_after No string A date in the 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.
    initiated_by No string See details here
    initiated_via No string See details here
    euin No string See details here
    user_ip No string See details here
    server_ip No string See details here
    source_ref_id No string See details here
    consent yes hash Consent from investor for confirming the redemption

    Update a redemption plan

    PATCH /v2/mf_redemption_plans

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

    JSON Request:

    {
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "cancellation_scheduled_on": "2022-05-09"
}

    JSON Response:

    {
  "object": "mf_redemption_plan",
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "number_of_installments": 7,
  "auto_generate_installments": true,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2021-04-01T17:51:21+05:30",
  "activated_at": "2021-04-01T17:51:21+05:30",
  "requested_activation_date": null,
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_on": "2022-05-09",
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd": "91",
    "mobile": "9008580644"
  }
}

    Request Parameters

    Name Mandatory Type Comments
    id Yes string Plan id
    amount No decimal Allowed only if systematic=false
    scheme No string Allowed only if systematic=false
    folio_number No string Allowed only if systematic=false
    euin No string See details here
    cancellation_scheduled_on No date See details here

    Fetch a redemption plan by its id

    GET /v2/mf_redemption_plans/:id

    This API can be used to fetch a redemption plan by its id.

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

    JSON Response:

    {
  "object": "mf_redemption_plan",
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "number_of_installments": 7,
  "auto_generate_installments": true,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "requested_activation_date": null,
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_on": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd": "91",
    "mobile": "9008580644"
  }
}

    List all redemption plans

    GET /v2/mf_redemption_plans

    This API is used to fetch all redemption plans.

    curl -X GET "https://s.finprim.com/v2/mf_redemption_plans?mf_investment_account=mfia_798fa03aba614840b983609e89ed16f2&states=active"
  -H "Authorization: Bearer ACCESS_TOKEN"

    JSON Response:

    {
  "object": "list",
  "data": [
    {
      "object": "mf_redemption_plan",
      "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "active",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "installment_day": 1,
      "auto_generate_installments": true,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "requested_activation_date": null,
      "number_of_installments": 7,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd": "91",
        "mobile": "9008580644"
      }
    },
    {
      "object": "mf_redemption_plan",
      "id": "mfrp_1ba5b25b534c48329dbfbeff70c846f0",
      "state": "active",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "5234567890",
      "frequency": "monthly",
      "scheme": "INF204KA1B64",
      "transaction_day": 1,
      "auto_generate_installments": true,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "requested_activation_date": null,
      "number_of_installments": 7,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd": "91",
        "mobile": "9008580644"
      }
    }
  ]
}

    Query Parameters

    Name Mandatory Type Comments
    mf_investment_account no string The investment account against which the redemption plans are created.
    states no string-array Multiple plan states separated by comma.

    Cancel a redemption plan

    POST /v2/mf_redemption_plans/:id/cancel

    This API can be used to cancel a plan. For more details, please see here

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

    JSON Response:

    {
  "object": "mf_redemption_plan",
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "cancelled",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "number_of_installments": 7,
  "auto_generate_installments": true,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "requested_activation_date": null,
  "cancelled_at": "2022-05-08T17:51:21+05:30",
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_on": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd": "91",
    "mobile": "9008580644"
  }
}

    Mark a redemption plan as complete

    POST /v2/mf_redemption_plans/:id/complete

    This API can be used to mark a plan as completed. For more details, please see here

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

    JSON Response:

    {
  "object": "mf_redemption_plan",
  "id": "mfrp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "completed",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "scheme": "INF204KA1B64",
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "number_of_installments": 7,
  "auto_generate_installments": true,
  "next_installment_date": null,
  "previous_installment_date": "2022-10-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "requested_activation_date": null,
  "cancelled_at": null,
  "completed_at": "2022-11-01T17:51:21+05:30",
  "failed_at": null,
  "cancellation_scheduled_on": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd": "91",
    "mobile": "9008580644"
  }
}

    MF Switch Plans(Early Access)

    MF Switch plan represents a plan defined to create switch orders on a recurring basis.

    Endpoints

    POST /v2/mf_switch_plans
    PATCH /v2/mf_switch_plans
    GET /v2/mf_switch_plans/:id
    GET /v2/mf_switch_plans
    POST /v2/mf_switch_plans/:id/cancel
    POST /v2/mf_switch_plans/:id/complete
    POST /v2/mf_switch_plans/:id/skip_instructions
    GET /v2/mf_switch_plans/skip_instructions/:id
    POST /v2/mf_switch_plans/skip_instructions/:id/cancel
    GET /v2/mf_switch_plans/:id/skip_instructions

    Switch Plan Object Structure

    {
  "object": "mf_switch_plan",
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "number_of_installments": 7,
  "auto_generate_installments": true,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "requested_activation_date": null,
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_on": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd": "91",
    "mobile": "9008580644"
  }
}
    Attribute Data type Can be null? Remarks
    object string No Will always be mf_switch_plan
    id string No Unique identifier of the mf_switch_plan object
    mf_investment_account string No 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 Yes Indicates the folio from which the switches must be made.
    switch_out_scheme string No ISIN of the scheme from which units must be switched out.
    switch_in_scheme string No ISIN of the scheme to which units must be switched to.
    amount decimal No Periodic switch amount.
    systematic boolean No The value of this attribute indicates the way this switch plan is registered with order gateways. If the true, it means that the plan is registered as a Systematic Transfer Plan with RTA/BSE and every installment is considered as a traditional stp installment. However, if the value is false, it means that FP will create switch orders according to the defined schedule and send the installments as normal switch orders to order gateways.
    frequency string No See details here
    installment_day integer Yes See details here
    requested_activation_date date Yes See details here
    number_of_installments integer No See details here
    start_date date Yes See details here
    end_date date Yes See details here
    next_installment_date date Yes See details here
    previous_installment_date date Yes See details here
    remaining_installments Yes integer See details here
    state string No See details here
    auto_generate_installments boolean No See details here
    source_ref_id string Yes See details here
    partner string No See details here
    gateway string No See details here
    euin string Yes See details here
    user_ip string Yes See details here
    server_ip string Yes See details here
    initiated_by string Yes See details here
    initiated_via string Yes See details here
    created_at timestamp No See details here
    activated_at timestamp Yes See details here
    cancelled_at timestamp Yes See details here
    cancellation_scheduled_on date Yes See details here
    failed_at timestamp Yes See details here
    completed_at timestamp Yes See details here
    reason string Yes See details here
    consent object No Consent from investor for confirming the switch

    As per SEBI regulations, investor consent must be obtained by sending a One-Time Password to the investor at his/her email/phone number registered against the folio before the switch order can be sent to rtas.

    Name Mandatory Type Comments
    email conditional string Mandatory if consent is obtained via email. The value must be one of the email addresses registered against the folio.
    isd conditional string Supported value - 91
    mobile conditional string Mandatory if consent is obtained via mobile. The value must be one of the mobile numbers registered against the folio.

    Create a switch plan

    POST /v2/mf_switch_plans

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

    JSON Request:

    {
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "amount": 1000.0,
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "frequency": "monthly",
  "installment_day": 1,
  "number_of_installments": 7,
  "generate_first_installment_now": true,
  "auto_generate_installments": true,
  "activate_after": null,
  "initiated_by": null,
  "initiated_via": null,
  "user_ip": null,
  "server_ip": null,
  "source_ref_d": null,
  "euin": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  }
}

    JSON Response:

    {
  "object": "mf_switch_plan",
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "number_of_installments": 7,
  "auto_generate_installments": true,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "requested_activation_date": null,
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_on": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd": "91",
    "mobile": "9008580644"
  }
}

    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.
    switch_out_scheme Yes string The isin of the scheme from which switches must be made.
    switch_in_scheme Yes string The isin of the scheme to which switches must be made.
    frequency Yes string See details here. Please note that the frequencies weekly, fortnightly, and half_yearly are not supported when order gateway is bse and systematic=true
    folio_number Yes string Folio from which the switches must be made
    amount Yes decimal The installment amount.
    1) If systematic = true, amount should be in multiples of stp_multiples and between min_stp_amount and max_stp_amount
    2) If systematic = false and folio number is not provided,the amount should be between min_stp_amount and max_stp_amount and should be a multiple of stp_multiples
    3) If systematic = false, the amount should be between min_switch_out_amount and max_switch_out_amount and should be a multiple of switch_out_amount_multiples
    installment_day No integer See details here
    number_of_installments No integer See details here
    systematic Yes string If true, the plan is registered as an SWP. Else, normal switch orders are generated as installments.
    generate_first_installment_now No boolean The value is false by default. This option is not available if you have opted to generate installments by yourself OR if you have opted for delayed activation of the plan.
    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 systematic=true, this value must be false. By default, the value is true
    activate_after No string A date in the 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.
    initiated_by No string See details here
    initiated_via No string See details here
    euin No string See details here
    user_ip No string See details here
    server_ip No string See details here
    source_ref_id No string See details here
    consent yes hash Consent from investor for confirming the redemption

    Update a switch plan

    PATCH /v2/mf_switch_plans

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

    JSON Request:

    {
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "cancellation_scheduled_on": "2022-05-09"
}

    JSON Response:

    {
  "object": "mf_switch_plan",
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "number_of_installments": 7,
  "auto_generate_installments": true,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2021-04-01T17:51:21+05:30",
  "activated_at": "2021-04-01T17:51:21+05:30",
  "requested_activation_date": null,
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_on": "2022-05-09",
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd": "91",
    "mobile": "9008580644"
  }
}

    Request Parameters

    Name Mandatory Type Comments
    id Yes string Plan id
    amount No decimal Allowed only if systematic=false
    scheme_out_scheme No string Allowed only if systematic=false
    scheme_in_scheme No string Allowed only if systematic=false
    folio_number No string Allowed only if systematic=false
    euin No string See details here
    cancellation_scheduled_on No date See details here

    Fetch a switch plan by its id

    GET /v2/mf_switch_plans/:id

    This API can be used to fetch a switch plan by its id.

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

    JSON Response:

    {
  "object": "mf_switch_plan",
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "active",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "number_of_installments": 7,
  "auto_generate_installments": true,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "requested_activation_date": null,
  "cancelled_at": null,
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_on": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd": "91",
    "mobile": "9008580644"
  }
}

    List all switch plans

    GET /v2/mf_switch_plans

    This API is used to fetch all switch plans.

    curl -X GET "https://s.finprim.com/v2/mf_switch_plans?mf_investment_account=mfia_798fa03aba614840b983609e89ed16f2&states=active"
  -H "Authorization: Bearer ACCESS_TOKEN"

    JSON Response:

    {
  "object": "list",
  "data": [
    {
      "object": "mf_switch_plan",
      "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
      "state": "active",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "1234567890",
      "frequency": "monthly",
      "switch_in_scheme": "INF204KA1B64",
      "switch_out_scheme": "INF205KA1B65",
      "installment_day": 1,
      "auto_generate_installments": true,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "requested_activation_date": null,
      "number_of_installments": 7,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd": "91",
        "mobile": "9008580644"
      }
    },
    {
      "object": "mf_switch_plan",
      "id": "mfsp_1ba5b25b534c48329dbfbeff70c846f0",
      "state": "active",
      "systematic": true,
      "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
      "folio_number": "5234567890",
      "frequency": "monthly",
      "switch_in_scheme": "INF204KA1B64",
      "switch_out_scheme": "INF208KA1B68",
      "transaction_day": 1,
      "auto_generate_installments": true,
      "start_date": "2022-04-01",
      "end_date": "2022-11-01",
      "requested_activation_date": null,
      "number_of_installments": 7,
      "next_installment_date": "2022-06-01",
      "previous_installment_date": "2022-05-01",
      "remaining_installments": 6,
      "amount": 1000.0,
      "source_ref_id": null,
      "euin": null,
      "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
      "created_at": "2022-04-01T17:51:21+05:30",
      "activated_at": "2022-04-01T17:51:21+05:30",
      "cancelled_at": null,
      "completed_at": null,
      "failed_at": null,
      "cancellation_scheduled_on": null,
      "gateway": "rta",
      "user_ip": null,
      "server_ip": null,
      "initiated_by": null,
      "initiated_via": null,
      "consent": {
        "email": "mfp@cybrilla.com",
        "isd": "91",
        "mobile": "9008580644"
      }
    }
  ]
}

    Query Parameters

    Name Mandatory Type Comments
    mf_investment_account no string The investment account against which the switch plans are created.
    states no string-array Multiple plan states separated by comma.

    Cancel a switch plan

    POST /v2/mf_switch_plans/:id/cancel

    This API can be used to cancel a plan. For more details, please see here

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

    JSON Response:

    {
  "object": "mf_switch_plan",
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "cancelled",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "number_of_installments": 7,
  "auto_generate_installments": true,
  "next_installment_date": "2022-06-01",
  "previous_installment_date": "2022-05-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "requested_activation_date": null,
  "cancelled_at": "2022-05-08T17:51:21+05:30",
  "completed_at": null,
  "failed_at": null,
  "cancellation_scheduled_on": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd": "91",
    "mobile": "9008580644"
  }
}

    Mark a switch plan as complete

    POST /v2/mf_switch_plans/:id/complete

    This API can be used to mark a plan as completed. For more details, please see here

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

    JSON Response:

    {
  "object": "mf_switch_plan",
  "id": "mfsp_dbabb25ba34c48329dbfbeff70c846f0",
  "state": "completed",
  "systematic": true,
  "mf_investment_account": "mfia_798fa03aba614840b983609e89ed16f2",
  "folio_number": "1234567890",
  "frequency": "monthly",
  "switch_in_scheme": "INF204KA1B64",
  "switch_out_scheme": "INF205KA1B65",
  "installment_day": 1,
  "start_date": "2022-04-01",
  "end_date": "2022-11-01",
  "number_of_installments": 7,
  "auto_generate_installments": true,
  "next_installment_date": null,
  "previous_installment_date": "2022-10-01",
  "remaining_installments": 6,
  "amount": 1000.0,
  "source_ref_id": null,
  "euin": null,
  "partner": "ptnr_b581dddcda27446dbd0cbfc2a7672557",
  "created_at": "2022-04-01T17:51:21+05:30",
  "activated_at": "2022-04-01T17:51:21+05:30",
  "requested_activation_date": null,
  "cancelled_at": null,
  "completed_at": "2022-11-01T17:51:21+05:30",
  "failed_at": null,
  "cancellation_scheduled_on": null,
  "gateway": "rta",
  "user_ip": null,
  "server_ip": null,
  "initiated_by": null,
  "initiated_via": null,
  "reason": null,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd": "91",
    "mobile": "9008580644"
  }
}

    MF Redemption Plans(Deprecated)

    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,
  "consent": {
    "email": "mfp@cybrilla.com",
    "isd_code": "91",
    "mobile": "9008580644"
  }
}

    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.
    consent yes hash Consent from investor for confirming the redemption

    As per SEBI regulations, investor consent must be obtained by sending a One-Time Password to the investor at his/her email/phone number registered against the folio before the redeption order can be sent to rtas.

    Name Mandatory Type Comments
    email conditional string Mandatory if consent is obtained via email.
    The value must be one of the email addresses registered against the folio.
    isd conditional string Supported value
    - 91
    mobile conditional string Mandatory if consent is obtained via mobile.
    The value must be one of the mobile numbers registered against the folio.

    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.

    Mandates

    Represents an authorization given by the investor to automatically debit payment from his bank account for onetime and recurring purchase orders.

    Endpoints:

    POST /api/pg/mandates
    POST /api/pg/payments/emandate/auth
    GET /api/pg/mandates/:id
    GET /api/pg/mandates
    POST /api/pg/mandates/:id/cancel

    Create a mandate (eNACH)

    curl -X POST "https://s.finprim.com/api/pg/mandates"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '
    {
  "mandate_type": "E_MANDATE",
  "bank_account_id": 1,
  "mandate_limit": 100000
}
  '

    JSON Response:

    {
  "id": 1
}

    POST /api/pg/mandates

    This endpoint is used to create e-mandate. The API returns mandate ID in response.

    Parameters

    Parameter Mandatory Type Description
    mandate_type yes String Possible values:
    E_MANDATE,
    UPI (UPI Autopay feature is only available if provider is Razorpay. Please note that this feature is an experimental feature and currently not available on production or sandbox)
    bank_account_id yes Long bank account ID generated while creating the investor. This is not the bank id or the bank account number. Please check the GET investor details API to fetch the bank account ID
    mandate_limit yes Integer mandate limit
    (For UPI autopay max mandate limit is 5000 INR)
    provider_name no String RAZORPAY (or) BSE
    valid_from no String valid From in yyyy-MM-dd format
    valid_to no String valid to in yyyy-MM-dd format. Only for BSE as gateway provider.

    Authorize a mandate (eNACH)

    curl "https://s.finprim.com/api/pg/payments/emandate/auth"
  -H "Authorization: Bearer ACCESS_TOKEN"
  -d '
    {
  "mandate_id": 1,
  "payment_postback_url": "https://example.com/"
}
  '

    JSON Response:

    {
  "token_url": "https://tenant.s.finprim.com/api/pg/payments/netbanking/razorpay?txnId=bdbd1396-3197-460b-afd3-adc3f6e09123&txnType=1",
  "id": 1
}

    POST /api/pg/payments/emandate/auth

    This endpoint is used for authorizing the e-mandate. Once the authorization is done from the bank side, subsequent payments need not be authorized again and will be made automatically. The response contains payment gateway URL along with payment ID.

    Parameters

    Parameter Mandatory Type Description
    mandate_id yes Integer ID of created e-mandate
    payment_postback_url no String Application url where the investor will be redirected back after emandate auth transaction (https://example.com/payment_confirmation). Not Supported with BSE as gateway provider.

    After e-mandate is authorized at the payment gateway, a post request using HTTP POST will be made via web browser to the preconfigured URL provided by tenant

    HTTP Form POST Parameters

    Parameter Type Description
    paymentId String ID of the generated payment
    status String payment status either success or failure
    failureReason String payment failure reason, empty if payment is successful

    You can use this data for displaying the authorization status to the investor and if required retry.

    Fetch a mandate

    curl "https://s.finprim.com/api/pg/mandates/1"
  -H "Authorization: Bearer ACCESS_TOKEN"

    JSON Response:

    {
  "id": 1,
  "bank_account_id": 1,
  "mandate_ref": null,
  "mandate_token": "token_WxyDNskmds",
  "valid_from": "2017-10-23",
  "mandate_limit": 50000,
  "mandate_type": "NACH",
  "mandate_status": "SUBMITTED",
  "umrn": null,
  "created_at": "2017-10-23T04:49:21+05:30",
  "received_at": null,
  "submitted_at": "2017-10-23T04:30:21+05:30",
  "cancelled_at": null,
  "approved_at": null,
  "rejected_at": null,
  "rejected_reason": null,
  "provider_id": 1
}

    GET /api/pg/mandates/:id

    This endpoint retrieves mandate info based on the mandate ID

    Note

    List all mandates

    curl "https://s.finprim.com/api/pg/mandates?bank_account_id=18,12"
  -H "Authorization: Bearer ACCESS_TOKEN"

    JSON Response:

    {
  "last": true,
  "total_pages": 1,
  "total_elements": 2,
  "size": 20,
  "number": 0,
  "first": true,
  "number_of_elements": 2,
  "mandates": [
    {
      "id": 2,
      "bank_account_id": 1,
      "mandate_ref": "391335121",
      "mandate_token": "token_WxyDNskmds",
      "valid_from": "2017-10-23",
      "mandate_limit": 50000,
      "mandate_type": "NACH",
      "mandate_status": "CREATED",
      "umrn": "1592",
      "created_at": "2017-10-23T04:51:27+05:30",
      "received_at": null,
      "submitted_at": null,
      "approved_at": null,
      "cancelled_at": null,
      "rejected_at": null,
      "rejected_reason": null,
      "provider_id": 1
    },
    {
      "id": 3,
      "bank_account_id": 1,
      "mandate_ref": "391115121",
      "mandate_token": "token_YnhDsFgos",
      "valid_from": "2017-11-24",
      "mandate_limit": 50000,
      "mandate_type": "NACH",
      "mandate_status": "CREATED",
      "umrn": "1512",
      "created_at": "2017-11-24T04:51:27+05:30",
      "received_at": null,
      "submitted_at": null,
      "approved_at": null,