> ## Documentation Index
> Fetch the complete documentation index at: https://developer.moneyone.in/llms.txt
> Use this file to discover all available pages before exploring further.
# Consent Request V4
> Create consent requests with individual consent handles per FIP for granular tracking and management of multi-FIP consent scenarios.
## Overview
The Consent Request V4 API represents the most advanced consent initiation capability in the FinPro platform. Unlike V2 and V3 which return a single consent handle, V4 creates separate consent handles for each Financial Information Provider (FIP) specified in the request.
This granular approach provides several advantages for complex consent scenarios:
* **Independent Tracking**: Each FIP gets its own consent handle, allowing you to track approval, rejection, or revocation independently per financial institution.
* **Partial Success Handling**: If consent is approved for some FIPs but rejected for others, you can identify exactly which institutions the customer authorized.
* **Selective Data Fetching**: Request financial information from specific FIPs based on which consents were approved, rather than an all-or-nothing approach.
* **Better Error Handling**: If one FIP fails during the consent process, other FIP consents remain unaffected and can proceed normally.
This API is ideal for scenarios where you need fine-grained control over multi-FIP consent journeys, such as comprehensive credit underwriting that requires data from multiple banks, or wealth management applications that aggregate accounts across numerous financial institutions.
## Endpoint
```bash Request theme={null}
POST {{Base_URL}}/v4/requestconsent
```
## Authentication
This API requires authentication through the following headers that must be included in every request:
| Header | Type | Required | Description |
| ---------------- | ------ | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `client_id` | string | Yes | Your unique client identifier provided by MoneyOne during FIU onboarding. This credential identifies your organization in the FinPro system. |
| `client_secret` | string | Yes | Your confidential client secret provided by MoneyOne. This must be kept secure and never exposed in client-side code or public repositories. |
| `organisationId` | string | Yes | Your organization's unique identifier in the FinPro system. This is assigned during onboarding and links all API calls to your FIU entity. |
| `appIdentifier` | string | Yes | Application-specific identifier that helps track which application or service within your organization is making the API call. Useful for multi-application FIU setups. |
## Request Body
The request body must be a JSON object containing the following parameters:
| Parameter | Type | Required | Description |
| ---------------------- | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `productID` | string | Yes | The unique identifier of the consent template configured in the FinPro admin portal. This template defines the purpose code, consent validity, FI types, fetch frequency, and other consent parameters that will govern the data sharing relationship. |
| `vua` | string | Yes | The customer's Virtual User Address (VUA) in the format `mobile@onemoney`. This is the unique identifier used by Account Aggregators to identify the customer across the AA ecosystem. |
| `partyIdentifierType` | string | Yes | The type of identifier being provided for the customer. Valid values are `MOBILE`, `EMAIL`, or `PAN`. This should match the format of the `partyIdentifierValue` field. |
| `partyIdentifierValue` | string | Yes | The actual identifier value for the customer. For `MOBILE` type, this should be a 10-digit Indian mobile number without country code. For `EMAIL`, provide the email address. For `PAN`, provide the 10-character PAN number. |
| `accountID` | string | Yes | A unique identifier from your system that links this consent request to a specific customer interaction, loan application, or transaction in your backend. This helps you correlate consent lifecycle events with your internal workflows. Use alphanumeric values to ensure compatibility. |
| `pan` | string | No | The customer's Permanent Account Number (PAN). Required for certain consent types and helps in identity verification across the AA ecosystem. Must be a valid 10-character Indian PAN format. |
| `fipID` | array of strings | No | An array of Financial Information Provider identifiers for which separate consent handles will be created. Each FIP in this array will get its own consent handle in the response. If not provided, the customer can discover and link accounts from all available FIPs, but will receive a single consent handle (similar to V3 behavior). |
| `redirectUrl` | string | No | The URL where the customer should be redirected after completing the consent journey in the AA interface. This should be a valid HTTPS URL that can handle the callback with consent status information. If not provided, the default redirect URL configured in your FinPro portal will be used. |
### Important Notes
* **FIP Specificity**: The real value of V4 comes from specifying multiple FIPs in the `fipID` array. Each FIP will receive its own consent handle, enabling independent tracking.
* **Success and Failure Lists**: The response includes both `successList` (FIPs for which consent handles were created successfully) and optionally a failure list (FIPs that encountered errors during handle creation).
* **Overall Status**: The top-level `status` field indicates whether the overall request was processed successfully. Individual FIP success/failure is tracked within the response data structure.
* **Party Identifier Validation**: The API performs strict validation on `partyIdentifierValue`. Mobile numbers must be exactly 10 digits, and any format violation will cause the entire request to fail.
## Response
### Success Response (200 OK)
When consent handles are successfully created for one or more FIPs, the API returns a detailed response with per-FIP consent handles:
```json Success Response theme={null}
{
"ver": "1.21.0",
"status": "success",
"data": {
"status": "PENDING",
"successList": {
"consent_handles": [
{
"consent_handle_id": "257cd126-3838-4597-a63c-f9438535ec47",
"fip_id": "ACME-FIP"
},
{
"consent_handle_id": "8f3a2c91-4d5e-4b2a-9c7d-1e6f5a8b9c2d",
"fip_id": "finsharebank"
}
]
}
}
}
```
| Field | Type | Description |
| ------------------------------------------------------ | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | string | Overall API call status. Will be `success` when the request was processed successfully. |
| `ver` | string | The version of the FinPro API that processed this request. Useful for debugging and version tracking. |
| `data.status` | string | The initial status of the consent requests. Will be `PENDING` when first created, indicating the customer has not yet approved or rejected the consents. |
| `data.successList` | object | Contains the list of successfully created consent handles organized by FIP. |
| `data.successList.consent_handles` | array | An array of objects, each containing a consent handle ID and its associated FIP ID. Each object represents a distinct consent that will be tracked independently. |
| `data.successList.consent_handles[].consent_handle_id` | string | A unique UUID that identifies the consent request for this specific FIP throughout its lifecycle. Store this value to track status changes per FIP. |
| `data.successList.consent_handles[].fip_id` | string | The Financial Information Provider identifier for which this consent handle was created. Matches one of the FIP IDs from your request. |
### Response with Partial Failures
In some scenarios, consent handles may be created successfully for some FIPs while others fail. The response structure accommodates this:
```json Partial Success Response theme={null}
{
"ver": "1.21.0",
"status": "success",
"data": {
"status": "PENDING",
"successList": {
"consent_handles": [
{
"consent_handle_id": "257cd126-3838-4597-a63c-f9438535ec47",
"fip_id": "ACME-FIP"
}
]
},
"failureList": {
"fip_errors": [
{
"fip_id": "invalid-fip",
"error": "FIP not found or not available"
}
]
}
}
}
```
### Error Response (400 Bad Request)
When the request contains invalid data or fails validation before processing FIPs, the API returns an error response:
```json Error Response theme={null}
{
"ver": "1.21.0",
"timestamp": "2025-10-01T11:42:55.836Z",
"errorCode": "InvalidRequest",
"errorMsg": " [ partyIdentifierValue must be valid Mobile number ] "
}
```
| Field | Type | Description |
| ----------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ver` | string | The version of the FinPro API that processed this request. |
| `timestamp` | string | ISO 8601 formatted timestamp indicating when the error occurred. This helps with debugging and correlating errors with logs. |
| `errorCode` | string | A human-readable error code indicating the category of error. Common values include `InvalidRequest`, `InvalidStatus`, `AuthenticationFailed`, etc. |
| `errorMsg` | string | A detailed error message explaining what went wrong. This provides specific information about which field or validation rule caused the failure. |
## Common Error Codes
| Error Code | Status Code | Description | Resolution |
| ------------------------ | ----------- | --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `InvalidRequest` | 400 | The request body contains invalid data or missing required fields. | Verify that all required fields are present and correctly formatted. Check that the `productID` exists in your portal configuration. |
| `InvalidProductID` | 400 | The specified `productID` does not exist or is not configured for your organization. | Log into the FinPro admin portal and verify that the product/consent template exists and is active. |
| `InvalidPartyIdentifier` | 400 | The `partyIdentifierValue` does not match the format expected by `partyIdentifierType`. | For MOBILE type, ensure the value is a 10-digit number without country code or special characters. For PAN, ensure it follows the standard format (5 letters, 4 digits, 1 letter). |
| `InvalidFIPID` | 400 | One or more FIP identifiers in the `fipID` array are not recognized or not available. | Verify the FIP IDs against the list of available FIPs in your FinPro portal. FIP IDs are case-sensitive and must match exactly. |
| `AuthenticationFailed` | 401 | The provided credentials (client\_id, client\_secret, organisationId) are invalid or expired. | Verify your credentials in the FinPro admin portal. Ensure you're using the correct credentials for the environment (UAT vs Production). |
## Example Request
```bash cURL theme={null}
curl --location '{{Base_URL}}/v4/requestconsent' \
--header 'client_id: {{Client_Id}}' \
--header 'client_secret: {{Client_Secret}}' \
--header 'organisationId: {{Organisation_Id}}' \
--header 'appIdentifier: {{App_Identifier}}' \
--header 'Content-Type: application/json' \
--data '{
"productID": "TESTWM01",
"vua": "9876543210@onemoney",
"partyIdentifierType": "MOBILE",
"partyIdentifierValue": "9876543210",
"accountID": "test123",
"pan": "ABCDE1234F",
"fipID": [
"ACME-FIP",
"finsharebank"
],
"redirectUrl": "https://yourapp.com/consent/callback"
}'
```
```javascript JavaScript theme={null}
const response = await fetch('{{Base_URL}}/v4/requestconsent', {
method: 'POST',
headers: {
'client_id': '{{Client_Id}}',
'client_secret': '{{Client_Secret}}',
'organisationId': '{{Organisation_Id}}',
'appIdentifier': '{{App_Identifier}}',
'Content-Type': 'application/json'
},
body: JSON.stringify({
productID: 'TESTWM01',
vua: '9876543210@onemoney',
partyIdentifierType: 'MOBILE',
partyIdentifierValue: '9876543210',
accountID: 'test123',
pan: 'ABCDE1234F',
fipID: ['ACME-FIP', 'finsharebank'],
redirectUrl: 'https://yourapp.com/consent/callback'
})
});
const data = await response.json();
// Store consent handles per FIP
data.data.successList.consent_handles.forEach(handle => {
console.log(`FIP: ${handle.fip_id}, Consent Handle: ${handle.consent_handle_id}`);
});
```
```python Python theme={null}
import requests
url = "{{Base_URL}}/v4/requestconsent"
headers = {
"client_id": "{{Client_Id}}",
"client_secret": "{{Client_Secret}}",
"organisationId": "{{Organisation_Id}}",
"appIdentifier": "{{App_Identifier}}",
"Content-Type": "application/json"
}
payload = {
"productID": "TESTWM01",
"vua": "9876543210@onemoney",
"partyIdentifierType": "MOBILE",
"partyIdentifierValue": "9876543210",
"accountID": "test123",
"pan": "ABCDE1234F",
"fipID": ["ACME-FIP", "finsharebank"],
"redirectUrl": "https://yourapp.com/consent/callback"
}
response = requests.post(url, json=payload, headers=headers)
data = response.json()
# Store consent handles per FIP
for handle in data['data']['successList']['consent_handles']:
print(f"FIP: {handle['fip_id']}, Consent Handle: {handle['consent_handle_id']}")
```
## Use Cases for V4
### Credit Underwriting with Multiple Banks
When evaluating a loan application, you may need bank statements from multiple institutions:
```javascript theme={null}
// Request consent for 3 major banks
const response = await createConsentV4({
productID: 'LOAN_UNDERWRITING',
vua: '9876543210@onemoney',
partyIdentifierType: 'MOBILE',
partyIdentifierValue: '9876543210',
accountID: `LOAN_${applicationId}`,
fipID: ['HDFC-FIP', 'ICICI-FIP', 'SBI-FIP']
});
// Store mapping of FIP to consent handle
const consentMap = {};
response.data.successList.consent_handles.forEach(handle => {
consentMap[handle.fip_id] = handle.consent_handle_id;
});
// Later, when webhooks arrive, you can identify which FIP's consent was approved
function handleConsentApproval(webhook) {
const fipId = getFIPIdFromConsentHandle(webhook.consentHandle, consentMap);
console.log(`Consent approved for ${fipId}`);
// Proceed to fetch data only from this FIP
}
```
### Wealth Management Account Aggregation
For comprehensive financial planning, aggregate accounts across multiple banks and investment platforms:
```python theme={null}
# Request consent for banks and investment platforms
fips = [
'HDFC-FIP', 'ICICI-FIP', 'SBI-FIP', # Banks
'ZERODHA-FIP', 'GROWW-FIP', # Investment platforms
'LICMF-FIP' # Mutual funds
]
response = create_consent_v4(
product_id='WEALTH_AGGREGATION',
vua=f'{customer_mobile}@onemoney',
party_identifier_type='MOBILE',
party_identifier_value=customer_mobile,
account_id=f'WEALTH_{customer_id}',
fip_id=fips
)
# Track each FIP separately
consent_tracking = {}
for handle in response['data']['successList']['consent_handles']:
consent_tracking[handle['fip_id']] = {
'consent_handle': handle['consent_handle_id'],
'status': 'PENDING',
'accounts_linked': []
}
```
## Next Steps
After successfully creating consent requests with V4:
1. **Store Consent Handle Mapping**: Create a mapping between FIP IDs and their corresponding consent handles in your database. This allows you to correlate webhook notifications and status updates back to specific FIPs.
2. **Track Per-FIP Status**: Implement logic to track consent status independently for each FIP. Some customers may approve certain banks quickly while taking longer for others.
3. **Configure Webhooks**: Ensure your webhook handlers can process notifications for each consent handle separately. You may receive approval for one FIP and rejection for another.
4. **Handle Partial Approvals**: Build business logic to proceed with data fetching from approved FIPs while gracefully handling rejections from others. Don't wait for all consents to be approved if your use case allows partial data.
5. **Request FI Data Selectively**: When requesting financial information, you can now target specific FIPs based on which consents were approved, optimizing data fetches and reducing API calls.
6. **Monitor Failure List**: If the response includes a `failureList`, log these errors and consider whether to retry with corrected FIP IDs or proceed with successful consents only.
## API Version Comparison
* **V2**: Returns a single consent handle with PENDING status. No web redirection URL. Basic consent creation.
* **V3**: Returns a `webRedirectionUrl` for automatic customer redirect. Single consent handle covers all FIPs. Good for simple multi-FIP scenarios.
* **V4 (this API)**: Returns separate consent handles per FIP for granular tracking. Enables independent lifecycle management per financial institution. Best for complex multi-FIP scenarios requiring fine-grained control.
Choose V4 when:
* You need to track consent status independently per FIP
* Your use case can proceed with partial consent approvals
* You want to optimize data fetching based on which FIPs were approved
* You require detailed error handling at the FIP level
* You're building comprehensive financial aggregation or underwriting systems
## OpenAPI
````yaml POST /v4/requestconsent
openapi: 3.0.3
info:
title: FinPro API
description: MoneyOne FinPro - Account Aggregator FIU Platform APIs
version: 1.21.0
servers:
- url: '{baseUrl}'
description: FinPro API Server
variables:
baseUrl:
default: https://scramblerpay-uat.moneyone.in
description: API Base URL - change this to your environment
security:
- clientId: []
clientSecret: []
organisationId: []
appIdentifier: []
paths:
/v4/requestconsent:
post:
tags:
- Consent Management
summary: Create Consent Request V4
description: >-
Create consent requests with individual consent handles per FIP for
granular tracking and management of multi-FIP consent scenarios. Unlike
V2 and V3 which return a single consent handle, V4 creates separate
consent handles for each Financial Information Provider (FIP) specified
in the request.
operationId: requestConsentV4
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConsentRequestV4'
example:
productID: TESTWM01
vua: 9876543210@onemoney
partyIdentifierType: MOBILE
partyIdentifierValue: '9876543210'
accountID: test123
pan: ABCDE1234F
fipID:
- ACME-FIP
- finsharebank
redirectUrl: https://yourapp.com/consent/callback
responses:
'200':
description: Consent request created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ConsentResponseV4Success'
example:
ver: 1.21.0
status: success
data:
status: PENDING
successList:
consent_handles:
- consent_handle_id: 257cd126-3838-4597-a63c-f9438535ec47
fip_id: ACME-FIP
- consent_handle_id: 8f3a2c91-4d5e-4b2a-9c7d-1e6f5a8b9c2d
fip_id: finsharebank
'400':
description: Bad Request - Invalid data or validation failure
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
ver: 1.21.0
timestamp: '2025-10-01T11:42:55.836Z'
errorCode: InvalidRequest
errorMsg: ' [ partyIdentifierValue must be valid Mobile number ] '
'401':
description: Authentication Failed - Invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- clientId: []
clientSecret: []
organisationId: []
appIdentifier: []
components:
schemas:
ConsentRequestV4:
type: object
required:
- productID
- vua
- partyIdentifierType
- partyIdentifierValue
- accountID
properties:
productID:
type: string
description: >-
The unique identifier of the consent template configured in the
FinPro admin portal. This template defines the purpose code, consent
validity, FI types, fetch frequency, and other consent parameters.
vua:
type: string
description: >-
The customer's Virtual User Address (VUA) in format mobile@onemoney.
This is the unique identifier used by Account Aggregators to
identify the customer.
partyIdentifierType:
type: string
enum:
- MOBILE
- EMAIL
- PAN
description: >-
The type of identifier being provided for the customer. Must match
the format of partyIdentifierValue.
partyIdentifierValue:
type: string
description: >-
The actual identifier value. For MOBILE: 10-digit Indian mobile
number without country code. For EMAIL: email address. For PAN:
10-character PAN number.
accountID:
type: string
description: >-
A unique identifier from your system that links this consent request
to a specific customer interaction, loan application, or
transaction.
pan:
type: string
description: >-
The customer's Permanent Account Number (PAN). Required for certain
consent types. Must be a valid 10-character Indian PAN format.
fipID:
type: array
items:
type: string
description: >-
An array of Financial Information Provider identifiers for which
separate consent handles will be created. Each FIP will get its own
consent handle in the response.
redirectUrl:
type: string
format: uri
description: >-
The URL where the customer should be redirected after completing the
consent journey. Must be a valid HTTPS URL.
ConsentResponseV4Success:
type: object
properties:
ver:
type: string
description: The version of the FinPro API that processed this request.
status:
type: string
description: >-
Overall API call status. Will be 'success' when the request was
processed successfully.
data:
type: object
properties:
status:
type: string
description: >-
The initial status of the consent requests. Will be 'PENDING'
when first created.
successList:
type: object
description: >-
Contains the list of successfully created consent handles
organized by FIP.
properties:
consent_handles:
type: array
description: >-
An array of objects, each containing a consent handle ID and
its associated FIP ID.
items:
$ref: '#/components/schemas/ConsentHandleV4'
failureList:
type: object
description: >-
Contains the list of FIPs for which consent handle creation
failed.
properties:
fip_errors:
type: array
description: >-
An array of FIP error objects indicating which FIPs failed
and why.
items:
$ref: '#/components/schemas/FipErrorV4'
ErrorResponse:
type: object
properties:
ver:
type: string
description: API version
timestamp:
type: string
format: date-time
description: When the error occurred
errorCode:
type: string
description: Error category code
errorMsg:
type: string
description: Detailed error message
status:
type: string
description: FinPro-specific error code (FPxxxx format)
ConsentHandleV4:
type: object
properties:
consent_handle_id:
type: string
format: uuid
description: >-
A unique UUID that identifies the consent request for this specific
FIP throughout its lifecycle.
fip_id:
type: string
description: >-
The Financial Information Provider identifier for which this consent
handle was created.
FipErrorV4:
type: object
properties:
fip_id:
type: string
description: >-
The Financial Information Provider identifier that encountered an
error.
error:
type: string
description: >-
Error message describing why consent handle creation failed for this
FIP.
securitySchemes:
clientId:
type: apiKey
in: header
name: client_id
description: Your unique client identifier provided by MoneyOne during FIU onboarding
clientSecret:
type: apiKey
in: header
name: client_secret
description: Your confidential client secret provided by MoneyOne
organisationId:
type: apiKey
in: header
name: organisationId
description: Your organization's unique identifier in the FinPro system
appIdentifier:
type: apiKey
in: header
name: appIdentifier
description: Application-specific identifier for tracking API calls
````