This document explains the flow of events related to the Payment Information Service (PIS) that a Payment Initiation Service Provider (PISP) tries. For the Berlin specific solution, the PIS is exposed as an API resource in NextGenPSD2XS2AFramework - 1.3.3
of WSO2 Open Banking. In the
- PSU authorises the payment-initiation and payment-cancellation.
Users can test the PISP flow in WSO2 Open Banking using the following steps that are described below.
Step 1 - Sign up as a TPP
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
.
Select Sign-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.
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 Add Application .
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.
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 - Create and upload certificates
The TPP user needs to obtain an eIDAS certificate from a Qualified Trust Service Provider (QTSP) that validates whether the TPP is registered in a governing entity. It is verified in the TPP Onboarding process.
For testing purposes, WSO2 Open Banking provides a sample eIDAS certificate. To download the sample eIDAS certificate, click here.
Upload the downloaded sample eIDAS certificate to the client trust stores of WSO2 OB APIM and WSO2 OB KM.
- Locate the client trust stores in WSO2 OB APIM and WSO2 OB KM in the following directory paths:
<WSO2_OB_APIM>/repository/resources/security/client-truststore.jks
<WSO2_OB_KM>/repository/resources/security/client-truststore.jks
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. |
---|
keytool -genkey -alias <alias> -keyalg RSA -keystore <filename>.jks
During the command execution, the TPP user requires to;
-
Set 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. |
---|
keytool -importkeystore -srckeystore <keystoreStoreName>.jks -destkeystore <PKCS12FileName>.p12 -deststoretype PKCS12
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. |
---|
openssl pkcs12 -in <PKCS12FileName>.p12 -nokeys -out <PEMFileName>.pem
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.
|
Click Request Access if 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 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.
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 click Applications.
- 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:
Step 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.
Run the following cURL command in a command prompt to generate the access token. Update the placeholders with the relevant values.
curl -v POST \
https://<WSO2_OB_APIM_HOST>:8243/token \
--cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
-H "Content-Type: application/x-www-form-urlencoded;charset=ISO-8859-1" \
-d "client_id=<CLIENT_ID>&grant_type=client_credentials&scope=payments+openid&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<CLIENT_ASSERTION_JWT>&redirect_uri=<APPLICATION_CALLBACK_URL>"
The access token is now generated.
Step 10 - Initiate a payment
In this step, the TPP creates a request to get the consent of the PSU before a transaction is executed.
Click here to see how it is done...
The TPP initiates a payment request to the ASPSP. The request body can be sent as a JSON body or pain.001 XML. The type of the request body is determined by the payment-service type and payment-product type.
Click here to see how it is done...
- Below mentioned are the available values for payment-service and payment-product types:
Payment service type:
- Single payment
- Bulk payment
- Periodic payment
Payment product type:
- sepa-credit-transfers
- instant-sepa-credit-transfers
- target-2-payments
- cross-border-credit-transfers
According to the payment-service and payment-product chose, the request body changes as follows:
The TPP implicitly generates the authorisation URL using the well-known URL under scaOAuth
link in the response. See Step 11 - Authorise the payment for more information on the authorisation URL.
Sample response for the payment-initiation request differs according to the chosen payment-service as follows:
Step 11 - Authorise the payment
WSO2 Open Banking v1.4.0 for Berlin Implementation supports both implicit and explicit authorization flows for transaction 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 for a particular transaction after the payment 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 payment-initiation 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 /{payment-service}/{payment-product}/{paymentId}/authorisations
API resource. At this point, the ASPSP creates authorization sub resources for the transaction 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.
Click here to see how it is done...
- The TPP invokes
POST /{payment-service}/{payment-product}/{paymentId}/authorisations
API resource to authorise a particular payment. - The TPP generates the authorisation URL using the well-known URL under
scaOAuth
link in the response.
POST /{payment-service}/{payment-product}/{paymentId}/authorisations - Initiate an authorisation for a payment
The TPP can authorise the particular payment using the sample request given below. In this case, the TPP is creating an authorisation subresource, that the PSU can use to authorise.
The TPP uses the well-known URL regardless of the authorisation followed (Implicit/Explicit) to authorise payments as below:
Click here to see how it is done...
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 a payment. |
Explicit authorisation | The response the TPP gets when invoking POST /{payment-service}/{payment-product}/{paymentId}/authorisations API resource. |
A sample well-known URL under scaOAuth
parameter looks as below:
{
"scaOAuth":
{
"href":"https://<WSO2_OB_APIM_HOST>:8243/.well-known/openid-configuration"
}
}
Paste the authorisation URL in the browser. The format for the authorisation URL looks as follows:
https://<WSO2_OB_APIM_HOST>:8243/authorize/?scope=<YOUR_SCOPES>&response_type=code&redirect_uri=<REDIRECT_URI>&state=<DYNAMICALLY_SET_VALUE>&code_challenge_method=<YOUR_CODE_CHALLENGE_METHOD>&client_id=<ORGANIZATION_ID>&code_challenge=<YOUR_CODE_CHALLENGE>
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 pis:<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 payment 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.
Step 12 - Cancel a payment
The cancellation of payment can happen in the following ways:
- TPP directly cancels a payment.
- TPP sends a payment cancellation request and based on the ASPSP requirements the PSU then authorizes the cancellation.
To define the cancellation method, configure the AuthorizeCancellation
property in <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml.
The TPP initiates the cancellation of the payment request as follows:
Click here to see how it is done...
DELETE /{payment-service}/{payment-product}/{paymentId} - Payment cancellation
The sample request and response looks as follows for the payment cancellation:
Authorise a cancellation of payment
The TPP can authorise a cancellation for an already cancelled payment.
Click here to see how it is done...
POST /{payment-service}/{payment-product}/{paymentId}/cancellation-authorisations - Start the authorisation process for the cancellation of the addressed payment
Creates an authorisation subresource and start the authorisation process of the cancellation of the addressed payment. Sample request and response are as follows: