This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.
Retrieving Account Information
- Former user (Deleted)
- Former user (Deleted)
Follow the steps below to access the PSU's account and transaction data:
Generating an application access token
When invoking APIs in the CBPII flow, application access tokens must be generated using the client credential grant type.
Generate the client assertion by signing the following JSON payload using the supported algorithms:
{ "alg": "<<This will be the algorithm used for signing>>", "kid": "<<This will be the certificate fingerprint>>", "typ": "JWT" } { "iss": "<<This is the issue of the token, e.g., client ID of your application>>", "sub": "<<This is the subject identifier of the issuer, e.g., client ID of your application>>", "exp": <<This is epoch time of the token expiration date/time>>, "iat": <<This is epoch time of the token issuance date/time>>, "jti": "<<This is an incremental unique value>>", "aud": "<<This is the audience that the ID token is intended for, e.g., https://<<AM_HOST>>:8243/token>>" } <signature>Run the following cURL command in a command prompt to generate the access token. Make sure you update the placeholders with the relevant values:
curl -v POST -H "Content-Type: application/x-www-form-urlencoded;charset=ISO-8859-1" -k -d "grant_type=client_credentials&scope=accounts&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<<pass the signed key generated in the above>>&redirect_uri=<<The callback URL of your application>>" https://<<AM_HOST>>:8243/token
The access token is generated.
You can use the same cURL command to re-generate the access token.
Initiating account consents
The TPP passes the customer-provided consents to the bank. The bank will validate the request and store the user consents.
Navigate to the API Store as a TPP user.
Click APIs.
Select the AccountAndTransactionAPI API.
Click the POST/account-request resource, if you have subscribed to v1.1 or v2.0. Click the POST /account-access-consent resource, if you have subscribed to v3.0.
Use the following as the body:
{ "Data": { "Permissions": [ "ReadTransactionsCredits", "ReadTransactionsDetail" ], "ExpirationDateTime": "<<The request call expiry date and time in ISO 8601>>", "TransactionFromDateTime": "<<The date and time from which the account and transaction data should be retrieved in ISO 8601>>", "TransactionToDateTime": "<<The date and time until which the account and transaction data should be retrieved in ISO 8601>>" }, "Risk": {} }Enter a unique ID that identifies the ASPSP in the x-fapi-financial-id field.
In the Authorization field, enter the application access token you created above. User the
Bearer:<< access token>>format.- Click Try it out!. The API response will bear the
AccountRequestId.
Authorizing account consents
The TPP redirects the bank customer to authenticate and approve/deny application-provided consents on behalf of the bank customer.
Generate the request object by signing the following JSON payload using the supported algorithms as a TPP user.
{ "alg": "<<This will be the algorithm used for signing>>", "kid": "<<This will be the certificate fingerprint>>", "typ": "JWT" } Body { "aud": "<<This is the audience that the ID token is intended for, e.g., https://<<AM_HOST>>:8243/token>>", "iss": "<<This is the issue of the token, e.g., client ID of your application>>", "response_type": "<<This can be code or code id_token>>", "client_id": "<<This is the client ID of your application>>", "redirect_uri": "<<This is the callback URL we set during application access token generation. Ref: Generate Application Access Token section>", "scope": "accounts openid", "nonce": "<<This is a value used to prevent replay attacks>>", "max_age": 86400, "claims": { "userinfo": { "openbanking_intent_id": { "value": "<<This is the AccountRequestId retrieved in Invoke the AccountAndTransactionAPI API section>>", "essential": true } }, "id_token": { "openbanking_intent_id": { "value": "<<This is the AccountRequestId retrieved in Invoke the AccountAndTransactionAPI API section>>", "essential": true }, "acr": { "essential": true, "values": [ "urn:openbanking:psd2:sca", "urn:openbanking:psd2:ca" ] } } } } <signature>For a response type, use the values based on their purpose:
code: Retrieves authorize code
code id_token: Retrieves authorize token and ID token
Run the following in a browser to prompt the invocation of the /authorize API. Make sure you update the placeholders with the relevant values:
https://<<AM_HOST>>:8243/authorize/?response_type=code%20id_token&client_id=<<the client-id of your application>>&scope=accounts openid&redirect_uri=<<The Callback URL of your application>>&prompt=login&request=<<The request object generated in the step above>>
- Once you pass this call, you are directed to a login page. Log in with the credentials of a user that has a subscriber role.
If a secondary factor is required, e.g. SMSOTP, provide the relevant values.
Upon successful authentication, the user is redirected to the consent management page.
- Upon providing consent, an authorization code is generated.
Generating a user access token
In this section, you will be generating an access token using the authorization code generated in the Invoke the /authorize API section above.
Run the following cURL command in a command prompt to generate the access token as a TPP user:
curl -v POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=authorization_code&code=<<Authorization code we generated in the Invoke the /authorize API section>>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<<Client assertion generated in step 2 of the Generate Application Access Token section>>&redirect_uri=<<The Callback URL of your application>>" https://<<AM_HOST>:8243/token
An access token and refresh token are generated.
You can renew the access token using the refresh token. To renew an access token, see Renew Access Token.
- Remain in the API Store.
Retrieving the Accounts and Transaction APIs
In this section, the TPP invokes the actual Accounts APIs. From the bank side, it is validated whether the TPP sends the Accounts API request based on approved consents by the bank customer.
- Accounts
- Transactions
- Beneficiaries
- Balances
- Direct-debits
- Standing-orders
- Products
- Offers
- Party
- Scheduled payments
- Statements
Accounts
The following endpoints exist for the resource:
Resource | HTTP Operation | Endpoint | Mandatory/Optional | Scope | Grant Type | Idempotency Key | Parameters |
|---|---|---|---|---|---|---|---|
| accounts | GET | GET /accounts | Mandatory | accounts | Authorization Code | No | Pagination |
| accounts | GET | GET /accounts/{AccountId} | Mandatory | accounts | Authorization Code | No |
GET /accounts
The first step for an AISP after an account-request is authorised, is to call the GET /accounts endpoint. An AISP will be given the full list of accounts (the AccountIds) that the PSU has authorised the AISP to access. The AccountId(s) returned may then be used to retrieve other resources for a specific AccountId. The selection of authorised accounts happens only at the ASPSP's interface.
Examples
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts'
GET /accounts/{AccountId}
An AISP may retrieve the account information resources for the AccountId (which is retrieved in the call to GET /accounts).
Examples
Use the user access token generated in the step above to invoke the APIs, as shown below:
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>'
- Bulk accounts - detail permission
- Specific account - detail permission
- Bulk accounts - basic permission
Bulk accounts - detail permission
The call to GET /accounts is the first step after an account-request is authorised. This allows the AISP to discover which accounts (and AccountId values) are associated with the authorisation of consent.
In this scenario,
- AccountId 22289 has a building society roll number; and AccountId 31820 does not.
- The ReadAccountsDetail permission has been granted.
Specific account - detail permission
An AISP may also retrieve the account resource details specifically for AccountId 22289. The ReadAccountsDetail permission has been granted.
The ReadAccountsBasic permission has been granted.
Balances
The following endpoints exist for the resource:
Resource | HTTP Operation | Endpoint | Mandatory/Optional | Scope | Grant Type | Idempotency Key | Parameters |
|---|---|---|---|---|---|---|---|
| balances | GET | GET /accounts/{AccountId}/balances | Mandatory | accounts | Authorization Code | No | |
| balances | GET | GET /balances | Optional | accounts | Authorization Code | No | Pagination |
GET /accounts/{AccountId}/balances
An AISP may retrieve the account balance information resource for a specific AccountId (this is retrieved in the call to GET /accounts).
Examples
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/balances'
GET /balances
If an ASPSP has implemented the bulk retrieval endpoints, an AISP may optionally retrieve the account information resources in bulk. This will retrieve the resources for all authorised accounts linked to the account-request.
Examples
Use the user access token generated in the step above to invoke the APIs, as shown below:
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/balances'
Specific account balances
Bulk balances
Transactions
The following endpoints exist for the resource:
HTTP Operation | HTTP Operation | Endpoint | Mandatory/Optional | Scope | Grant Type | Idempotency Key | Parameters |
|---|---|---|---|---|---|---|---|
| transactions | GET | GET /accounts/{AccountId}/transactions | Mandatory | accounts | Authorization Code | No | Pagination Filtering |
| transactions | GET | GET /transactions | Optional | accounts | Authorization Code | No | Pagination Filtering |
GET /accounts/{AccountId}/transactions
GET /transactions
If an ASPSP has implemented the bulk retrieval endpoints, an AISP may optionally retrieve the transactions in bulk. This will retrieve the resources for all authorised accounts linked to the account-request.
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/transactions'
Examples
Use the user access token generated in the step above to invoke the APIs, as shown below:
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/transactions'
Specific account transactions
Bulk transactions
None of the transactions included in the payload are e-commerce transactions, so MerchantDetails are not included in the examples.
No access to transactions
In this example, the AISP does not have access to call the transactions endpoint. This will result in a 403 error.
Beneficiaries
The following endpoints exist for the resource:
Resource | HTTP Operation | Endpoint | Mandatory/Optional | Scope | Grant Type | Idempotency Key | Parameters |
|---|---|---|---|---|---|---|---|
| beneficiaries | GET | GET /accounts/{AccountId}/beneficiaries | Conditional | accounts | Authorization Code | No | |
| beneficiaries | GET | GET /beneficiaries | Optional | accounts | Authorization Code | No | Pagination |
GET /accounts/{AccountId}/beneficiaries
An AISP may retrieve the account beneficiaries information resource for a specific AccountId (this is retrieved in the call to GET /accounts).
GET /beneficiaries
If an ASPSP has implemented the bulk retrieval endpoints for beneficiaries, an AISP may optionally retrieve the beneficiaries' information in bulk. This endpoint will retrieve the beneficiaries' resources for all authorised accounts linked to a specific account-request.
Examples
Use the user access token generated in the step above to invoke the APIs, as shown below:
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/beneficiaries'
Specific account beneficiaries
Bulk beneficiaries
Direct-debits
The following endpoints exist for the resource:
Resource | HTTP Operation | Endpoint | Mandatory? | Scope | Grant Type | Idempotency Key | Parameters |
|---|---|---|---|---|---|---|---|
| direct-debits | GET | GET /accounts/{AccountId}/direct-debits | Conditional | accounts | Authorization Code | No | |
| direct-debits | GET | GET /direct-debits | Optional | accounts | Authorization Code | No | Pagination |
GET /accounts/{AccountId}/direct-debits
An ASPSP must provide this endpoint for AISPs to retrieve the direct-debits for a specific account identified by the AccountId.
GET /direct-debits
An ASPSP may provide this endpoint for AISPs to retrieve direct-debits for all accounts that the PSU has consented to. This will retrieve the direct-debit resources for all authorised accounts linked to the account-request.
Examples
Use the user access token generated in the step above to invoke the APIs, as shown below:
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/direct-debits'
Specific account direct-debits
Bulk account direct-debits
Standing-orders
The following endpoints exist for the resource:
Endpoints for the resource and available methods.
Resource | HTTP Operation | Endpoint | Mandatory/Optional | Scope | Grant Type | Idempotency Key | Parameters |
|---|---|---|---|---|---|---|---|
| standing-orders | GET | GET /accounts/{AccountId}/standing-orders | Conditional | accounts | Authorization Code | No | |
| standing-orders | GET | GET /standing-orders | Optional | accounts | Authorization Code | No | Pagination |
GET /accounts/{AccountId}/standing-orders
An AISP may retrieve the standing-order resource for a specific AccountId (this is retrieved in the call to GET /accounts).
GET /standing-orders
If an ASPSP has implemented the bulk retrieval endpoints, an AISP may optionally retrieve the standing-order resources in bulk.
This will retrieve the resources for all authorised accounts linked to the account-request.
Examples
Use the user access token generated in the step above to invoke the APIs, as shown below:
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/standing-orders'
Specific account standing-orders
Bulk accounts standing-orders
GET /standing-orders HTTP/1.1Authorization: Bearer Az90SAOJklae x-fapi-financial-id: OB/2017/001 x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 GMT x-fapi-customer-ip-address: 104.25.212.99 x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d Accept: application/json
Products
Resource | HTTP Operation | Endpoint | Mandatory/Optional | Scope | Grant Type | Idempotency Key | Parameters |
|---|---|---|---|---|---|---|---|
| products | GET | GET /accounts/{AccountId}/product | Conditional | accounts | Authorization Code | No | |
| products | GET | GET /products | Optional | accounts | Authorization Code | No | Pagination |
GET /accounts/{AccountId}/product
GET /products
If an ASPSP has implemented the bulk retrieval endpoints for products, an AISP may optionally retrieve the products information in bulk. This endpoint will retrieve the products resources for all authorised accounts linked to a specific account-request.
Examples
Use the user access token generated in the step above to invoke the APIs, as shown below:
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/product'
Specific account product information
Bulk accounts product information
Supported API callsAll account balances
In addition to the above API calls, the v2.0 and v3.0 API versions support the following API calls.
- All offers
- Account-specific offers
- All account owner/party details
- Account-specific account owner/party details
- All scheduled payment details
- Account-specific scheduled payment details
- All account statements
- All account-specific details
- File-based account-specific statement
- Account-specific statement transactions
All offers
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/offers'
Account-specific offers
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/offers'
All account owner/party details
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/party'
Account-specific account owner/party details
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/party'
All scheduled payment details
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/scheduled-payments'
Account-specific scheduled payment details
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/scheduled-payments'
All account statements
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/statements'
All account-specific details
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/statements'
File-based account-specific statement
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/statements/<<StatementId>>/file'
Account-specific statement transactions
curl -X GET --header 'Accept: application/json' --header 'x-fapi-financial-id: OB/2017/001' --header 'Authorization: Bearer <<access token>>' 'https://<<AM_HOST>>:8243/open-banking/<<version>>/aisp/accounts/<<AccountRequestId>>/statements/<<StatementId>>/transactions
Renewing the access token
Since access tokens have an expiration period, once an access token expires, you need to regenerate it. Let's regenerate the access token that was generated using the authorization code in the section above.
Run the following cURL command to call the refresh_token endpoint and regenerate a new access token as a TPP user:
curl -v POST -H "Content-Type: application/x-www-form-urlencoded;charset=UTF-8" -k -d "grant_type=refresh_token&refresh_token=<<refresh token token>>&scope=accounts openid&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<<Client assertion generated in step 2 of the Generate User Access Token section>>&redirect_uri=<<The Callback URL of your application>>" https://<<AM_HOST>>:8243/token/