#Consent object

The consent object is the core of the AA framework. When an FIU requires data about the user, the request is packaged in the form of a consent object.

Consent object contains the information about all the different types of data the FIU needs, the purpose of the data, and how the FIU plans to use the data and so on.

#FIP Selector Screen

→ Scroll down to see the detailed FIP Selector Screen section

#Consent request object

#Context Parameters

The context parameter accepts key-value pairs to customize the consent flow. Below are the supported context keys:

#Context property examples

Filter by account type

"context": [
    {
      "key": "accounttype",
      "value": "CURRENT"
    }
  ]

Filter by FIP ids

"context": [
    {
      "key": "fipId",
      "value": "setu-fip,icici-fip"
    }
  ]

Exclude specific FIP ids

"context": [
    {
      "key": "excludeFipIds",
      "value": "setu-fip,icici-fip"
    }
  ]

Specify consent review location

"context": [
    {
      "key": "consentReviewAt",
      "value": "first"
    }
  ]

Custom purpose description

"context": [
    {
      "key": "purposeDescription",
      "value": "For loan eligibility assessment"
    }
  ]

Specify purpose code

"context": [
    {
      "key": "purposeCode",
      "value": "101"
    }
  ]

Configure alternate number

"context": [
    {
      "key": "alternateNumber",
      "value": "true"
    }
  ]

Specify account selection mode

"context": [
    {
      "key": "accountSelectionMode",
      "value": "multi"
    }
  ]

Filter by transaction type

"context": [
    {
      "key": "transactionType",
      "value": "debit"
    }
  ]

#Consent response object

#Understanding Tags in AA Framework

• Tags must first be created at the product instance level before they can be used in any requests.

• Tags can be created and managed while setting up or updating a product instance. They are unique identifiers (max 100 characters) that can be linked to multiple product instances.

• Tags are visible in consent and data-fetch reports, and serve as filters in analytics dashboards. Use them to track user journeys, monitor failures, analyze behavior, measure campaign performance, and generate custom insights.

• Key limitations and rules:

• Tags are case-sensitive (e.g., "partnerA" and "PartnerA" will be considered two different tags)
• Duplicate tags are not allowed
• Bulk tagging for historical data is not supported
• Number of tags per FIU is configurable
• Invalid characters will trigger errors
• System issues may prevent tag application (with error notifications)

• Best practice: Use clear, consistent, and easily understandable tag names for effective tracking.

• To add tags to a consent request, include them under the additionalParams field:

{
  "consentDetail": {
    ...
  },
  ...,
  "additionalParams": {
    "tags": ["Loan_Tracking", "Partner_X"]
  }
}

#FIP Selector Screen

#Overview

The FIP Selector Screen is a feature that helps improve AA journey success rates by intelligently routing users to the best performing Account Aggregator (AA) - FIP pair.

It enables FIUs to:

• Select the best-performing AA for a given FIP (instead of just the highest overall-performing AA).
• Provide explicit user consent for using PII (mobile number) to discover pre-existing handles on AAs.
• Reduce drop-offs on the account linking page by routing users to an AA where they already have a handle.
• Move away from latency-prone autodiscovery flows by adopting a faster, targeted manual discovery approach.

All of this enables better consent conversion across the funnel

#How it works

1. User lands on the FIP Selector Screen before the AA journey
2. FIU (or Setu module) shows available FIPs and takes explicit user consent to use PII data via a checkbox.
3. Setu uses this consent to:
   • Discover pre-existing AA handles (using mobile number).
   • Route requests to the best-performing AA for that specific FIP.
4. The improved routing logic kicks in, reducing drop-offs and boosting success rates.

#Flow diagram

The FIP Selector Screen flow works as follows:

1. User selects FIP → User chooses their preferred Financial Information Provider
2. Consent checkbox for discovery → User provides explicit consent for PII usage
3. Setu checks AA handles using mobile number → System discovers pre-existing handles
4. Best performing AA for FIP → Intelligent routing based on performance data
5. Consent creation via AA → Consent is created through the optimal AA
6. Account linking + Data fetch → Final step of account connection and data retrieval

#How FIUs can enable this

#✅ Case 1: FIUs with an existing FIP Selector Screen

1. Add the consent checkbox to your FIP Selector Screen.
2. Share a screenshot of the updated screen with Setu.
3. For Finvu, also complete the AA Profile Discovery API Access Request form.
4. For OneMoney and Anumati, Setu will share your screenshot with the AA for approval.
5. Once confirmed, this data will be used in the AA routing logic.

#✅ Case 2: FIUs without an FIP Selector Screen

1. Setu will provide an opt-in module for the FIP Selector Screen.
2. No need to share screenshots - Setu will handle UI, routing, and compliance requirements end-to-end.
3. Setu will also assist with form submissions for AA sign-offs

#Tech implementation

#Case 1: FIUs NOT passing Account Aggregator the context filter (Multi AA)

Create Consent API Changes

Request Payload:

{
  "vua": "9999999999"  // Only mobile number (no AA suffix)
}

Response Payload:

{
  "vua": "9999999999",     // Only mobile number
  "status": "INITIATED",   // Initial status (PENDING status sent via notification once actual consent is created with AA)
  // ...other fields remain unchanged
}

Key Changes:

• Initial status is INITIATED instead of PENDING
• VUA contains only mobile number without AA suffix
• Actual PENDING status communicated via notification after consent creation

Notification Handler Updates

Once the user completes the bank selection, we'll create consent on the most optimal Account Aggregator (AA) for the selected Financial Information Provider (FIP) and then send the PENDING status.

Success Notification Payload:

{
  "data": {
    "status": "PENDING",                    // New additional status
    "vua": "9999999999@selectedAA"        // Updated with selected AA
  },
  "success": true,
  "type": "CONSENT_STATUS_UPDATE", 
  "error": null,
  "consentId": "<<consentId>>",
  "notificationId": "<<notificationId>>",
  "timestamp": "2024-01-29T07:28:24.547Z"
}

Failure Notification Payload:

{
  "success": false,
  "error": {
    "code": "ConsentObjectCreationFailure", 
    "message": "Internal server error occurred while fetching consent details from upstream AA"
  },
  "data": null,
  "consentId": "<<consentId>>",
  "notificationId": "<<notificationId>>",
  "timestamp": "2024-01-29T07:28:24.547Z",
  "type": "CONSENT_STATUS_UPDATE"
}

Required Implementation:

• Add CONSENT_STATUS_UPDATE notification handler
• Update status management logic
• Handle VUA format changes

#Case 2: FIUs passing specific AA in the context filter

✅ No changes required from FIUs for Case 2

This case works immediately with existing implementations as it's purely an optimization that doesn't affect consent status transitions.