Consent Request V4

​

Overview

• 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.

​

Endpoint

POST {{Base_URL}}/v4/requestconsent

​

Authentication

​

Request Body

​

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.
• Date of Birth: The optional dob is an additional weak identifier used for account discovery at Financial Information Providers that require it. Provide it as either DDMMYYYY or YYYY-MM-DD; the platform normalizes it to YYYY-MM-DD before sending it to the Account Aggregator. A value matching neither format is rejected with a validation error. Supply it alongside pan when the target FIP mandates additional identifiers for discovery.

​

Response

​

Success Response (200 OK)

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

​

Response with Partial Failures

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

{
  "ver": "1.21.0",
  "timestamp": "2025-10-01T11:42:55.836Z",
  "errorCode": "InvalidRequest",
  "errorMsg": " [ partyIdentifierValue must be valid Mobile number ] "
}

​

Common Error Codes

​

Example Request

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",
    "dob": "1990-05-21",
    "fipID": [
        "ACME-FIP",
        "finsharebank"
    ],
    "redirectUrl": "https://yourapp.com/consent/callback"
}'

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',
    dob: '1990-05-21',
    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}`);
});

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",
    "dob": "1990-05-21",
    "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

// 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

# 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

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.

• 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