Consent Request V3

​

Overview

​

Endpoint

POST {{Base_URL}}/v3/requestconsent

​

Authentication

​

Request Body

​

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.
• FIP Filtering: When fipID array is provided, only those specific FIPs will be available during the customer’s account discovery journey. This is useful for scenarios where you have partnerships with specific banks or want to limit options for regulatory or business reasons.
• Redirect URL Security: The redirectUrl should be a secure HTTPS endpoint that you control. Avoid using dynamic or user-provided URLs to prevent open redirect vulnerabilities.
• PAN Validation: When provided, the PAN will be validated against standard format (5 uppercase letters, 4 digits, 1 uppercase letter). Invalid PAN formats will result in a validation error.

​

Response

​

Success Response (200 OK)

{
  "ver": "1.21.0",
  "status": "success",
  "data": {
    "webRedirectionUrl": "https://webrd.onemoney.in/uat/v2/?ecreq=luBWxKb9cUczWlDX3GgkW1Z8MfF2hVFUPAu4yrYamw5PqsZTtB63VYdEsAquR0G4qTVHIgLwyWFPtloc5FYOqajGrLkZnWQ0UOlZ_R4L9p9nM_qafwDXioAEORNfwDbeh6NKpt3ksnzy4GGHSXcw5to8Tmby9EVEwswBlIQB..."
  }
}

​

Important Notes About Web Redirection URL

• Single-Use Token: The webRedirectionUrl contains a one-time token that expires after use or after a configured time period (typically 24 hours). Do not reuse the same URL for multiple attempts.
• Secure Redirect: The encrypted request parameter ensures that consent details cannot be tampered with during the redirect. The AA will validate the signature before displaying the consent interface.
• URL Expiry: If the customer does not complete the journey within the expiry window, you’ll need to create a new consent request to generate a fresh URL.

​

Error Response (400 Bad Request)

{
  "ver": "1.21.0",
  "timestamp": "2025-10-01T11:41:43.027Z",
  "errorCode": "InvalidRequest",
  "errorMsg": "Request has Invalid ProductID  2",
  "status": "FP0001"
}

​

Common Error Codes

​

Example Request

curl --location '{{Base_URL}}/v3/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"
}'

const response = await fetch('{{Base_URL}}/v3/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();
console.log(data.data.webRedirectionUrl);

import requests

url = "{{Base_URL}}/v3/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()
print(data['data']['webRedirectionUrl'])

​

Integration Patterns

​

Web Application Integration

// After getting the API response
const { webRedirectionUrl } = response.data;

// Option 1: Full page redirect
window.location.href = webRedirectionUrl;

// Option 2: Open in new tab/window
window.open(webRedirectionUrl, '_blank');

// Option 3: Embed in iframe (if your AA supports it)
document.getElementById('aa-iframe').src = webRedirectionUrl;

​

Mobile Application Integration

// iOS (Swift)
if let url = URL(string: webRedirectionUrl) {
    let safariVC = SFSafariViewController(url: url)
    present(safariVC, animated: true)
}

// Android (Kotlin)
val intent = Intent(Intent.ACTION_VIEW, Uri.parse(webRedirectionUrl))
startActivity(intent)

​

Next Steps

1. Redirect the Customer: Use the webRedirectionUrl to redirect the customer to the Account Aggregator interface. Choose the integration pattern that best fits your application type (web, mobile, etc.).
2. Configure Webhooks: Ensure you have webhook endpoints configured in the FinPro admin portal to receive consent lifecycle notifications (Approve, Reject, Revoke, Expire). The webhook will be triggered when the customer completes the journey.
3. Handle Redirect Callback: Implement the callback handler at your redirectUrl endpoint to process the customer’s return after completing the AA journey. Parse any status information included in the callback URL parameters.
4. Monitor Consent Status: Listen for webhook notifications to get real-time updates on consent status changes. Alternatively, use the Consent List APIs to poll for status updates.
5. Request FI Data: Once you receive a consent approval webhook, use the Data Management APIs to request and retrieve financial information from the linked accounts.

​

API Version Comparison

• V2: Returns only a consent handle with PENDING status. Requires manual customer redirection mechanism.
• V3 (this API): Returns a webRedirectionUrl for automatic customer redirect. Supports FIP filtering and custom redirect URLs. Single consent handle for all FIPs.
• V4: Returns separate consent handles per FIP when multiple FIPs are specified. Best for scenarios requiring granular tracking of multi-FIP consent journeys.