#Consent flow

Get users' consent before you can start pulling their financial data with Setu AA by initiating Consent flow in your application. This flow broadly consists of two parts:

1. Create consent request — This is essentially a one-time data request that your user needs to approve. To know more details about this please visit Consent Object page. Once a consent is created, you will receive a unique id with status = PENDING, along with a url where you can redirect your customer to consent approval screens, to review the data request. Here, the user may approve or reject the request

2. Consent status — You can track the consent status with Get Consent Status API, alternatively Setu will notify you when the user has acted upon the consent request. See Notifications to configure your notification endpoint.

Here are some more advanced features related to consents, which are explained in detail at the end.

1. Multi consents — Merge two consents into a single UI flow, with its own unique dual consent ID.

2. Revoke a consent — A revoke API for FIUs to withdraw or manually revoke an end users' consent for any purpose or on behalf of the customer

#Create Consent API

Call this API to create a consent request. The details of the request will be presented to your customer on Setu’s screens, as part of the next step.

POST /consents
{
  "consentDuration": {
    "unit" : "MONTH",
    "value": "4"
  },
  "vua":  "999999999", // {{mobile}} or {{mobile}}@handle. Ex: 999999999@setu or 999999999@onemoney
  "dataRange": {
      "from": "2020-04-01T00:00:00Z",
      "to": "2023-01-01T00:00:00Z"
  },
  "context": [
  ]
}

{
    "id": "6d285134-c764-49ab-b32d-ead003161587",
    "url": "https://fiu.setu.co/v2/consents/webview/6d285134-c764-49ab-b32d-ead003161587",
    "status": "PENDING",
    "detail": {
        "consentStart": "2023-04-10T05:36:43.011Z",
        "fiTypes": ["DEPOSIT"],
        "fetchType": "PERIODIC",
        "purpose": {
            "category": {
                "type": "string"
            },
            "refUri": "https://api.rebit.org.in/aa/purpose/101.xml",
            "code": "101",
            "text": "Loan underwriting"
        },
        "vua": "999999999@onemoney",
        "dataRange": {
            "from": "2020-04-01T00:00:00.000Z",
            "to": "2023-01-01T00:00:00.000Z"
        },
        "consentTypes": ["TRANSACTIONS", "PROFILE", "SUMMARY"],
        "consentMode": "STORE",
        "consentExpiry": "2023-08-08T05:36:43.011Z",
        "frequency": {
            "value": 30,
            "unit": "MONTH"
        },
        "dataLife": {
            "value": 1,
            "unit": "MONTH"
        }
    },
    "redirectUrl": "https://setu.co",
    "context": [],
    "usage": {
        "count": "0",
        "lastUsed": null
    },
    "traceId": "1-6433a06a-4b99c3a81b538bc762b5aa08"
}

#Consent review by customer

On redirecting your users to url, it opens up a Consent approval flow that permits consent approval/rejection. This url can easily be embedded as a webview or be used to redirect from a website. The URL is of the form:

https://<fiu-base-url>/consents/webview/<id>

• <fiu-base-url> — This is the base URL provided by Setu.
• <id> — This is the request ID of the consent generated returned after the create consent request.

On getting redirected to the url, your users will be asked to verify their mobile number to further initiate the account fetching process. The mobile verification does a login, or register them with Setu using their mobile number. Setu creates a unique account aggregator handle for every registered customer.

The following steps are handled by Setu’s screens—

• OTP verification on user's mobile number
• Setu authenticates the user and displays the data request
• Setu fetches the Financial Information Providers or FIPs
• User links the FIPs and reviews the request
• Setu validates and saves consent
• Setu sends notification to you to confirm consent approval. At this point, consent status is APPROVED or REJECTED

#Get Consent API

Call this API to get the consent details and the updated status of a consent request by passing its unique id.

If the consent is approved, the status in the response will be ACTIVE. After this, you can now initiate Data flow for the approved consent request.

Request

 GET /consents/:id 

{
    "id": "e082b325-2692-47cd-88cf-875068df9051"
    "url": "https://fiu.setu.co/consents/v2/webview/e082b325-2692-47cd-88cf-875068df9051",
    "status": "PENDING",
    "context": [],
    "detail": {
        "vua": "9999999999@anumati",
        "consentStart": "2023-04-04T07:10:41.165Z",
        "consentExpiry": "2023-08-02T12:40:41.165Z"
    },
    "accountsLinked": [],
    "traceId": "26b8bc4c-5d33-43a1-a58f-be5d4d0acbd0"
}

{
    "id": "73633c01-d14d-4dbb-8a82-d82e53df5920",
    "url": "https://fiu.setu.co/v2/consents/webview/73633c01-d14d-4dbb-8a82-d82e53df5920",
    "status": "PENDING",
    "detail": {
        "purpose": {
            "refUri": "https://api.rebit.org.in/aa/purpose/101.xml",
            "code": "101",
            "text": "Loan",
            "category": {
                "type": "string"
            }
        },
        "consentStart": "2023-05-22T07:39:41.333Z",
        "fiTypes": [
            "DEPOSIT",
            "EQUITIES",
            "MUTUAL_FUNDS",
            "GST_GSTR3B",
            "GST_GSTR2A",
            "GST_GSTR1"
        ],
        "frequency": {
            "value": 3,
            "unit": "MONTH"
        },
        "fetchType": "PERIODIC",
        "vua": "99999999999@anumati",
        "dataLife": {
            "value": 1,
            "unit": "YEAR"
        },
        "consentExpiry": "2023-09-19T13:09:41.333Z",
        "dataFilter": [],
        "consentTypes": ["TRANSACTIONS", "PROFILE"],
        "dataRange": {
            "from": "2020-04-01T00:00:00.000Z",
            "to": "2023-01-01T00:00:00.000Z"
        },
        "consentMode": "STORE"
    },
    "context": [],
    "usage": {
        "lastUsed": null,
        "count": "0"
    },
    "accountsLinked": [],
    "traceId": "74d3032a-597e-40e1-859b-67b035e8a0e0"
}

#Multi consents

In the Account Aggregator (AA) ecosystem in India, the multi consent feature allows Financial Information Users (FIUs) to streamline the process of obtaining consent from customers for data sharing. By merging multiple separate consent requests into a single flow, FIUs can enhance the user experience, reduce friction, and ensure higher completion rates for consent acquisition.

Features

• Single UI Flow — Merges two consent requests into a single UI flow, displaying the consent parameters of each request in a consolidated manner.

• Optional and mandatory consents — Offers flexibility in making one of the consents optional, while the other remains mandatory, allowing customers to choose which data they are willing to share.

• Unified OTP authentication — Simplifies the authentication process by requiring only a single set of OTP authentications for the multi consent flow.

Create multi consent API

• Create individual consent requests — Prior to using the Dual consent API, create the individual consent requests as per the standard procedure in the AA ecosystem.

• Create multi consent — Use the provided API endpoint to create a multi consent process by specifying which consents are optional and which are mandatory.

• Redirecting the customer to consent approval — On success, direct the customer to the redirectUrl for consent approval.

• Get consent status — Monitor the status of each consent through the same Get Consent API, that is used for a single consent.

Request

Sample Request body

{
    "optionalConsents": [],
    "mandatoryConsents": ["36c34bbc-9408-454e-a80e-e44f4fc4cdbf", "037801eb-923e-4592-80cc-b05cecaedba1"]
}

Sample Response

{
    "consentCollectionId": "5f3a5564-9abc-48f9-ae32-af4b22c781ce",
    "url": "https://fiu-sandbox.setu.co/v2/consents/webview/5f3a5564-9abc-48f9-ae32-af4b22c781ce",
    "txnid": "6aeb84aa-b078-4ab1-bdb6-fa0e82b18bb3",
    "traceId": "b3f26ccb-a64d-4692-a02e-282bd8ef7778"
}

#Revoke consent

The customer in the Account Aggregator framework has full control over their data and to ensure this, the framework allows the user to revoke a consent at any point of time. The general process of revoking a consent requires the user to login to Account Aggregator's platform and revoke the consent manually. However this might not be a seamless experience for the customer, who might expect to be able to revoke a consent directly from FIU's app. There might also be cases where the FIU might want to automatically revoke a consent.

To solve for these use cases, AA framework provides a way for FIUs to communicate revokation of consent to the Account Aggregator. Setu's AA gateway provides a simple API to perform this action for any AA.

Request

Sample Response

{
    "status": "REVOKED",
    "traceId": "b3f26ccb-a64d-4692-a02e-282bd8ef7778"
}

#Get Last Fetch Status

This API retrieves the last data fetch status for a given consent ID. It provides details about the most recent data fetch operation associated with the consent, including the timestamp of the fetch, the data range covered, and the identifiers of the financial information providers (FIPs) involved.

Request

Sample Response

{
    "lastFetchedAt": "2024-11-21T07:48:16.404Z",
    "dataRange": {
        "from": "2022-01-01T00:00:00.000Z",
        "to": "2024-06-01T00:00:00.000Z"
    },
    "lastFetchedFips": [
        "setu-fip",
        "setu-fip",
        "setu-fip",
        "setu-fip",
        "setu-fip",
        "setu-fip",
        "setu-fip-2",
        "setu-fip-2",
        "setu-fip-2",
        "setu-fip-2"
    ],
    "traceId": "1-673ee5c2-5e4e353d5d08c03372b26f6c"
}