In this step, the TPP registers its TPP application in WSO2 API store.
Click here to see how it is done...
Navigate to the API Store at https://<WSO2_OB_APIM_HOST>:9443/store.
SelectSign-up that is on the top left corner of the homepage.
Provide the requested details on the Sign Up page.
Click here for more information..
a. Generic details:
Field
Description
Username/Email
The username/email that the TPP uses to sign in to the API Store.
Password
The password that the TPP uses to sign in to the API Store.
Retype Password
This is to prevent the TPP from accidentally setting an incorrect password.
Last Name
This is the last name of the TPP.
First Name
This is the first name of the TPP.
b. Company details:
Field
Description
Legal Entity Name
The official name of the TPP.
Country of Registration
The country in which the TPP is registered.
Legal Identifier Number (LEI)
This identifies the TPP.
Company Register
The organization that registered the TPP.
Company Registration Number
Identifier issued at the TPP registration.
Address Line 1
Address of the TPP.
Address Line 2
Address of the TPP.
City
City in which the TPP is located.
Postal Code
Postal code of the geographical location of the TPP.
Country
The country in which the TPP is located.
c. Competent authority registration details:
Field
Description
Competent Authority
The regulatory body that authorises and supervises the open banking services delivered by the TPP.
Competent Authority Country
Country of the competent authority that authorised the TPP to provide open banking services.
Competent Authority Registration Number
The registration number issued by the Competent Authority to the TPP.
URL of the Competent Authority Register Page
URL of the page that has the list of organizations authorised by the competent authority.
Open Banking Roles
Captures the open banking roles the TPP is willing to take up:
Account Information Service Provider: An Account Information Service Provider (AISP) provides an aggregated view of all the accounts and past transactions that a customer has with different banks. To provide this view to the customer, the AISP should have authorisation from the customer to view the corresponding transaction and balance information of all the accounts. The AISPs can also provide the facility to analyze the customer's spending patterns, expenses, and financial needs. Unlike a PISP, an AISP cannot transfer funds from a account.
Initiation Service Provider: A Initiation Service Provider (PISP) initiates credit transfers on behalf of a bank's customer.
After selecting the TPP, indicate whether the TPP is authorised by a competent authority to provide the services of the selected roles.
If the TPP is not yet registered to provide the services of the selected roles, indicate whether the TPP has applied for registration or not.
Read terms and conditions. Click the checkbox to agree to the terms and conditions.
Click Sign Up. A request to approve the TPP sign up is now sent to the Approver users.
Step 2 - Approve the TPP
Now that you have signed up as a TPP, an admin who overlooks all TPP sign-up forms must approve it.
It is not mandatory to include the approval step for approving the TPP. In order to add this step, you need to configure workflows in the WSO2 Open Banking solution. For more information on configuring workflows, see .
Click here to see how it is done...
Sign in to the WSO2 Open Banking API Manager Admin portal as an Approver at https://<WSO2_OB_APIM_HOST>:9443/admin.
Locate the approval request and click Assign To Me.
Click Start to start the approval process.
Select Approve then Complete.
Now the TPP can sign in to the API store.
Step 3 - Sign in to the API store as the TPP
Users can sign in to the API store and proceed with the steps mentioned below.
Click here to see how it is done...
Sign in to the API Store as the TPP at https://<WSO2_OB_APIM_HOST>:9443/store.
Click Sign In and navigate to the Sign In page.
Enter the username and the password you entered when signing up as a TPP.
Click Sign In.
The homepage of the API store is now displayed along with the APIs.
Step 4 - Create an application
The TPP needs to create an application in WSO2 API store that represents its TPP application. The application created via WSO2 API store allows to observe statistics of APIs, subscribe to APIs, and generate keys for the subscribed APIs.
Click here to see how it is done...
In the API store, click Applications.
Click AddApplication.
Enter application details.
Field
Description
Name
Application name.
Per Token Quota
Determines the maximum number of API requests accepted within a given duration.
Description
This describes the purpose of the application.
Click Add.
An application can be used to subscribe to multiple APIs. See for the instructions.
Step 5 - Subscribe to API
The TPP user needs to subscribe to the NextGenPSD2XS2AFramework - 1.3.3 API in order to access API resources. Once subscribed to the NextGenPSD2XS2AFramework - 1.3.3 API, the users are subscribing to all the supported services of Accounts, Payments and Confirmation of Funds API resources.
Click here to see how it is done...
In the API store, Click APIs.
Select the NextGenPSD2XS2AFramework-1.3.3 API.
In the right top corner, select the application you created from the dropdown list under Applications.
Set the Tiers to Unlimited.
Click Subscribe.
Now that you have subscribed to the API, you can generate keys and invoke the API.
Step 6 - Upload certificates to the client trust stores
Step 7 - Generate keys
The TPP user requests client ID and client secret to access the subscribed APIs.
Click here to see how it is done...
Sign in to the API store as the TPP user and click either of the following on the Applications tab.
Production Keys: Generates access tokens in the production environment.
Sandbox Keys: Generates access tokens in the sandbox environment.
Provide the requested information as defined below:
Field
Description
Grant Types
These determine the credentials that are used to generate the access token.
Refresh Token: This is to renew an expired access token.
Client Credential: This relates to the client credentials grant type and is applicable when consuming the API as an application.
Code: This relates to the authorisation code grant type and is applicable when consuming the API as a user.
Client ID
OrganizationIdentifier as provided in the EIDAS certificate. The organizationIdentifier attribute contains information using the following structure in the presented order:
PSD as the 3-character legal person identity type reference;
2-character ISO 3166 country code representing the NCA country;
hyphen-minus (-)
2-8 character NCA identifier (A-Z upper case only, no separator)
hyphen-minus (-)
PSP (Payment Service Provider) identifier (authorisation number as specified by NCA)
Callback URL
This is the URL used by the Account Information Service Provider (AISP) / Payment Initiation Service Provider (PISP) to receive the authorisation code sent from the Account Servicing Payment Service Provider (ASPSP), e.g: bank. The authorisation code can be used later to generate an OAuth2 access token.
Application Certificate
According to the Berlin specification, the TPPs require to upload eIDAS (electronic identification and trust services) certificate when generating the keys. If you do not have an eIDAS certificate, you can create an X.509 certificate to generate the keys.
Click here to see how it is done...
A keystore file is used to store the trusted certificates of the TPP in the WSO2 Open Banking solution. Use the commands given below in a command-line interface in order to create a keystore file as the TPP.
Make sure to update the following placeholders:
<alias>
A preferred alias for the keystore file.
<filename>
A preferred name for the keystore file.
During the command execution, the TPP user requires to;
sourcekeystorePSSet a password for the keystore.
Provide information, acquired when registering with a governing entity.
Set a password for user-defined alias (<alias>).
Convert the keystore from the .jks format to .PKCS12. Make sure to update the following placeholders:
<keyStoreName>
This is the name of the <filename>, given above.
<PKCS12FileName>
This is the name of the keystore in the .PKCS12 format.
During the command execution, the TPP user requires to;
Set a password for the destination keystore.
Enter the source keystore password, as defined in the above step.
Create the application certificate (.pem) file in the PKCS12 format using the keystore. e.g: tpp.p12.
Make sure to update the following placeholders:
<PKCS12FileName>
This is the name of the keystore in the PKCS12 format, as mentioned above for the <PKCS12FileName>.
<PEMFileName>
This is the name of the application certificate that is created in the .pem format.
During the command execution, the TPP user requires to;
Set a password to import the .pem file.
You can now upload the eIDAS certificate or X.509 certificate by clicking Choose Files.
Make sure to add only the content between BEGIN CERTIFICATE and END CERTIFICATE strings from the certificate file.
Click Request Accessif you are generating production keys. If workflows are configured in the solution, it sends a request to Approver user to approve the token generation. Otherwise, it generates consumer key and consumer secret.
Click Generate Keys if you are generating sandbox keys. It generates consumer key and consumer secret.
Now, you have generated the consumer key and consumer secret successfully. Navigate to the first point of Authorization code that appears after the keys on the same page.
This is the URL that the TPP must send to the PSU. This URL points to a web interface with permissions that the TPP is seeking from the PSU. A sample web interface looks as follows:
Step 7 8 - Approve Production Key generation
This step includes instructions to an Approver user to review and approve a request to generate production keys for an application.
It is not mandatory to include the approval step for the Production Key generation. In order to add this step, you need to configure workflows in the WSO2 Open Banking solution. For more information on configuring workflows, see .
Click here to see how it is done...
Sign in to the WSO2 Open Banking API Manager Admin portal as an Approver at https://<WSO2_OB_APIM_HOST>:9443/admin.
Click Tasks and then the Application Registration.
Locate the approval request and click Assign To Me.
Click Start to start the approval process.
Select Approve and then click Complete.
Navigate back to the API Store and clickApplications.
On the Applications tab, Click View of the application that you created.
Click Production Keys tab to find the generated keys.
It includes the consumer key and consumer secret as follows:
Note that consumer key is used as client ID in the below steps.
Step 8 9 - Generate application access token
When invoking APIs, application access tokens must be generated using the client credential grant type. The generated application access token is used to invoke the NextGenPSD2XS2AFramework-1.3.3 API.
Click here to see how it is done...
Generate the client assertion by signing the following JSON payload using the supported algorithms. The supported algorithms are RS256 and PS256.
The value of the aud claim should contain the same value as the Identity Provider Entity ID.
Click here to view the Identity Provider Entity ID:
In the Main menu, go to Home > Identity > Identity Providers > Resident.
View the value in Resident Identity Provider > Inbound Authentication Configuration >OAuth2/OpenID Connect Configuration > Identity Provider Entity ID. By default this value is set to https://localhost:8243/token.
Run the following cURL command in a command prompt to generate the access token. Update the placeholders with the relevant values.
The access token is now generated.
You can use the same cURL command to regenerate the access token.
Step
9
10 - Initiate account consents
In this step, the TPP creates a request to get the consent of the PSU to access the accounts and its information from the bank. The Bank sends the request to the PSU stating the accounts and information that the TPP wishes to access. Upon the user approving or denying the account consent, the TPP is now eligible to access the user's account details.
Expand
title
Click here to see how it is done...
POST / consents - Create consent
First, the TPP must state the accounts and permissions in the account initiation request and send it to the bank. Then, the bank responds with a URL that redirects the PSU to provide the consent for the accounts that the TPP wishes to access. The request and the response are as follows:
Localtabgroup
Localtab
title
Format for the Sample Request
Code Block
title
Sample Request Format
{
"access":{<Includes requested access services>}
"recurringIndicator":"<Indicates whether the consent is for one-time/recurring access to the account data><possible values: false,true>"
"validUntil" :"<A date that the consent is valid upto>"
"frequencyPerDay": "<Defines how many times a cosent can be accessed per day>"
"combinedServiceIndicator":"<Indicates whether the payment initiation request can be accessed in the same session>"
}
{
"consentStatus":"<Authentication status of the user consent>"
"consentId":"<Identification of the consent resource as used in the API structure>"
"scaMethods""<Indicates whether a SCA method is required and a choice between different authentication methods>"
"chosenScaMethod":"<The SCA method. Applicable only if an embeded SCA method>"
"challengeData":"Additional data element to chosenScaMethod, if required"
"links":"<Hyperlinks that can be identified by the TPP>"
"scaOAuth":"<>"
"self":"<>"
"psuMessage":"<A message that can be viewed by the PSU>"
}
Code Block
title
Sample Response
{
"consentStatus":"received",
"consentId":"e41ddeaa-1dac-4071-b605-8c15c32f99cd",
"scaMethods":[
{
"authenticationType":"SMS_OTP",
"authenticationMethodId":"sms-otp",
"name":"sms-otp",
"explanation":"SMS based one time password"
}
],
"chosenScaMethod":{
"authenticationType":"SMS_OTP",
"authenticationMethodId":"sms-otp",
"name":"sms-otp",
"explanation":"SMS based one time password"
},
"_links":{
"scaStatus":{
"href":"/consents/e41ddeaa-1dac-4071-b605-8c15c32f99cd/authorisations/5c41126d-4457-404e-bc9c-63fba7b4c09f"
},
"scaOAuth":{
"href":"https://<WSO2_OB_APIM_HOST>:8243/.well-known/openid-configuration"
},
"self":{
"href":"https://<WSO2_OB_APIM_HOST>:8243/xs2a/1.3.3/consents/e41ddeaa-1dac-4071-b605-8c15c32f99cd"
}
}
}
Tip
Users can call any API resource at any time once the TPP creates a consent, and PSUs grant access to relevant accounts.
Expand
title
Click here to find the consent related API calls that can be invoked at any time...
GET /consents/{consentId} - Get consent request
The TPP can retrieve information of the account initiation request using the following request. It generates a sample response as below:
GET /consents/{consentId}/status - Consent status request
Once the consent is granted by the PSU, the TPP can retrieve the status of the consent using the sample request given below. It generates a sample response as follows:
If the user executes the above-mentioned request, it generates no response.
Step
10
11 - Initiate an authorisation flow for an account consent
Anchor
authorisationStep
authorisationStep
WSO2 Open Banking v1.4.0 for Berlin Implementation supports both implicit and explicit authorization flows for account authorization. In both cases, TPP generates the authorization URL using the well-known configuration that is received from the ASPSP as scaOAuth link in the response.
Implicit authorisation
In this approach, ASPSP creates authorization sub resources after the account consent is received and replies with the well-known configuration of the Key Manager (WSO2_OB_KM) in the links section of the response, generated for the account consent request. Then the TPP generates the authorization URL using the well-known URL. The PSU goes through the authorisation flow with that authorisation URL.
Explicit authorisation
In this approach, the TPP initiates the authorization flow by invoking POST /consents/{consentId}/authorisations API resource. At this point, the ASPSP creates authorization sub resources and reply back with the well-known configuration of the Key Manager (WSO2_OB_KM) in the links section of the response. Then the TPP has to generate the authorization URL using which later the PSU uses to go through the authorization flow.
The TPP invokes POST /consents/{consentId}/authorisations API resource to authorise a particular account.
The TPP generates the authorisation URL using the well-known URL under scaOAuth link in the response.
Expand
title
Click here to see how it is done...
POST /consents/{consentId}/authorisations - Start the authorisation process for a consent
The sample request is shown below using the request body that we used to seek access to PSU's account. In this case, the TPP is creating an authorisation subresource, that the PSU can use to authorise.
Localtabgroup
Localtab
title
Sample Request
Code Block
title
Sample Request Body
{
<!-- This is an empty request body -->
}
Run the following cURL command in a command-line interface to initiate account access consent. Update the placeholders with the relevant values.
Users can call any API resource at any time once the TPP creates a consent, and PSUs grant access to relevant accounts.
Expand
title
Click here to find the consent related API calls that can be invoked at any time...
Following API resources can be followed by the consent authorisation step mentioned here.
GET /consents/{consentId}/authorisations - Get Consent Authorisation Sub-Resources Request
The TPP can use GET /consents/{consentId}/authorisations API resource to retrieve the list of subresource IDs that are created. A sample request and response are given below:
The TPP uses the well-known URL regardless of the authorisation followed (Implicit/Explicit) to authorise an account as below:
Expand
title
Click here to see how it is done...
Anchor
authorisationURL
authorisationURL
The open banking solution sends the authorisation URL that was generated under scaOAuth link of the response. The response the TPP uses differs according to the authorisation as follows:
Implicit authorisation
The response the TPP gets when initiating an account consent.
Explicit authorisation
The response the TPP gets when invoking POST /consents/{consentId}/authorisations API resource.
A sample well-known URL under scaOAuth parameter looks as below:
Use the following table to find the descriptions for the parameters:
Parameter
Description
scope
This is the reference to the consent resource for account access. It is in the form of ais:<consentId>
response_type
code is recommended.
redirect_uri
The TPP's URI that the OAuth2 server redirects the PSU's user agent after the authorisation.
state
Prevents XSRF attacks by TPP setting a dynamic value.
code_challenge_method
Code verifier transformation method. It is recommended in the Berlin specification to use S256.
client_id
As provided in the eIDAS certificate, the organization_Identifier must contain the following information in it: - "PSD" as 3 character legal person identity type reference - 2 character ISO 3166 country code representing the NCA country - hyphen-minus "-" and - 2-8 character NCA identifier (A-Z uppercase only, no separator - hyphen-minus "-" - PSP identifier (authorization number as specified by NCA)
code_challenge
This is used to avoid code injection attacks using the PKCE challenge in the cryptographic RFC 7636. Go to https://tools.ietf.org/html/rfc7636 for more information on the cryptographic RFC 7636.
The authorisation URL points to a web interface as follows:
Upon the user approving or denying the account consent, the user can invoke consent/authorization API resource of the authentication endpoint. By invoking this API resource, the user retrieves the consent approval/denial, that is displayed on the consent web-app.
Use the following cURL command to generate the user access token:
Code Block
curl -v POST -H "Content-Type: application/x-www-form-urlencoded;charset=ISO-8859-1" -k -d "grant_type=authorization_code&scope=accounts+openid&client_assertion_type=<eg:-urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer>&client_assertion=<jwt_key>&redirect_uri=<The callback URL of your application>&code_challenge_method=<code_challenge_method>&code_verifier=<code_verifier>&code=<code>" https://<WSO2_OB_APIM_HOST>:8243/token
Parameters and their descriptions are as follows:
Parameter
Description
grant_type
authorization_code is recommended.
code
Authorisation code from the authorisation response.
scope
The scope of the user access token.
client_assertion_type
jwt-bearer that were sent as parameters in the request when using JWTs for OAuth 2 client authentication and authorization grants. See Generate application access token for more information.
client_assertion
The signed JWT that was sent as parameters in the request when using JWTs for OAuth 2 client authentication and authorization grants. See Generate application access token for more information.
redirect_uri
The TPP's URI that the OAuth2 server redirected the PSU's user agent for a transaction.
code_verifier
This is the code we used to generate the code challenge in the POST /consents/{consentId}/authorisations API call.
The user can retrieve details of an account that consent is already granted by the PSU and stored in the ASPSP system. Use the sample request to generate a sample response as given below.
GET /accounts/{account-id}/transactions - Read transaction list of an account
The user can retrieve transaction reports and transaction lists for a consent-granted account using the sample request given below. Users can choose the type of transaction using the booking status parameter. For a given account, a user can specify dateFrom and dateTo parameters.
GET /accounts/{account-id}/transactions/{transactionId} - Read transaction details
The user can retrieve transaction information for a specific transaction. The path of xxx is denoted under _links subfield in the response generated by calling the GET /accounts/{account-id}/balances API resource.
Note
This call generates responses for the transactions that are reported in the JSON format.
Use the sample request and generate a response as follows:
The TPP can retrieve a list of card accounts. You can specify PSU ID to check the card-accounts that the PSU have consented. Additionally, you can retrieve balances of card accounts in the response. See below for a sample request and response.
