Introduction

Consent is the core of the open banking system and is crucial to maintain regulatory standards, and improving privacy and data security. Singleview Open Banking API provides the users with the ability to securely access their banking information as well as control the sharing of the data by managing their consent as per the regulatory standards.

User consent is captured at the bank by sending a request to access the specific user's account information.

🚧
Important information
A bank account with no user consent or expired user consent cannot be accessed through the AIS services as per the regulatory standards.

Singleview Open Banking API's consent management feature allows the Payment Service Users (PSUs) to:

Header - Authentication requirements

Every request needs to include the mentioned header information. The header details are crucial to authenticate the request and processing it successfully. Below is the data that is required to be sent in the header of all the requests involved in managing the consent.

JSON Tag	Description	Data type
`clientId` Mandatory	Registered Client Identification	String
`clientCode` Mandatory	Client Secret Code	String
`Signature` Mandatory	64-Bit signature code developed by processing Signature Key through SHA 256 Algorithm	String
`sid` Mandatory	Unique identification for an authorized session	String
`Authorization: Bearer` Mandatory	Unique identification bearer token obtained upon a successful login	String

Manage consents for AIS

Add consent

PSUs can generate new consents by sending a request to the banks through the TSP. The consent generated authorizes Singleview Open Banking API platform to enable AIS and retrieve account information for the specific corresponding bank account. A user can access multiple bank accounts of a bank through a registered and linked consent or can create individual consent to access individual bank accounts.

1852 — Singleview Open Banking - Representation of process to create an AIS consent

Endpoint details:

Endpoint	Method	Grant type	Scope
`/v1/api/openBanking/createConsent`	POST	The header should include: 1. `clientId` 2. `clientCode` 3. `signature` 4. `sid` 5. `Authorization: Bearer`	Posting a request to create a new or expired consent

Request to create consent

{
    "SVConsentRequest": {
        "DateTimeStamp": "2022-06-06T17:51:03",
        "RequestID": "{{RequestID}}",
        "userName": "{{userName}}",
        "SVConsentInfoMessage": [
            {
                "SVConsentInfoRequest": {
                    "BankCode": "SAMA",
                    "Data": {
                        "Permissions": [
                            "ReadAccountsBasic",
                            "ReadAccountsDetail",
                            "ReadBalances",
                            "ReadBeneficiariesBasic",
                            "ReadBeneficiariesDetail",
                            "ReadDirectDebits",
                            "ReadTransactionsBasic",
                            "ReadTransactionsCredits",
                            "ReadTransactionsDebits",
                            "ReadTransactionsDetail",
                            "ReadProducts",
                            "ReadStandingOrdersDetail",
                            "ReadProducts",
                            "ReadStandingOrdersDetail",
                            "ReadStatementsDetail",
                            "ReadParty",
                            "ReadPartyPSU"
                        ],
                        "ExpirationDateTime": "2022-09-26T11:54:15.922Z",
                        "TransactionFromDateTime": "2022-09-26T11:54:15.922Z",
                        "TransactionToDateTime": "2022-10-26T11:54:15.922Z"
                    },
                    "Risk": {}
                }
            }
        ]
    }
}

Description:

JSON Tag	Description	Data type
SVConsentRequest Mandatory	Create consent request tag	Object
DateTimeStamp Mandatory	Stamp denoting the request date and time	String
RequestID Mandatory	Unique request identification	String
userName Mandatory	Client Username	String
SVConsentInfoMessage Mandatory	Consent information message tag	Object
SVConsentInfoRequest Mandatory	Consent information request tag	Object
BankCode Mandatory	Unique bank code for identification	String
Data Mandatory	Data tag representing the data included in the request	Object
Permissions Mandatory	List of permissions requested through the consent `ReadAccountsBasic` `ReadAccountsDetail` `ReadBalances` `ReadBeneficiariesBasic` `ReadBeneficiariesDetail` `ReadDirectDebits` `ReadTransactionsBasic` `ReadTransactionsCredits` `ReadTransactionsDebits` `ReadTransactionsDetail` `ReadProducts` `ReadStandingOrdersDetail` `ReadProducts` `ReadStandingOrdersDetail` `ReadStatementsDetail` `ReadParty` `ReadPartyPSU`	Array
ExpirationDateTime Mandatory	Consent expiry date and time	String
TransactionFromDateTime Mandatory	Initial date & time for the allotted transaction access period	String
TransactionToDateTime Mandatory	Final date & time for the allotted transaction access period	String
Risk Mandatory	Risk description & disclaimer	String

Successful consent creation response

{
    "success": true,
    "message": "",
    "SVConsentResponse": {
        "SVConsentInfoMessage": [
            {
                "SVConsentInfoResponse": {
                    "Data": {
                        "Permissions": [
                            "ReadAccountsBasic",
                            "ReadAccountsDetail",
                            "ReadBalances",
                            "ReadBeneficiariesBasic",
                            "ReadBeneficiariesDetail",
                            "ReadDirectDebits",
                            "ReadTransactionsBasic",
                            "ReadTransactionsCredits",
                            "ReadTransactionsDebits",
                            "ReadTransactionsDetail",
                            "ReadProducts",
                            "ReadStandingOrdersDetail",
                            "ReadProducts",
                            "ReadStandingOrdersDetail",
                            "ReadStatementsDetail",
                            "ReadParty",
                            "ReadPartyPSU"
                        ],
                        "ExpirationDateTime": "2022-09-26T11:54:15.922Z",
                        "TransactionFromDateTime": "2022-09-26T11:54:15.922Z",
                        "TransactionToDateTime": "2022-10-26T11:54:15.922Z",
                        "ConsentId": "aac-b9a73147-7a1d-4ec9-bbbe-c8db6e21d65c",
                        "Status": "AwaitingAuthorisation",
                        "CreationDateTime": "2022-07-18T09:40:01.107Z",
                        "StatusUpdateDateTime": "2022-07-18T09:40:01.107Z",
                        "consentId": "aac-b9a73147-7a1d-4ec9-bbbe-c8db6e21d65c"
                    },
                    "Risk": {},
                    "Links": {
                        "Self": "https://rs1.lab.openbanking.sa/open-banking/v3.1/aisp/account-access-consents/aac-b9a73147-7a1d-4ec9-bbbe-c8db6e21d65c"
                    },
                    "Meta": {},
                    "BankCode": "SAMA",
                    "scope": "openid accounts",
                    "state": "c3c6770e-7800-49b2-a7ad-426e46c45ea7",
                    "bankRedirectURL": "https://auth1.lab.openbanking.sa/auth?client_id=9f97a211-6f57-4239-bbe4-2b4654ba6af6&response_type=code&scope=openid%20accounts&request=eyJhbGciOiJub25lIn0.eyJhdWQiOiJodHRwczovL2F1dGgxLmxhYi5vcGVuYmFua2luZy5zYSIsImV4cCI6MTY1ODEzNzgwMywiaXNzIjoiOWY5N2EyMTEtNmY1Ny00MjM5LWJiZTQtMmI0NjU0YmE2YWY2Iiwic2NvcGUiOiJvcGVuaWQgYWNjb3VudHMiLCJyZWRpcmVjdF91cmkiOiJodHRwczovL3VhdC5vbmVzaW5nbGV2aWV3LmNvbS9vcGVuYmFua2luZy9hdXRob3Jpc2UvVTBGTlFRPT0iLCJyZXNwb25zZV90eXBlIjoiY29kZSIsImNsaWVudF9pZCI6IjlmOTdhMjExLTZmNTctNDIzOS1iYmU0LTJiNDY1NGJhNmFmNiIsIm5vbmNlIjoiMjI2OTI4MjUtYjZiZC00M2FiLTgyYTItYWZhNjc4ZmIwY2QyIiwic3RhdGUiOiJjM2M2NzcwZS03ODAwLTQ5YjItYTdhZC00MjZlNDZjNDVlYTciLCJuYmYiOjE2NTgxMzYzMDMsImxvZ2luX2hpbnQiOiJyYXN0YW1hbiIsImNsYWltcyI6eyJpZF90b2tlbiI6eyJvcGVuYmFua2luZ19pbnRlbnRfaWQiOnsidmFsdWUiOiJhYWMtYjlhNzMxNDctN2ExZC00ZWM5LWJiYmUtYzhkYjZlMjFkNjVjIiwiZXNzZW50aWFsIjp0cnVlfX19LCJyZXNwb25zZVR5cGUiOiJjb2RlIn0.",
                    "Token": "1c240123-f41e-4e65-a55a-2b4f6a20cbc6"
                }
            }
        ]
    }
}

Description:

JSON Tag	Description
success	Process success status represented as `True` or `False`
message	Process execution message
SVConsentResponse	Create consent response tag
SVConsentInfoMessage	Consent information message tag
SVConsentInfoResponse	Consent information response Tag
Data	Data tag for account information
Permissions	List of permissions provided in the consent
ExpirationDateTime	Date and time for consent expiry
TransactionFromDateTime	Initial date & time for the allotted transaction access period
TransactionToDateTime	Final date & time for the allotted transaction access period
ConsentId	Unique consent identification
Status	Status of consent processing
CreationDateTime	Date and time of representing the creation of consent
StatusUpdateDateTime	Most recent time and date representing latest consent update
Risk	Risk description and disclaimer
Links	Redirect links
Self	Own link/url details
Meta	Meta tag
BankCode	Unique bank code for identification
scope	Scope details
state	Unique state identification
bankRedirectURL	Bank redirect url for reflecting the results
Token	Unique token identification

Delete Consent

If a PSU/User wants to revoke the account access authority then it is required to delete the existing active consent. This can be done by sending a request to delete the concerned consent and disable AIS services for that particular account.

1750 — Singleview Open Banking - Representation of process to delete an AIS consent

Endpoint details:

Endpoint	Method	Grant type	Scope
`/v1/api/openBanking/deleteConsent`	POST	The header should include: 1. `clientId` 2. `clientCode` 3. `signature` 4. `sid` 5. `Authorization: Bearer`	Posting a request to delete an existing and active consent

Request to delete consent

{
  "SVConsentsDeleteRequest": {
    "DateTimeStamp": "2022-03-29T17:51:03",
    "RequestID": "{{RequestID}}",
    "userName": "{{userName}}",
    "SVConsentsDeleteMessage": [
      {
        "SVConsentDeleteRequest": {
          "BankCode": "SAMA",
          "ConsentId": "{{ConsentId}}"
        }
      }
    ]
  }
}

Description:

JSON Tag	Description	Data type
SVConsentsDeleteRequest Mandatory	Delete consent request tag	Object
DateTimeStamp Mandatory	Stamp denoting the request date and time	String
RequestID Mandatory	Unique request identification	String
userName Mandatory	Client Username	String
SVConsentsDeleteMessage Mandatory	Delete consents message tag	Array
SVConsentsDeleteRequest Mandatory	Request tag with the information to delete a specific consent	Object
BankCode Mandatory	Unique bank code for identification	String
ConsentId Mandatory	Unique consent identification	String

Successfully consent deleted response

{
    "success": "true",
    "message": "",
    "SVConsentsDeleteResponse": {
        "SVConsentsDeleteMessage": [
            {
                "SVConsentDeleteResponse": {
                    "BankCode": "SAMA",
                    "ConsentId": "aac-b9a73147-7a1d-4ec9-bbbe-c8db6e21d65c",
                    "success": true,
                    "message": "Successfully delete consent",
                    "status": "success"
                }
            }
        ]
    }
}

Description:

JSON Tag	Description
success	Request processing success status represented as `True` or `False`
message	Process execution message
SVConsentsDeleteResponse	Delete consents response tag
SVConsentsDeleteMessage	Deleted consent message tag
SVConsentDeleteResponse	Deleted consent individual details response tag
BankCode	Unique bank code for identification
ConsentId	Unique consent identification
success	Individual consent deleting status represented as `True` or `False`
message	Individual consent deleting process message
status	Individual consent deleting process status

View Consent

A PSU/User can check their consent details by sending a request to view the concerned consent by providing the corresponding Consent IDs.

Endpoint details:

Endpoint	Method	Grant type	Scope
`/v1/api/openBanking/consentDetails`	POST	The header should include: 1. `clientId` 2. `clientCode` 3. `signature` 4. `sid` 5. `Authorization: Bearer`	Posting a request to view the details of a particular consent using Consent ID

Request to view consent details

{
  "SVConsentDetailsRequest": {
    "DateTimeStamp": "2022-05-27T17:51:03",
    "RequestID": "{{RequestID}}",
    "userName": "{{userName}}",
    "SVConsentDetailsMessage": [
      {
        "SVConsentDetailRequest": {
          "BankCode": "SAMA",
          "ConsentId": "{{ConsentId}}"
        }
      }
    ]
  }
}

Description:

JSON Tag	Description	Data type
SVConsentDetailsRequest Mandatory	View consent details request tag	Object
DateTimeStamp Mandatory	Stamp denoting the request time and date	String
RequestID Mandatory	Unique request identification	String
userName Mandatory	Client Username	String
SVConsentDetailsMessage Mandatory	View consents details request message tag	Object
SVConsentDetailRequest Mandatory	Individual consent details tag	Object
BankCode Mandatory	Unique bank code for identification	String
ConsentId Mandatory	Unique consent identification	String

Successful view consent response

{
    "success": true,
    "message": "",
    "SVConsentDetailsResponse": {
        "SVConsentDetailsMessage": [
            {
                "SVConsentDetailResponse": {
                    "Data": {
                        "Permissions": [
                            "ReadAccountsBasic",
                            "ReadAccountsDetail",
                            "ReadBalances",
                            "ReadBeneficiariesBasic",
                            "ReadBeneficiariesDetail",
                            "ReadDirectDebits",
                            "ReadTransactionsBasic",
                            "ReadTransactionsCredits",
                            "ReadTransactionsDebits",
                            "ReadTransactionsDetail",
                            "ReadProducts",
                            "ReadStandingOrdersDetail",
                            "ReadProducts",
                            "ReadStandingOrdersDetail",
                            "ReadStatementsDetail",
                            "ReadParty",
                            "ReadPartyPSU"
                        ],
                        "ExpirationDateTime": "2022-09-26T11:54:15.922Z",
                        "TransactionFromDateTime": "2022-09-26T11:54:15.922Z",
                        "TransactionToDateTime": "2022-10-26T11:54:15.922Z",
                        "ConsentId": "aac-b9a73147-7a1d-4ec9-bbbe-c8db6e21d65c",
                        "Status": "Authorised",
                        "CreationDateTime": "2022-07-18T09:40:01.107Z",
                        "StatusUpdateDateTime": "2022-07-18T09:40:32.889Z"
                    },
                    "Risk": {},
                    "Links": {
                        "Self": "https://rs1.lab.openbanking.sa/open-banking/v3.1/aisp/account-access-consents/aac-b9a73147-7a1d-4ec9-bbbe-c8db6e21d65c"
                    },
                    "Meta": {},
                    "BankCode": "SAMA"
                }
            }
        ]
    }
}

Description:

JSON Tag	Description
success	Process success status represented as `True` or `False`
message	Process execution message
SVConsentDetailsResponse	View consent details response tag
SVConsentDetailsMessage	View consent details message tag
SVConsentDetailResponse	View individual consent response tag
Data	Data tag for account information
Permissions	List of permissions provided in the consent
ExpirationDateTime	Date and time for consent expiry
TransactionFromDateTime	Initial date & time for the allotted transaction access period
TransactionToDateTime	Final date & time for the allotted transaction access period
ConsentId	Unique consent identification
Status	Status of consent processing
CreationDateTime	Date and time of representing the creation of consent
StatusUpdateDateTime	Most recent time and date representing latest consent update
Risk	Risk description and disclaimer
Links	Redirect links
Self	Own link/url details
Meta	Meta tag
BankCode	Unique bank code for identification

Refresh Consent

The aim of this request is to refresh account consent before it is expired by passing the consent id as an input parameter.

Endpoint details:

Endpoint	Method	Grant type	Scope
`/v1/api/openBanking/refreshConsent`	POST	The header should include: 1. `clientId` 2. `clientCode` 3. `signature` 4. `sid` 5. `Authorization: Bearer`	Posting a request to refresh/renew a consent using Consent ID

Request to refresh consent

{
                    "SVConsentsRefreshRequest": {
                      "DateTimeStamp": "2022-03-29T17:51:03",
                      "RequestID": "SDFSDFF23424234244",
                      "userName": "tatanew",
                      "SVConsentsRefreshMessage": [
                        {
                          "SVConsentRefreshRequest": {
                            "BankCode": "ANB",
                            "ConsentId": "0bf9c24f-a24a-48b1-9e87-18b5b4da9dd7"
                          }
                        },
                        {
                          "SVConsentRefreshRequest": {
                            "BankCode": "ALRAJHI",
                            "ConsentId": "7341a6ae-c3df-46c6-8588-7ecb805aa51c"
                          }
                        }
                      ]
                    }
                  }

Description:

JSON Tag	Description	Data type
SVConsentsRefreshRequest Mandatory	Consent refresh request tag	Object
DateTimeStamp Mandatory	Stamp denoting the request date and time	String
RequestID Mandatory	Unique request identification	String
userName Mandatory	Client Username	String
SVConsentsRefreshMessage Mandatory	Consents refresh message tag	Object
SVConsentRefreshRequest Mandatory	Individual consent details to refresh request tag	Object
BankCode Mandatory	Unique bank code for identification	String
ConsentId Mandatory	Unique consent identification	String

Successful refresh consent response

{
                    "success": true,
                    "message": "",
                    "SVConsentsRefreshResponse": {
                        "SVConsentsRefreshMessage": [
                            {
                                "SVConsentRefreshResponse": {
                                    "BankCode": "ANB",
                                    "ConsentId": "0bf9c24f-a24a-48b1-9e87-18b5b4da9dd7",
                                }
                            },
                            {
                                "SVConsentRefreshResponse": {
                                    "BankCode": "ALRAJHI",
                                    "status": "FAILURE",
                                    "message": "Access Denied"
                                }
                            }
                        ]
                    }
                  }

Description:

JSON Tag	Description
success	Process success status represented as `True` or `False`
message	Process execution message
SVConsentsRefreshResponse	Refresh consents response tag
SVConsentsRefreshMessage	Refresh consents message tag
SVConsentRefreshResponse	Specific consent refresh response tag
BankCode	Unique bank code for identification
ConsentId	Unique consent identification
status	Individual consent refresh process message
message	Individual consent refresh process status