> ## 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 Management

> Comprehensive consent lifecycle management for Account Aggregator data flows

## Overview

FinPro's Consent Management module provides Financial Information Users with complete control over the customer consent lifecycle, from creation and approval to revocation and expiry. The system handles all aspects of RBI-compliant consent orchestration, including customer redirection to Account Aggregators, real-time status tracking via webhooks, and bulk operations for high-volume use cases.

## Consent Lifecycle

The consent journey follows a well-defined lifecycle with multiple states and transitions:

<Steps>
  <Step title="Creation">
    FIU calls the Consent Request API with customer identifier and product template
  </Step>

  <Step title="Pending">
    Customer receives redirect URL to Account Aggregator for approval
  </Step>

  <Step title="Active">
    Customer approves consent within the AA interface
  </Step>

  <Step title="Paused / Resumed">
    Customer temporarily pauses or resumes data sharing
  </Step>

  <Step title="Revoked / Expired">
    Consent ends due to customer revocation or validity expiry
  </Step>
</Steps>

### Consent States

| State        | Description                                    | Next Possible States     |
| ------------ | ---------------------------------------------- | ------------------------ |
| **PENDING**  | Consent created, awaiting customer approval    | ACTIVE, REJECTED         |
| **ACTIVE**   | Customer approved, data fetch authorized       | PAUSED, REVOKED, EXPIRED |
| **REJECTED** | Customer declined consent request              | (Terminal state)         |
| **PAUSED**   | Customer temporarily stopped data sharing      | RESUMED, REVOKED         |
| **RESUMED**  | Customer reactivated previously paused consent | PAUSED, REVOKED, EXPIRED |
| **REVOKED**  | Customer permanently withdrew consent          | (Terminal state)         |
| **EXPIRED**  | Consent validity period elapsed                | (Terminal state)         |

## Consent Request APIs

FinPro offers multiple API versions to support different integration patterns and use cases.

### V2 Consent Request (Deprecated)

<Warning>V2 is deprecated. New integrations should use [V3 Consent Request](/api-reference/consent/request-v3) instead.</Warning>

The V2 API provides basic consent creation with essential parameters.

**Key Parameters:**

* `productID`: Reference to pre-configured consent template
* `vua`: Customer's Virtual User Address (mobile\@aa or pan\@aa)
* `accountID`: FIU's internal customer/journey identifier
* `redirect`: Boolean indicating if redirect URL should be generated

**Use Case:** Simple consent journeys with minimal customization

<Card title="API Documentation" icon="code" href="/api-reference/consent/request-v2">
  View V2 Consent Request Details
</Card>

### V3 Consent Request (Standard)

The V3 API adds support for enhanced customer attributes and custom configurations.

**Additional Parameters:**

* `name`: Customer's full name
* `email`: Customer's email address
* `accountRef`: Additional reference numbers for tracking
* `customAttributes`: Free-form metadata for journey tracking

**Use Case:** Consent journeys requiring customer identification and enhanced tracking

<Card title="API Documentation" icon="code" href="/api-reference/consent/request-v3">
  View V3 Consent Request Details
</Card>

## Consent Templates

Consent templates define the structure, scope, and behavior of consent requests. Templates are pre-configured in the FinPro admin portal and referenced by `productID` in API calls.

### Template Configuration

<AccordionGroup>
  <Accordion title="Purpose and Compliance">
    **Purpose Code**: RBI/SEBI/NPCI-defined purpose codes (e.g., 101 for personal loans, 102 for housing loans)

    **Template Name**: Customer-facing name displayed in AA interface

    **Description**: Detailed explanation of why data is being requested

    **Regulatory Compliance**: Automatic validation against RBI AA framework requirements
  </Accordion>

  <Accordion title="Consent Validity">
    **Start Date**: When the consent becomes active (immediate or future-dated)

    **End Date**: When the consent automatically expires

    **Maximum Validity**: Configurable up to regulatory limits (typically 1-2 years)
  </Accordion>

  <Accordion title="Consent Type">
    **ONETIME**: Single data fetch upon approval

    **PERIODIC**: Recurring data fetches at specified intervals

    **Frequency**: For periodic consents, defines fetch cadence (daily, weekly, monthly)
  </Accordion>

  <Accordion title="Financial Information Types">
    Select which types of financial data can be fetched:

    * Savings Accounts
    * Current Accounts
    * Term Deposits (FD/RD)
    * Mutual Funds
    * Equities and Debentures
    * Insurance Policies (Life, General)
    * NPS Accounts
    * Bonds and Government Securities
    * GST Returns
  </Accordion>

  <Accordion title="Data Range">
    **From Date**: Historical data start point (e.g., 6 months ago, 1 year ago)

    **To Date**: Data end point (typically current date)

    **Maximum Range**: Configurable based on use case (regulatory limits apply)
  </Accordion>

  <Accordion title="Data Filters (Optional)">
    **Transaction Amount Filters**: Specify minimum/maximum transaction amounts to fetch

    **Credit/Debit Filters**: Restrict to only credits, only debits, or both

    **Narration Patterns**: Include/exclude transactions based on description keywords

    **Date Filters**: Fetch data only from specific date ranges within the overall consent period
  </Accordion>
</AccordionGroup>

### Template Management

**Creating Templates:**

1. Navigate to **Admin Portal → Consent Templates**
2. Click **Create New Template**
3. Configure all template parameters
4. Save and note the generated `productID`

**Updating Templates:**

* Template updates apply only to new consent requests
* Existing active consents continue using the original template configuration
* Version control tracks all template changes for audit purposes

**Deleting Templates:**

* Templates with active consents cannot be deleted
* Mark templates as inactive to prevent new consent creation while preserving historical records

## Bulk Consent Management

For high-volume operations, FinPro provides batch APIs and admin interfaces to manage consents at scale.

### Bulk Consent Creation

**Use Cases:**

* Pre-approval campaigns where customer lists are uploaded
* Loan portfolio monitoring requiring consent setup for multiple borrowers
* Collections campaigns targeting specific customer segments

**Process:**

1. Upload CSV file with customer details (VUA, accountID, productID)
2. FinPro processes batch and creates consent requests
3. Redirect URLs are generated for each customer
4. Webhooks notify of approval/rejection for each consent

**Best Practices:**

* Batch size should not exceed 10,000 records per upload
* Include valid email/mobile for customer communication
* Ensure VUA format is correct (mobile\@aa or pan\@aa)

### Bulk Consent Revocation

**Use Cases:**

* Loan closure scenarios where ongoing monitoring is no longer needed
* Compliance requirements to cease data collection
* Customer request to revoke multiple consents

**Process:**

1. Navigate to **Admin Portal → Bulk Operations**
2. Upload list of consent IDs or accountIDs to revoke
3. Confirm bulk revocation action
4. System sends revocation requests to respective AAs
5. Webhook notifications confirm completion

<Card title="API Documentation" icon="code" href="/api-reference/consent/revoke">
  View Consent Revocation API
</Card>

## Webhook Notifications

FinPro sends real-time webhook notifications for all consent lifecycle events — including `CONSENT_APPROVED`, `CONSENT_REJECTED`, `CONSENT_REVOKED`, `CONSENT_EXPIRED`, `CONSENT_PAUSED`, and `CONSENT_RESUMED` — enabling FIUs to react immediately to customer actions.

All webhooks are signed with HMAC-SHA256 for verification via the `X-Webhook-Signature` header.

<Card title="Webhooks Documentation" icon="bell" href="/api-reference/webhooks/overview">
  Full payload examples, HMAC verification code, event lifecycle diagrams, and integration guidance
</Card>

## Consent Listing and Tracking

FinPro provides APIs to query consent status and history for individual customers or across the entire portfolio.

### Consent List APIs

<CardGroup cols={2}>
  <Card title="Consent List" icon="list" href="/api-reference/consent/list">
    Retrieve all consents for a customer or accountID
  </Card>

  <Card title="Consent List V2" icon="list-check" href="/api-reference/consent/list-v2">
    Enhanced listing with pagination and filtering
  </Card>

  <Card title="Unique Accounts" icon="fingerprint" href="/api-reference/consent/list-unique">
    Get distinct linked accounts across all consents
  </Card>
</CardGroup>

### Query Parameters

**Filter by:**

* `accountID`: FIU's internal customer identifier
* `vua`: Customer's Virtual User Address
* `consentId`: Specific consent identifier
* `productID`: Consent template reference
* `status`: Filter by consent state (ACTIVE, EXPIRED, etc.)

**Pagination:**

* `page`: Page number (default: 1)
* `limit`: Results per page (default: 20, max: 100)

**Sorting:**

* `sortBy`: Field to sort by (createdAt, expiryDate, status)
* `sortOrder`: ASC or DESC

## Consent Revocation

FIUs can programmatically revoke consents on behalf of customers or in response to business logic.

### Revocation Scenarios

**Loan Closure:**
When a loan is fully repaid, revoke recurring monitoring consents to cease data collection.

**Non-Disbursal:**
If a loan application is rejected, revoke the consent to avoid unnecessary data fetching.

**Customer Request:**
Honor customer requests to stop data sharing by revoking consents via API.

**Compliance:**
Revoke consents in response to regulatory requirements or data deletion requests.

### Revocation API

<Card title="API Documentation" icon="ban" href="/api-reference/consent/revoke">
  View Consent Revocation API Details
</Card>

**Request Example:**

```json theme={null}
{
  "consentId": "3c92001e-57ea-4320-bbb8-66d524bfb435",
  "reason": "Loan fully repaid, monitoring no longer required"
}
```

**Response:**

```json theme={null}
{
  "status": "SUCCESS",
  "message": "Consent revoked successfully",
  "consentId": "3c92001e-57ea-4320-bbb8-66d524bfb435",
  "revokedAt": "2023-08-20T14:30:00.000Z"
}
```

## Best Practices

<AccordionGroup>
  <Accordion title="Design Consent Templates Thoughtfully">
    Keep templates focused on specific use cases. Avoid overly broad consent scopes that may confuse customers or trigger regulatory scrutiny.
  </Accordion>

  <Accordion title="Implement Robust Webhook Handling">
    Ensure webhook endpoints are highly available, respond quickly (within 5 seconds), and implement retry logic for failed processing.
  </Accordion>

  <Accordion title="Track Consent Status Consistently">
    Maintain a local copy of consent states synchronized via webhooks. Use Consent List APIs to reconcile discrepancies.
  </Accordion>

  <Accordion title="Respect Customer Revocations">
    Immediately cease data fetching upon receiving revocation webhooks. Failure to honor revocations can result in compliance violations.
  </Accordion>

  <Accordion title="Automate Consent Renewal">
    For long-term monitoring use cases, prompt customers to renew consents before expiry to maintain uninterrupted data access.
  </Accordion>

  <Accordion title="Monitor Consent Approval Rates">
    Track approval vs rejection rates to identify friction points in the consent journey. Optimize template descriptions and customer communication.
  </Accordion>
</AccordionGroup>

## Integration Checklist

<Steps>
  <Step title="Configure Consent Templates">
    Create templates in FinPro admin portal for each product journey
  </Step>

  <Step title="Set Up Webhook Endpoints">
    Deploy webhook handlers with signature verification
  </Step>

  <Step title="Integrate Consent Request APIs">
    Call appropriate API version (V2/V3/V4) based on requirements
  </Step>

  <Step title="Handle Redirect Flow">
    Redirect customers to AA using provided URL or deep link
  </Step>

  <Step title="Process Webhook Events">
    React to consent lifecycle events in real-time
  </Step>

  <Step title="Implement Consent Revocation">
    Add logic to revoke consents when business conditions require
  </Step>

  <Step title="Test End-to-End Flows">
    Validate consent creation, approval, data fetch, and revocation in UAT
  </Step>
</Steps>

## Support

For questions about consent configuration, webhook troubleshooting, or API integration, contact Moneyone support through the FinPro admin portal.

<CardGroup cols={2}>
  <Card title="API Reference" icon="code" href="/api-reference/consent/request-v2">
    Complete API documentation
  </Card>

  <Card title="Admin Portal Guide" icon="book" href="/guides/admin-portal">
    Learn template and webhook configuration
  </Card>
</CardGroup>