Consent Request V2

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

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` or `email@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:

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

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

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

Next Steps

After successfully creating a consent request with V2:

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.
Redirect the Customer: Since V2 does not provide a web redirection URL, you’ll need to use your own mechanism to redirect the customer to the Account Aggregator interface. Consider using V3 or V4 APIs if you need an automated redirection URL.
Configure Webhooks: Ensure you have webhook endpoints configured in the FinPro admin portal to receive consent lifecycle notifications (Approve, Reject, Revoke, Expire).
Monitor Status: Use the Consent List APIs to poll for consent status updates, or rely on webhook notifications for real-time status changes.
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.
V4: Returns separate consent handles per FIP when multiple FIPs are specified. Provides granular control over multi-FIP consent scenarios with individual tracking per financial institution.

Choose the version that best fits your integration requirements and customer journey design.

Consent Management

Data Management

Web Redirection

User Management

Miscellaneous

Overview

Endpoint

Authentication

Request Body

Important Notes

Response

Success Response (200 OK)

Error Response (400 Bad Request)

Common Error Codes

Example Request

Next Steps

API Version Comparison

Consent Management

Data Management

Web Redirection

User Management

Miscellaneous

​Overview

​Endpoint

​Authentication

​Request Body

​Important Notes

​Response

​Success Response (200 OK)

​Error Response (400 Bad Request)

​Common Error Codes

​Example Request

​Next Steps

​API Version Comparison

Overview

Endpoint

Authentication

Request Body

Important Notes

Response

Success Response (200 OK)

Error Response (400 Bad Request)

Common Error Codes

Example Request

Next Steps

API Version Comparison