Setu
AA Gateway v1

Consent flow

API Playground

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.

Before

Request

Read up more about the the Detail object here.

POST /Consent
{
    "ver"       : "1.0",
    "timestamp" : "2019-08-24T14:15:22Z",
    "txnid"     : "4a4adbbe-29ae-11e8-a8d7-0289437bf331",
    "ConsentDetail" : {
        <Refer to “Consent object” for more information>
        }
}
Response

Your will receive a consentHandle in the response, which is the unique identifier for the created consent request.

Redirect your customer to consent manager at this point to review the consent. Read more about review consent below.

{
    "ver" : "1.0",
    "timestamp" : "2018-12-06T11:39:57.153Z",
    "txnid" : "4a4adbbe-29ae-11e8-a8d7-0289437bf331",
    "Customer" : {
        "id" : "customer_mobile_number@AA_identifier"
    },
    "ConsentHandle" : "39e108fe-9243-11e8-b9f2-0256d88baae8"
}

Now

Request

Read up more about the the Detail object here.

POST /consents
{
    "Detail": {
        "consentStart": "2022-01-06T06:23:51.832Z",
        "consentExpiry": "2022-04-23T05:44:53.822Z",
        "Customer": {
            "id": "9999999999@setu-aa" // {mobile_number@onemoney-aa}
        },
        "FIDataRange": {
            "from": "2021-04-01T00:00:00Z",
            "to": "2021-10-01T00:00:00Z"
        },
        "consentMode": "STORE",
        "consentTypes": [
            "TRANSACTIONS",
            "PROFILE",
            "SUMMARY"
        ],
        "fetchType": "PERIODIC",
        "Frequency": {
            "value": 30,
            "unit": "MONTH"
        },
        "DataFilter": [
            {
                "type": "TRANSACTIONAMOUNT",
                "value": "5000",
                "operator": ">="
            }
        ],
        "DataLife": {
            "value": 1,
            "unit": "MONTH"
        },
        "DataConsumer": {
            "id": "setu-fiu-id"
        },
        "Purpose": {
            "Category": {
                "type": "string"
            },
            "code": "101",
            "text": "Loan underwriting",
            "refUri": "https://api.rebit.org.in/aa/purpose/101.xml"
        },
        "fiTypes": [
            "DEPOSIT"
        ]
    },
    "redirectUrl": "https://setu.co"
}
Response

Consent gets created with a unique identifier id with status as PENDING Redirect your customers to consent manager url to initiate consent review flow.

{
  "id": "60c76fa3-601c-4b9d-ad30-d33c0ebcacf3",
  "url": "https://fiu.setu.co/consents/webview/60c76fa3-601c-4b9d-ad30-d33c0ebcacf3",
  "status": "PENDING",
  "Detail": {
    //consent details object
  }
}

Consent Manager screens are used by your customer to approve the consent request. They will be either asked to login, or register with Setu using their mobile number. Setu creates a unique account aggregator handle for every registered customer.

Before

Consent Manager URL is always

https://anumati.setu.co/(consentHandleInResponse)?redirect_url=(yourRedirectURL). Quick definitions—

  • consentHandleInResponse—This is the ConsentHandle that was received in the response to Create consent request API.

  • yourRedirectURL—This will be used to pass control back to your app from consent manager and will redirect your customer to this provided URL.

The following steps are handled by Setu's screens—

  • Login with PIN or mobile number
  • Setu authenticates customer and displays the data request
  • Customer reviews the request and links data
  • Setu validates and saves consent
  • Setu sends notification to you to confirm consent approval

  • Once the customer approves the consent request, Setu generates the digitally signed consent artefact that you can fetch.

Test this flow as FIU developer

Only for testing this flow, replace the placeholders in the consent manager URL— https://anumati.setu.co/(consentHandleInResponse)?redirect_url= (yourRedirectURL). Visit the URL to approve consent.

This URL is optional when testing as an FIU developer.

Example—If ConsentHandle in the response is XXX-YYY-XXX-ZZZ, your consent manager URL will be https://anumati.setu.co/XXX-YYY-XXX-ZZZ

Use 123456 as OTP in Setu Anumati wherever prompted.

Now

On redirecting your users to url, it opens up a Consent Manager 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 users mobile number

  • Setu authenticates customer 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, status of consent is APPROVED or REJECTED

Use Setu FIP and get access to mock financial data on staging

Test this flow as FIU developer

Only for testing this flow, replace the placeholders in the consent manager URL— https://(fiu-base-url)/consents/webview/(id)?redirect_url=(yourRedirectURL). Visit the URL to approve consent.

This URL is optional when testing as an FIU developer.

Before

Check consent request status

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

If the consent is approved, the ConsentStatus in the response will be READY.

Once consent is approved, Setu AA will notify you on the same by sending a request to the notification endpoint you entered on the Bridge.

Request
GET /Consent/handle/{:id}
Response
{
  "ver": "1.0",
  "timestamp": "2018-12-06T11:39:57.153Z",
  "txnid": "795038d3-86fb-4d3a-a681-2d39e8f4fc3c",
  "ConsentHandle": "a4adbbe-29ae-11e8-a8d7-0289437bf331",
  "ConsentStatus": {
    "id": "654024c8-29c8-11e8-8868-0289437bf331",
    "status": "READY"
  }
}

Fetch signed consent

Call this API to get a signed consent request by passing its unique id.

Request
GET /Consent/{:id}
Response
{
  "ver": "1.0",
  "txnid": "0b811819-9044-4856-b0ee-8c88035f8858",
  "consentId": "XXXX-XXXX-XXXX-XXXX",
  "status": "ACTIVE",
  "createTimestamp": "2018-12-06T11:39:57.153Z",
  "signedConsent": "longkey",
  "ConsentUse": {
    "logUri": "string",
    "count": 1,
    "lastUseDateTime": "2018-12-06T11:39:57.153Z"
  }
}

Now

Both Check Consent request status and

Fetch signed consent APIs are clubbed into one API.

Call this API to get 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": "ac4f8df2-d00c-47c0-bff3-54cdc894c6fb",
    "url": "https://fiu.setu.co/consents/webview/ac4f8df2-d00c-47c0-bff3-54cdc894c6fb",
    "status": "ACTIVE",
    "Detail": {
       //consent details object
}
}

On this page

Create Consent APIBeforeNowConsent Review by customerBeforeNowGet Consent Status APIBeforeNow