FIP API Specification

Last updated 4 months ago

Was this helpful?

This API enables an AA to discover accounts belonging to a customer based on the customer identifiers. A list of masked account information and corresponding linkRefNumber for each discovered account is returned based on the identifier matching logic at FIP.

Note: "Request Body Example Value" and "Responses Example Value" given below is for illustrative purposes only.

post

/Accounts/discover

Authorizations

Header parameters

aa_api_keyanyrequired

aa_api_key is provided to FIP by the AA

x-jws-signatureanyrequired

Detached JWS of the body

x-request-metaanyrequired

It is the Base64 encoded JSON object having the identifier of the receiver (recipient-id) to whom the API call needs to be forwarded. Ex: x-request-meta: [Base64 of {"recipient-id": "SIMULATOR"}] i.e x-request-meta: eyJyZWNpcGllbnQtaWQiOiAiU0lNVUxBVE9SIn0K

Body

FITypesstring · enum[]required

List of financial information types.

verstringrequired

API version.

timestampstring · date-timerequired

Request creation timestamp.

txnidstringrequired

Unique transaction identifier used for providing an end to end traceability.

Customerobjectrequired

This block would contain the information about the customer including the identifiers & the customer address at the AA

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.sandbox.sahamati.org.in/router/v2/Accounts/discover' \
  --header 'aa_api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "FITypes": [
      "DEPOSIT"
    ],
    "ver": "2.0.0",
    "timestamp": "2023-06-26T06:41:54.904+0000",
    "txnid": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
    "Customer": {
      "id": "customer_identifier@AA_identifier",
      "Identifiers": [
        {
          "category": "STRONG",
          "type": "AADHAAR",
          "value": "XXXXXXXXXXXXXXXX"
        }
      ]
    }
  }'

200

400

401

404

409

412

500

501

503

{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T11:39:57.153Z",
  "txnid": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
  "DiscoveredAccounts": [
    {
      "FIType": "DEPOSIT",
      "accType": "SAVINGS",
      "accRefNumber": "BANK11111111",
      "maskedAccNumber": "XXXXXXX3468"
    }
  ]
}

This API will be used for initiating an account link request to link selected account/s with the AA customer address. Note: "Request Body Example Value" and "Responses Example Value" given below is for illustrative purposes only.

post

/Accounts/link

Authorizations

Header parameters

aa_api_keyanyrequired

aa_api_key is provided to FIP by the AA

x-jws-signatureanyrequired

Detached JWS of the body

x-request-metaanyrequired

Body

verstringrequired

API version

timestampstring · date-timerequired

Current Timestamp

txnidstringrequired

Unique transaction identifier used for providing an end to end traceability.

Customerobjectrequired

Customer identifiers including AA virtual address.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.sandbox.sahamati.org.in/router/v2/Accounts/link' \
  --header 'aa_api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "ver": "2.0.0",
    "timestamp": "2023-06-26T17:51:18.412Z",
    "txnid": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
    "Customer": {
      "id": "customer_identifier@AA_identifier",
      "Accounts": [
        {
          "FIType": "DEPOSIT",
          "accType": "SAVINGS",
          "accRefNumber": "BANK11111111",
          "maskedAccNumber": "XXXXXXX3468"
        }
      ]
    }
  }'

200

400

401

404

409

412

500

501

503

{
  "AuthenticatorType": "TOKEN",
  "RefNumber": "f6b1482e-8f08-11e8-862a-02552b0d3c36",
  "ver": "2.0.0",
  "timestamp": "2023-06-26T06:13:30.967+0000",
  "txnid": "f35761ac-4a18-11e8-96ff-0277a9fbfedc"
}

This API will be used to delete a previously established account link to the user's profile. Once deleted, the financial information can not be retrieved for that account through Account Aggregator.

Note: "Request Body Example Value" and "Responses Example Value" given below is for illustrative purposes only.

post

/Accounts/delink

Authorizations

Header parameters

aa_api_keyanyrequired

aa_api_key is provided to FIP by the AA

x-jws-signatureanyrequired

Detached JWS of the body

x-request-metaanyrequired

Body

verstringrequired

API version

timestampstring · date-timerequired

Creation timestamp of the message.

txnidstringrequired

Unique transaction identifier used for providing an end to end traceability.

Accountobjectrequired

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.sandbox.sahamati.org.in/router/v2/Accounts/delink' \
  --header 'aa_api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "ver": "2.0.0",
    "timestamp": "2023-06-26T17:51:18.412Z",
    "txnid": "f35761ac-4a18-11e8-96ff-0277a9fbfedc",
    "Account": {
      "customerAddress": "customer_address@aa_identifier",
      "linkRefNumber": "xxxxxxxxxxxxx"
    }
  }'

200

400

401

404

409

412

500

501

503

{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T10:27:17.699+0000",
  "txnid": "410c2d2e-4a1e-11e8-960e-0277a9fbfedc",
  "AccLinkDetails": {
    "customerAddress": "customer_address@aa_identifier",
    "linkRefNumber": "xxxxxxxxxxxxx",
    "status": "DELINKED"
  }
}

This API is used to submit the token/OTP(received from the customer) back to FIP so that account linkage can be completed. It is used only in case of token-based authentication for linking accounts. Note: "Request Body Example Value" and "Responses Example Value" given below is for illustrative purposes only.

post

/Accounts/link/verify

Authorizations

Header parameters

aa_api_keyanyrequired

aa_api_key is provided to FIP by the AA

x-jws-signatureanyrequired

Detached JWS of the body

x-request-metaanyrequired

Body

verstringrequired

API version

timestampstring · date-timerequired

Creation timestamp of the message.

txnidstringrequired

Unique transaction identifier used for providing an end to end traceability.

refNumberstringrequired

Temporary reference number generated by FIP for account linking request

tokenstringrequired

The token that was sent to the customer by the FIP to confirm account link activity

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.sandbox.sahamati.org.in/router/v2/Accounts/link/verify' \
  --header 'aa_api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "ver": "2.0.0",
    "timestamp": "2023-06-26T10:27:17.699+0000",
    "txnid": "410c2d2e-4a1e-11e8-960e-0277a9fbfedc",
    "refNumber": "f6b1482e-8f08-11e8-862a-02552b0d3c36",
    "token": 999999
  }'

200

400

401

404

409

412

500

501

503

{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T10:27:17.699+0000",
  "txnid": "410c2d2e-4a1e-11e8-960e-0277a9fbfedc",
  "AccLinkDetails": [
    {
      "customerAddress": "customer_address@aa_identifier",
      "linkRefNumber": "xxxxxxxxxxxxx",
      "accRefNumber": "XXXXXXXXXXXX",
      "status": "LINKED"
    }
  ]
}

This API is used by the AA to request for financial information from the FIP. The FIP will validate the request against the signed consent and return a sessionID which can then be used by the AA to fetch the required data.

Note: "Request Body Example Value" and "Responses Example Value" given below is for illustrative purposes only.

post

/FI/request

Authorizations

Header parameters

aa_api_keyanyrequired

aa_api_key is provided to FIP by the AA

x-jws-signatureanyrequired

Detached JWS of the body

x-request-metaanyrequired

Body

KeyMaterialobjectrequired

Contains the cryptographic parameters that are required to perform End-to-End encryption for sharing the financial information between the producer and the consumer in a secure manner. Please refer this link for more information: https://tools.ietf.org/html/rfc4492

verstringrequired

API version

timestampstring · date-timerequired

Creation timestamp of the message.

txnidstringrequired

Unique transaction identifier used for providing an end to end traceability.

Consentobjectrequired

Consent Artefact details.

FIDataRangeobjectrequired

Specifies the date time range for which the financial information is requested

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.sandbox.sahamati.org.in/router/v2/FI/request' \
  --header 'aa_api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "KeyMaterial": {
      "Nonce": "29512b70-ca84-46b5-9471-63765599cf15",
      "cryptoAlg": "ECDH",
      "curve": "Curve25519",
      "params": "cipher=AES/GCM/NoPadding;KeyPairGenerator=ECDH",
      "DHPublicKey": {
        "Parameters": "text",
        "KeyValue": "text",
        "expiry": "2019-06-01T09:58:50.505Z"
      }
    },
    "ver": "2.0.0",
    "timestamp": "2023-06-26T09:58:50.505Z",
    "txnid": "c4a1450c-d08a-45b4-a475-0468bd10e380",
    "Consent": {
      "digitalSignature": "NdjwMjLortTb10dxcJezkvdOxPVvEdZvIqwqVWOHnE8pS_YDswcRPLTRmds2xO-Tvm_A2cFv1qKYpaZnv8Bl6xmZoOsG_F8_40gRZqIhz5hF9puzp8lEEhMlZ6NaX2Y2OYkwHcOBBpCIXpLXB4CMWiefUEWjO9zKDd5JJwZ4vLWeT4qgwvPfRqE60B33tzVlF5E6OA2mKK17sGRXsfrI9obEjL52RMdGo_9bv1HnHfvPlbj5ihj6d_5iTtoh7HUC_X8CrJGvkgkCjP_7of1jPb5QgJ9nx_Yfsxj3vf8zEseZIVISjF3MwBzW7Di4CpfQl4wlnpkQO9MKu78F69Z9Ig",
      "id": "654024c8-29c8-11e8-8868-0289437bf331"
    },
    "FIDataRange": {
      "from": "2018-11-27T06:26:29.761Z",
      "to": "2018-12-27T06:26:29.761Z"
    }
  }'

200

400

401

403

404

409

412

500

501

503

{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T10:05:50.505Z",
  "txnid": "c4a1450c-d08a-45b4-a475-0468bd10e380",
  "consentId": "654024c8-29c8-11e8-8868-0289437bf331",
  "sessionId": "caa2f259-2dc2-4075-87aa-6d81018b6183"
}

This API is used to fetch financial information from FIP once AA recieves the data ready notification.

Note: "Request Body Example Value" and "Responses Example Value" given below is for illustrative purposes only.

post

/FI/fetch

Authorizations

Header parameters

aa_api_keyanyrequired

aa_api_key is provided to FIP by the AA

x-jws-signatureanyrequired

Detached JWS of the body

x-request-metaanyrequired

Body

verstringrequired

API version

timestampstring · date-timerequired

Creation timestamp of the message.

txnidstringrequired

Unique transaction identifier used for providing an end to end traceability.

sessionIdstringrequired

A session ID is a base-64 encoded UUID number that FIP returns to the AA for each financial information access request.

fipIdstring

FIP ID as defined in the Account Aggregator Ecosystem.

linkRefNumberobject[]

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.sandbox.sahamati.org.in/router/v2/FI/fetch' \
  --header 'aa_api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "ver": "2.0.0",
    "timestamp": "2023-06-26T06:41:34.904+0000",
    "txnid": "af5b8023-aabc-4a46-8f37-d3c167129b1e",
    "sessionId": "caa2f259-2dc2-4075-87aa-6d81018b6183",
    "fipId": "FIP-1",
    "linkRefNumber": [
      {
        "id": "XXXX-XXXX-XXXX"
      }
    ]
  }'

200

400

401

403

404

409

412

500

501

503

{
  "ver": "2.0.0",
  "timestamp": "2023-06-26T06:41:54.904+0000",
  "txnid": "af5b8023-aabc-4a46-8f37-d3c167129b1e",
  "FI": [
    {
      "KeyMaterial": {
        "Nonce": "29512b70-ca84-46b5-9471-63765599cf15",
        "cryptoAlg": "ECDH",
        "curve": "Curve25519",
        "params": "cipher=AES/GCM/NoPadding;KeyPairGenerator=ECDH",
        "DHPublicKey": {
          "Parameters": "text",
          "KeyValue": "text",
          "expiry": "2019-06-01T09:58:50.505Z"
        }
      },
      "fipID": "FIP-1",
      "data": [
        {
          "encryptedFI": "text",
          "linkRefNumber": "XXXX-XXXX-XXXX",
          "maskedAccNumber": "XXXXXXXX4020"
        }
      ]
    }
  ]
}

This API is intended to be used by AA to notify the change in consent status due to the consent management operations performed by the customer. For more details about consent notification flow, please refer FAQ section. Note: "Request Body Example Value" and "Responses Example Value" given below is for illustrative purposes only.

post

/Consent/Notification

Authorizations

Header parameters

aa_api_keyanyrequired

aa_api_key is provided to FIP by the AA

x-jws-signatureanyrequired

Detached JWS of the body

x-request-metaanyrequired

Body

verstringrequired

API version

timestampstring · date-timerequired

Creation timestamp of the message.

txnidstringrequired

The unique transaction identifier used for providing an end to end traceability.

Notifierobjectrequired

Information about the notifier

ConsentStatusNotificationobjectrequired

Contains the Consent ID and Consent Status details.

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.sandbox.sahamati.org.in/router/v2/Consent/Notification' \
  --header 'aa_api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "ver": "2.0.0",
    "timestamp": "2023-06-26T11:39:57.153Z",
    "txnid": "0b811819-9044-4856-b0ee-8c88035f8858",
    "Notifier": {
      "type": "AA",
      "id": "AA_1"
    },
    "ConsentStatusNotification": {
      "consentId": "XXXX0-XXXX-XXXX",
      "consentStatus": "REVOKED"
    }
  }'

200

400

401

404

409

412

500

501

503

{
  "response": "OK",
  "ver": "2.0.0",
  "timestamp": "2023-06-26T06:13:30.967+0000",
  "txnid": "f35761ac-4a18-11e8-96ff-0277a9fbfedc"
}

This API will be used by the AA to send the consent artefact to the FIP on creation.

Note: "Request Body Example Value" and "Responses Example Value" given below is for illustrative purposes only.

post

/Consent

Authorizations

Header parameters

aa_api_keyanyrequired

aa_api_key is provided to FIP by the AA

x-jws-signatureanyrequired

Detached JWS of the body

x-request-metaanyrequired

Body

statusstring · enumrequired

Specifies the status of consent artefact

Options: ACTIVE, PAUSED, REVOKED, EXPIRED

signedConsentstringrequired

Consent artefact signed using JWS. See SignedConsentDetail model for consent format.

verstringrequired

API version

txnidstringrequired

The unique transaction identifier used for providing an end to end traceability.

consentIdstringrequired

Unique ID generated by AA after consent approval is given by the customer.

createTimestampstring · date-timerequired

Creation time of the Consent Artefact

ConsentUseobjectrequired

Section defining the parameters for consent tracking

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.sandbox.sahamati.org.in/router/v2/Consent' \
  --header 'aa_api_key: YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
    "status": "ACTIVE",
    "signedConsent": "eyJhbGciOiJSUzI1NiIsImtpZCI6IjQyNzE5MTNlLTdiOTMtNDlkZC05OTQ5LTFjNzZmZjVmYzVjZiIsImI2NCI6ZmFsc2UsImNyaXQiOlsiYjY0Il19.ew0KICAgICAgICAiY29uc2VudFN0YXJ0IjogIjIwMTktMDUtMjhUMTE6Mzg6MjAuMzgwKzAwMDAiLA0KICAgICAgICAiY29uc2VudEV4cGlyeSI6ICIyMDIwLTA1LTI4VDExOjM4OjIwLjM4MSswMDAwIiwNCiAgICAgICAgImNvbnNlbnRNb2RlIjogIlZJRVciLA0KICAgICAgICAiZmV0Y2hUeXBlIjogIk9ORVRJTUUiLA0KICAgICAgICAiY29uc2VudFR5cGVzIjogWw0KICAgICAgICAgICAgIlBST0ZJTEUiLA0KICAgICAgICAgICAgIlNVTU1BUlkiLA0KICAgICAgICAgICAgIlRSQU5TQUNUSU9OUyINCiAgICAgICAgXSwNCiAgICAgICAgImZpVHlwZXMiOiBbDQogICAgICAgICAgICAiREVQT1NJVCIsDQogICAgICAgICAgICAiVEVSTS1ERVBPU0lUIg0KICAgICAgICBdLA0KICAgICAgICAiRGF0YUNvbnN1bWVyIjogew0KICAgICAgICAgICAgImlkIjogImNvb2tpZWphci1hYUBmaW52dS5pbiIsDQogICAgICAgICAgICAidHlwZSI6ICJBQSINCiAgICAgICAgfSwNCiAgICAgICAgIkRhdGFQcm92aWRlciI6IHsNCiAgICAgICAgICAgICJpZCI6ICJCQVJCMEtJTVhYWCIsDQogICAgICAgICAgICAidHlwZSI6ICJGSVAiDQogICAgICAgIH0sDQogICAgICAgICJDdXN0b21lciI6IHsNCiAgICAgICAgICAgICJpZCI6ICJkZW1vQGZpbnZ1Ig0KICAgICAgICB9LA0KICAgICAgICAiQWNjb3VudHMiOiBbDQogICAgICAgICAgICB7DQogICAgICAgICAgICAgICAgImZpVHlwZSI6ICJERVBPU0lUIiwNCiAgICAgICAgICAgICAgICAiZmlwSWQiOiAiQkFSQjBLSU1YWFgiLA0KICAgICAgICAgICAgICAgICJhY2NUeXBlIjogIlNBVklOR1MiLA0KICAgICAgICAgICAgICAgICJsaW5rUmVmTnVtYmVyIjogIlVCSTQ4NTk2NDU3OSIsDQogICAgICAgICAgICAgICAgIm1hc2tlZEFjY051bWJlciI6ICJVQkk4NTIxNzg4MTI3OSINCiAgICAgICAgICAgIH0sDQogICAgICAgICAgICB7DQogICAgICAgICAgICAgICAgImZpVHlwZSI6ICJERVBPU0lUIiwNCiAgICAgICAgICAgICAgICAiZmlwSWQiOiAiQkFSQjBLSU1YWFgiLA0KICAgICAgICAgICAgICAgICJhY2NUeXBlIjogIlNBVklOR1MiLA0KICAgICAgICAgICAgICAgICJsaW5rUmVmTnVtYmVyIjogIlVCSTQ4NTk2NDUiLA0KICAgICAgICAgICAgICAgICJtYXNrZWRBY2NOdW1iZXIiOiAiVUJJODUyMTc4ODEyIg0KICAgICAgICAgICAgfQ0KICAgICAgICBdLA0KICAgICAgICAiUHVycG9zZSI6IHsNCiAgICAgICAgICAgICJjb2RlIjogIjEwMSIsDQogICAgICAgICAgICAicmVmVXJpIjogImh0dHBzOi8vYXBpLnJlYml0Lm9yZy5pbi9hYS9wdXJwb3NlLzEwMS54bWwiLA0KICAgICAgICAgICAgInRleHQiOiAiV2VhbHRoIG1hbmFnZW1lbnQgc2VydmljZSIsDQogICAgICAgICAgICAiQ2F0ZWdvcnkiOiB7DQogICAgICAgICAgICAgICAgInR5cGUiOiAicHVycG9zZUNhdGVnb3J5VHlwZSINCiAgICAgICAgICAgIH0NCiAgICAgICAgfSwNCiAgICAgICAgIkZJRGF0YVJhbmdlIjogew0KICAgICAgICAgICAgImZyb20iOiAiMjAxOS0wNS0yOFQxMTozODoyMC4zODMrMDAwMCIsDQogICAgICAgICAgICAidG8iOiAiMjAyMC0wNS0yOFQxMTozODoyMC4zODErMDAwMCINCiAgICAgICAgfSwNCiAgICAgICAgIkRhdGFMaWZlIjogew0KICAgICAgICAgICAgInVuaXQiOiAiTU9OVEgiLA0KICAgICAgICAgICAgInZhbHVlIjogNA0KICAgICAgICB9LA0KICAgICAgICAiRnJlcXVlbmN5Ijogew0KICAgICAgICAgICAgInVuaXQiOiAiSE9VUiIsDQogICAgICAgICAgICAidmFsdWUiOiA0DQogICAgICAgIH0sDQogICAgICAgICJEYXRhRmlsdGVyIjogWw0KICAgICAgICAgICAgew0KICAgICAgICAgICAgICAgICJ0eXBlIjogIlRSQU5TQUNUSU9OQU1PVU5UIiwNCiAgICAgICAgICAgICAgICAib3BlcmF0b3IiOiAiPiIsDQogICAgICAgICAgICAgICAgInZhbHVlIjogIjIwMDAwIg0KICAgICAgICAgICAgfQ0KICAgICAgICBdDQogICAgfQ.O3KPh-eTpW2w47QXYidOBe1Hk2y7djVAEcOnZyRRvxQ3cY18-9ZWiodF16jff-e7yNQgsYZpAy95Fx2Fft8LoYugkYh9_6qHiG_7LCtW8Ng4nCMgZM3Wwsj11ks1msrK5C1ksPrGlTkFhm9-FufNkPTAlW76_5Sb8G_lOsIj1lB8TrvKpOvPlhEIgsS4WBNdPfv3SBqTV2suw2LvkX3QTilqwuMgXMkrm9-RYL90fweX_yyoyaBWHOJNQaKNuQWPpoRRNHGOx3v4_QiwgrELdfeTVtKn6R_AsfaBoEthQ3wrc8tY1q0Wx5j0x18NdU2R2C26dHyZ9M11dEH99psA1A",
    "ver": "2.0.0",
    "txnid": "0b811819-9044-4856-b0ee-8c88035f8858",
    "consentId": "XXXX-XXXX-XXXX-XXXX",
    "createTimestamp": "2023-06-26T11:39:57.153Z",
    "ConsentUse": {
      "logUri": "text",
      "count": 1,
      "lastUseDateTime": "2018-12-06T11:39:57.153Z"
    }
  }'

200

400

401

404

409

412

500

501

503

{
  "response": "OK",
  "ver": "2.0.0",
  "timestamp": "2023-06-26T06:13:30.967+0000",
  "txnid": "f35761ac-4a18-11e8-96ff-0277a9fbfedc"
}

This API can be used by the AAs to check availability of the FIP application.

Note: "Request Body Example Value" and "Responses Example Value" given below is for illustrative purposes only.

get

/Heartbeat

Authorizations

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.sandbox.sahamati.org.in/router/v2/Heartbeat' \
  --header 'aa_api_key: YOUR_API_KEY'

200

400

401

404

500

501

503

{
  "Status": "UP",
  "ver": "2.0.0",
  "timestamp": "2023-06-26T06:54:54.435Z"
}