#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:
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
withstatus = PENDING
, along with aurl
where you can redirect your customer to consent approval screens, to review the data request. Here, the user may approve or reject the requestConsent 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.
Multi consents — Merge two consents into a single UI flow, with its own unique dual consent ID.
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@onemoney","dataRange": {"from": "2020-04-01T00:00:00Z","to": "2023-01-01T00:00:00Z"},"context": []}
Response
Consent gets created with a unique identifier id
with status as PENDING
. Redirect your customers to consent approval flow url
to review the consent.
{"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
Use Setu FIP and get access to mock financial data on staging
#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.
Additionally, Setu AA will notify you on the consent status update by sending a webhook notification to the configured endpoint you entered on the Bridge. See more details on Consent Notifications.
Request
GET /consents/:id
Response
{"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@onemoney","consentStart": "2023-04-04T07:10:41.165Z","consentExpiry": "2023-08-02T12:40:41.165Z"},"accountsLinked": [],"traceId": "26b8bc4c-5d33-43a1-a58f-be5d4d0acbd0"}
If query param expanded=true
is included in the request
{"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@onemoney","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.
Currently, the multi consent feature supports merging only two consents into a multi consent
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
Base URL | Sandbox: https://fiu-sandbox.setu.co Production: https://fiu.setu.co |
---|---|
Path | /v2/consents/consents/collection |
Method | POST |
Headers | Content-Type : application/json Authorization : Bearer access_token x-product-instance-id : product-instance-id |
Sample Request body
{"optionalConsents": [],"mandatoryConsents": ["36c34bbc-9408-454e-a80e-e44f4fc4cdbf", "037801eb-923e-4592-80cc-b05cecaedba1"]}
At least one consent must be marked as mandatory to create a multi consent
Sample Response
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
Base URL | Sandbox: https://fiu-sandbox.setu.co Production: https://fiu.setu.co |
---|---|
Path | /v2/consents/:request_id/revoke |
Method | POST |
Headers | Content-Type : application/json Authorization : Bearer access_token x-product-instance-id : product-instance-id |
This is a POST API without any request body
Sample Response
Response
{"status": "REVOKED","traceId": "b3f26ccb-a64d-4692-a02e-282bd8ef7778"}
Was this page helpful?