Data flow

Below is a summary of the APIs you need to use to fetch FI data. These APIs are to be used only once your customer has approved consent request. The flow mainly involves data fetching against a valid data session with below APIs.

Create Data Session—Call this API against an APPROVED consent. This initiates data preparation at user's linked FIP accounts. You will be notified by Setu once the data is ready to be fetched.
Fetch FI data—Fetch decrypted FI data with data session id.

Create new Data Session API

Call this API to create a data session against the approved consentId.

Request

Specify the format in which you wish to receive the decrypted financial data, this can be xml or json.

Make sure that values of dataRange array in the body, matches or is within the FIDataRange specified in the Create consent request API.

POST /sessions
{
    "consentId": "d4f40bd9-a22f-4408-a622-4e8a1e4fbda6",
    "dataRange": {
        "from": "2016-12-06T11:39:57.153Z",
        "to": "2021-12-31T14:25:33.440Z"
    },
    "format": "json"
}

SUCCESS

Response

This initiates a data session with a id, that uniquely identifies this data request. Setu will also notify you when the FIP is ready to share the data you requested and you can use the id to fetch the data with the next API.

{
    "format": "json",
    "fips": null,
    "dataRange": {
        "to": "2021-06-30T16:30:16.363Z",
        "from": "2021-05-30T11:39:57.154Z"
    },
    "id": "f608b1c5-60cb-445d-8355-76a9cc053535",
    "status": "PENDING",
    "consentId": "c8b03bc3-6b6c-45e2-a604-6f7ec4541e57",
    "traceId": "1-646c4a4c-34b8663b0f1238aa04412e89"
}

FAIL

Response

{
  "errorMsg": "string",
  "errorCode": "string",
  "txnid": "string",
  "timestamp": "2023-03-30T08:20:31.367Z",
  "ver": "string"
}

Error codes

A mapping of error codes and messages

Status codes	Error codes	Error messages
404	`NotFound`	Consent not found
400	`Invalid request`	Invalid request body
500	`InternalServerError`	An internal server error has occurred, please try again in some time. You can report this to aa@setu.co

Fetch FI data

For each data session created, Setu will notify you on the webhook endpoint configured by you, as and when each FIP in the data session responds with an update. See FI notifications.

When the combined data session status in the notification is either PARTIAL or COMPLETED, you can fetch FI data with this API.

Request

If you request for multiple FI types, you will receive all the FI data from end-user's linked accounts in an array.

GET /sessions/:id

Response

SUCCESS

Response

The response comes with two statuses—

Individual account FI status
Combined data session status

Individual account FI status	Explanation
`PENDING`	FIP has received the account data request
`READY`	FIP is ready with the requested account data
`DELIVERED`	FIP has delivered the requested account data
`TIMEOUT`	The account data request to the FIP has timed out
`DENIED`	FIP has denied sharing the requested account data

Combined data session status	Individual account FI status
`PENDING`	Individual account FI status of all accounts in the data session are in `PENDING` status. Data fetch for this data session was not supposed to be initiated.
`PARTIAL`	One or more accounts have individual FI account status as `READY` but the remaining have status as `PENDING`/`FAILED`/`TIMEOUT`. Only data from accounts with status as `READY` was fetched.
`COMPLETED`	Individual account FI status of all accounts is `READY` and data from all accounts was fetched.
`EXPIRED`	Data session has expired, irrespective of individual account FI statuses. No further fetches can happen for this data session.
`FAILED`	Data session has failed, irrespective of individual account FI statuses. Retry by creating a new data session.

The payload contains Profile, Summary and Transactions as requested in Create consent request.

{
  "status": "PARTIAL", // combined data session status
  "format": "json",
  "fips": [
    {
      "accounts": [
        {
          "linkRefNumber": "b2329f47-0a6f-4131-adb5-9ef7b4c1ca6a",
          "maskedAccNumber": "XXXXXX4373",
          "status": "DELIVERED" // individual account FI status
          "data": {
            "account": {
              "linkedAccRef": "b2329f47-0a6f-4131-adb5-9ef7b4c1ca6a",
              "maskedAccNumber": "XXXXXX4373",
              "type": "deposit",
              "version": "1.1",
              "profile": {
                "holders": {
                  "type": "SINGLE",
                  "holder": {
                    "address": "8/1190, 5th Cross, 3rd Main, 7th Block, Jayanagar, Bangalore - 560011",
                    "ckycCompliance": "true",
                    "dob": "1947-08-15",
                    "email": "mail@mail.com",
                    "landline": "",
                    "mobile": "8569884373",
                    "name": "Akshay Kumar",
                    "nominee": "REGISTERED",
                    "pan": "AAAAA0000A"
                  }
                }
              },
              "summary": {
                "currentBalance": "101666.33",
                "currency": "INR",
                "branch": "Jayanagar 4th Block",
                "balanceDateTime": "2020-06-22T07:50:00+00:00",
                "currentODLimit": "0",
                "drawingLimit": "0",
                "exchgeRate": " ",
                "facility": "OD",
                "ifscCode": "ICIC0001124",
                "micrCode": "500240246",
                "openingDate": "2004-08-06",
                "status": "ACTIVE",
                "type": "SAVINGS",
                "Pending": {
                  "transactionType": "DEBIT",
                  "amount": "0"
                }
              },
              "transactions": {
                "startDate": "2021-04-01",
                "endDate": "2021-09-30"
              }
            }
          },
        }
      ],
      "fipID": "Setu-FIP"
    },
    {
      "accounts": [
        {
          "linkRefNumber": "b2329f47-0a6f-4131-adb5-9ef7b4c1ca6a",
          "maskedAccNumber": "XXXXXX4373",
          "FIstatus": "FAILED",  // individual account FI status
          "data": null
        }
      ],
      "fipID": "ACME-FIP"
    }
  ],
  "id": "378ec65c-f558-49fc-89ea-e880c2cf88b3",
  "dataRange": {
    "from": "2021-04-01T00:00Z",
    "to": "2021-09-30T00:00Z"
  },
  "consentId": "d4f40bd9-a22f-4408-a622-4e8a1e4fbda6"
}

FAIL

Response

{
  "errorMsg": "string",
  "errorCode": "string",
  "txnid": "string",
  "timestamp": "2023-03-30T08:20:31.367Z",
  "ver": "string"
}

Error codes

A mapping of error codes and messages

Status codes	Error codes	Error messages
404	`NotFound`	Consent not found
400	`Invalid request`	Invalid request body
500	`InternalServerError`	An internal server error has occurred, please try again in some time. You can report this to aa@setu.co

Auto-Fetch data feature

As seen above, once a consent is approved, FIUs need to create a data session, listen to notifications and then fetch FI data.

Auto-Fetch data feature aims to absorb this complexity from the FIUs. With Auto-Fetch data feature enabled, the process will look like this—

Consent is approved by the customer.
Setu creates a data session automatically.
Setu continuously monitors data availability through notifications and periodic checks:
- Listens to FI notifications from AA
- Performs periodic data fetches in case notifications are delayed or missed
As soon as data becomes available, Setu fetches and sends it to the FIU.
- For one time consents, Auto-Fetch executes only once, right after the consent is approved.
- For recurring consents, Auto-Fetch can fetch data periodically. Set up the frequency of Auto-Fetch data in your configuration on the Bridge.

Auto-Fetch can be set up on Bridge, under Step 1 of your product configuration.

When Auto-Fetch is enabled, it will automatically fetch data for all approved consents and you will be automatically charged for successful fetches.

Auto fetch notification payload

SUCCESS

POST /your-webhook-endpoint
{
  "type": "FI_DATA_READY",
  "consentId": "58180119-15bc-454f-83bb-192efda9321b",
  "status": "COMPLETED", // Can be PENDING/PARTIAL/COMPLETED
  "dataRange": {
    "from": "2023-07-25T11:27:01.069Z",
    "to": "2023-07-25T11:28:00.648Z"
  },
  "fiData": [
    {
      "fipID": "setu-fip",
      "data": [
        {
          "linkRefNumber": "4b4cc8fb-89eb-41c3-bc64-fec2497d5454",
          "maskedAccNumber": "XXXXXXXX7561",
          "decryptedFI": {
            "account": {
              "linkedAccRef": "4b4cc8fb-89eb-41c3-bc64-fec2497d5454",
              "maskedAccNumber": "XXXXXXXX7561",
              "type": "deposit",
              "version": "1.1",
              "profile": {
                "holders": {
                  "type": "SINGLE",
                  "holder": [
                    {
                      "address": "758, Das Nagar Bikaner 455148",
                      "ckycCompliance": "false",
                      "dob": "1983-09-08",
                      "email": "buchzain@setu-dummy.com",
                      "mobile": "3536459776",
                      "name": "Tushar Balakrishnan",
                      "nominee": "REGISTERED",
                      "pan": "SMPXE2207K"
                    }
                  ]
                }
              },
              "transactions": {
                "startDate": "2020-04-01T00:00:00.000Z",
                "endDate": "2023-01-01T00:00:00.000Z",
                "transaction": [
                  {
                    "amount": "33834.65",
                    "currentBalance": "489971.1",
                    "mode": "UPI",
                    "narration": "UPI/CR/457233689286/Gatik Yohannan/CZBR/64321752",
                    "reference": "966712146",
                    "transactionTimestamp": "2020-05-08T11:05:29+00:00",
                    "txnId": "EUCE23840883221703",
                    "type": "CREDIT",
                    "valueDate": "2020-05-09T11:05:29+00:00"
                  },
                  {
                    "amount": "16480.04",
                    "currentBalance": "408905.24",
                    "mode": "UPI",
                    "narration": "UPI/CR/988357930370/Dhruv Desai/RZJF/85716960",
                    "reference": "510260839",
                    "transactionTimestamp": "2020-12-16T21:49:14+00:00",
                    "txnId": "ZJGE96715479740775",
                    "type": "CREDIT",
                    "valueDate": "2020-12-17T21:49:14+00:00"
                  }
                  //more transactions
                ]
              }
            }
          }
        }
      ]
    }
  ]
}

FAIL

POST /your-webhook-endpoint
{
    "type": "FI_DATA_FAILED",
    "timestamp": "2023-08-28T17:12:51.521Z",
    "consentId": "af43608a-ed6e-4c65-9745-0386ba5fd91b",
    "success": true,
    "data": null,
    "error": {
        "code": "InvalidConsentUse",
        "message": "Consent fetch frequency exceeded"
    }
}

Error codes

A mapping of error codes and messages

Error codes	Error messages
`InvalidConsentUse`	Consent fetch frequency exceeded
`InvalidConsentStatus`	Consent for which data fetch has been requested has expired
`SessionExpired`	Session to fetch data for a session ID has expired
`ConsentRevoked`	Consent for which data fetch has been requested has been revoked
`UpstreamServerDown`	Received 500 from upstream AA
`DataFetchFailure`	Failed to fetch data after multiple retry attempts due to upstream errors

Response

Response

Error codes

Response

Response

Error codes

Error codes

On this page