> ## 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 V2
> Create a new consent request to initiate the Account Aggregator flow for customer data sharing authorization.
**Legacy API** — This is Consent Request V2. We recommend using [V3](/api-reference/consent/request-v3) for new integrations.
## Overview
The Consent Request V2 API initiates a consent journey by creating a new consent request based on a pre-configured consent template. This API generates a consent handle that uniquely identifies the consent request and allows the FIU to track its lifecycle through subsequent status checks and webhook notifications.
This is the foundational version of the consent request API that returns a consent handle without web redirection capabilities. Use this API when you plan to redirect customers through a separate mechanism or when you need just the consent handle for tracking purposes.
## Endpoint
```bash Request theme={null}
POST {{Base_URL}}/v2/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. |
### Important Notes
* **VUA Format**: The VUA must follow the exact format `identifier@onemoney` where the identifier matches the party identifier value. The domain `@onemoney` is case-sensitive and required.
* **Party Identifier Validation**: The API validates that the `partyIdentifierType` and `partyIdentifierValue` match the expected format. Mobile numbers must be exactly 10 digits, and PAN must follow the standard Indian PAN format.
* **Product ID Configuration**: The `productID` must exist in your FinPro portal configuration before making this API call. Requests with invalid or non-existent product IDs will be rejected.
* **Account ID Uniqueness**: While not enforced by the API, it's recommended to use unique `accountID` values per consent request to avoid confusion when processing webhooks and tracking consent status.
## Response
### Success Response (200 OK)
When the consent request is successfully created, the API returns a response with the consent handle that can be used to track the consent status:
```json Success Response theme={null}
{
"status": "success",
"ver": "1.21.0",
"data": {
"status": "PENDING",
"consent_handle": "3a3f2d96-fc3b-42e5-804f-e65d10a4be98"
}
}
```
| Field | Type | Description |
| --------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status` | string | Overall API call status. Will be `success` for successful requests. |
| `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 request. Will be `PENDING` when first created, indicating the customer has not yet approved or rejected the consent. |
| `data.consent_handle` | string | A unique UUID that identifies this consent request throughout its lifecycle. Store this value to track status changes, correlate webhook notifications, and perform subsequent operations like consent listing or revocation. |
### Error Response (400 Bad Request)
When the request contains invalid data or fails validation, the API returns an error response with details about what went wrong:
```json Error Response theme={null}
{
"ver": "1.21.0",
"timestamp": "2025-10-01T10:55:32.710Z",
"errorCode": "InvalidRequest",
"errorMsg": "Request has Invalid ProductID 2",
"status": "FP0001"
}
```
| 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. |
| `status` | string | FinPro-specific error code for categorization and tracking. Format is typically `FPxxxx` where the number indicates the error category. |
## 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. For PAN, ensure it follows the standard format (5 letters, 4 digits, 1 letter). |
| `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}}/v2/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"
}'
```
```javascript JavaScript theme={null}
const response = await fetch('{{Base_URL}}/v2/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'
})
});
const data = await response.json();
console.log(data);
```
```python Python theme={null}
import requests
url = "{{Base_URL}}/v2/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"
}
response = requests.post(url, json=payload, headers=headers)
print(response.json())
```
## Next Steps
After successfully creating a consent request with V2:
1. **Store the Consent Handle**: Persist the `consent_handle` returned in the response to your database, linked to the `accountID` you provided. This allows you to track the consent lifecycle and correlate webhook events.
2. **Redirect the Customer**: Since V2 does not return a web redirection URL directly, use the [Web Redirection Encryption](/api-reference/web-redirection/encryption) API to generate an encrypted URL that redirects the customer to the Account Aggregator consent flow. Alternatively, consider using the V3 API which returns a redirection URL in the response itself.
3. **Configure Webhooks**: Ensure you have webhook endpoints configured in the FinPro admin portal to receive consent lifecycle notifications (Approve, Reject, Revoke, Expire).
4. **Monitor Status**: Use the Consent List APIs to poll for consent status updates, or rely on webhook notifications for real-time status changes.
5. **Handle Customer Decision**: When the customer approves the consent (notified via webhook), you can proceed to request FI data using the Data Management APIs. If rejected, handle the rejection gracefully in your application workflow.
## API Version Comparison
* **V2 (this API)**: Returns only a consent handle with PENDING status. Requires manual customer redirection mechanism.
* **V3**: Returns a `webRedirectionUrl` that can be used to automatically redirect customers to the AA consent interface. Supports FIP filtering and redirect URL configuration.
Choose the version that best fits your integration requirements and customer journey design.
## OpenAPI
````yaml POST /v2/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:
/v2/requestconsent:
post:
tags:
- Consent Management
summary: Create Consent Request V2
description: >-
Create a new consent request to initiate the Account Aggregator flow for
customer data sharing authorization. Returns a consent handle for
tracking.
operationId: requestConsentV2
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConsentRequestV2'
example:
productID: TESTWM01
vua: 9876543210@onemoney
partyIdentifierType: MOBILE
partyIdentifierValue: '9876543210'
accountID: test123
responses:
'200':
description: Consent request created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ConsentResponseV2Success'
example:
status: success
ver: 1.21.0
data:
status: PENDING
consent_handle: 3a3f2d96-fc3b-42e5-804f-e65d10a4be98
'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-01T10:55:32.710Z'
errorCode: InvalidRequest
errorMsg: Request has Invalid ProductID
status: FP0001
'401':
description: Authentication Failed - Invalid credentials
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
deprecated: true
security:
- clientId: []
clientSecret: []
organisationId: []
appIdentifier: []
components:
schemas:
ConsentRequestV2:
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.
vua:
type: string
description: The customer's Virtual User Address (VUA) in format mobile@onemoney.
partyIdentifierType:
type: string
enum:
- MOBILE
- EMAIL
- PAN
description: The type of identifier being provided for the customer.
partyIdentifierValue:
type: string
description: The actual identifier value (10-digit mobile, email, or PAN).
accountID:
type: string
description: >-
A unique identifier from your system that links this consent request
to a customer interaction.
ConsentResponseV2Success:
type: object
properties:
status:
type: string
description: Overall API call status
ver:
type: string
description: API version
data:
type: object
properties:
status:
type: string
description: Consent request status (PENDING when first created)
consent_handle:
type: string
format: uuid
description: Unique identifier for tracking the consent request
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)
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
````