This documentation is for WSO2 Open Banking version 1.4.0. View documentation for the latest release.

Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.
Excerpt

This document explains the flow of events related to the Payment Initiation API v3.1.1. 

Tip
titleBefore you begin

You need to deploy the Payment Initiation API in <WSO2_OB_APIM_HOME>/repository/resources/finance/apis/openbanking.org.uk/Payments/3.1.1/payment-swagger-3.1.1.yaml. Click here to see how to deploy APIs for WSO2 Open Banking UK.

Note

If you have integrated with OBIE you can use the Dynamic Client Registration v3.2 API. Click here to see how to deploy DCR v3.2 API. Once you deploy the API you can continue from the Generate application access token step.

Table of Content Zone
maxLevel3
locationtop

Step 1 - Sign up as a TPP

A Third-Party Provider(TPP), is an authorized third-party that allows merchants to accept a wide variety of payments through a single channel/third-party application, and manage the entire payment flow from start to finish. For more information on the role, see here.

The TPP needs to register its Payment Initiation Service Provider (PISP) application in WSO2 API store in order to access the data.

Expand
titleClick here to see how it is done...
  1. Navigate to the API Store at https://<WSO2_OB_APIM_HOST>:9443/store

  2. Select Sign-up that is on the top left corner of the homepage.

    Image Modified

  3. Provide the requested details on the Sign Up page.

    Expand
    titleClick 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 payment 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 payment account.

    • Payment Initiation Service Provider: A Payment Initiation Service Provider (PISP) initiates credit transfers on behalf of a bank's customer.

    After selecting PISP, 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.

  4. Read terms and conditions. Click the checkbox to agree to the terms and conditions.

    Image Modified

  5. Click Sign Up. A request to approve the TPP sign up is now sent to the Approver users.

    Image Modified



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. 


Note

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.

Expand
titleClick here to see how it is done...
  1. Sign in to the WSO2 Open Banking API Manager Admin portal as an Approver at https://<WSO2_OB_APIM_HOST>:9443/admin

  2. Locate the approval request and click Assign To Me.
    Image Modified

  3. Click Start to start the approval process.
    Image Modified
  4. Select Approve then Complete.
    Image Modified

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.


Expand
titleClick here to see how it is done...
  1. Sign in to the API Store as the TPP at https://<WSO2_OB_APIM_HOST>:9443/store

  2. Click Sign In and navigate to the Sign In page.

  3. Enter the username and the password you entered when signing up as a TPP.

  4. Click Sign In

The homepage of the API store is now displayed along with the APIs.


Step 4 - Create an application

The TPP with an AISP application needs to create an application using WSO2 API store. The application created via WSO2 API store allows to observe statistics of APIs, subscribe to APIs, and access the subscribed APIs.
Expand
titleClick here to see how it is done...
  1. Go to the Applications tab in the API Store.

    Image Modified

  2. Click Add Application.

    Image Modified

  3. Enter application details.

    Image Modified

    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.

  4. Click Add

Note

An application can be used to subscribe to multiple APIs. See

Try out the

Payment Initiation API v3.1.1 - Domestic Payments for the instructions.


Step 5 - Subscribe to an API

The TPP user needs to subscribe to the PaymentInitiationAPI - v3.1.1 API in order to access API resources. Once subscribed to a certain API, the users are subscribing to all the supported services of the API resources .  


Expand
titleClick here to see how it is done...
  1. Go to the APIs tab in the API Store.

    Image Modified

  2. Select the API.

  3. Select the application you created in the Create an application section.

  4. Set the throttling policy to Unlimited.

  5. Click Subscribe.

Now that you have subscribed to the API, generate access tokens and invoke the API.


Step 6 - Create certificates

The TPP user needs to create certificates to validate whether the TPP is registered in a governing entity.


Expand
titleClick here to see how it is done...
  1. 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 a TPP.

    Make sure to update the following placeholders:

    <alias>A preferred alias for the keystore file.
    <filename>A preferred name for the keystore file.
    Code Block
    keytool -genkey -alias <alias> -keyalg RSA -keystore <filename>.jks

    During the command execution, the TPP user requires to;

    1. Anchor
      sourcekeystorePS
      sourcekeystorePS
      Set a password for the keystore.
    2. Provide information, acquired when registering with a governing entity.
    3. Set a password for user-defined alias (<alias>).
  2. 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.
    Code Block
    keytool -importkeystore -srckeystore <keystoreStoreName>.jks -destkeystore <PKCS12FileName>.p12 -deststoretype PKCS12

    During the command execution, the TPP user requires to;

    1. Set a password for the destination keystore.
    2. Enter the source keystore password, as defined in the above step .
  3. 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.
    Code Block
    openssl pkcs12 -in <PKCS12FileName>.p12 -nokeys -out <PEMFileName>.pem

    During the command execution, the TPP user requires to;

    1. Set a password to import the .pem file.

Step 7 - Generate keys

The TPP user requires a Client ID(Consumer Key) and a Client Secret(Consumer Secret) to access the subscribed APIs.

Expand
titleClick here to see how it is done...
  1. Sign in to the API store as a TPP user and click either of the following on the Applications tab.

    1. Production Keys: Generates access tokens in the production environment.

    2. Sandbox Keys: Generates access tokens in the sandbox environment.

  2. Provide the requested information as defined below:  

    Field

    Description

    Grant Types

    These determine the credentials that are used to generate the access token. There are six types of grant types available in WSO2 Open Banking:

    • 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

    This is the content between the BEGIN CERTIFICATE and END CERTIFICATE strings of the application certificate (.PEM) that you created above.

  3. 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.

  4. Click Generate Keys if you are generating sandbox keys. It generates consumer key and consumer secret.


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.

Note

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.

Expand
titleClick here to see how it is done...
  1. Sign in to the WSO2 Open Banking API Manager Admin portal as an Approver at https://<WSO2_OB_APIM_HOST>:9443/admin.

  2. Click Tasks and then Application Registration.

  3. Locate the approval request and click Assign To Me.

  4. Click Start to start the approval process.
    Image Modified
  5. Select Approve and then click Complete.
    Image Modified
  6. Navigate back to the API Store and click Applications.
    Image Modified
  7. On the Applications tab in the API Store, click View of the application that you created. Image Modified
  8. Click Production Keys tab to find the generated keys.
    Image Modified
  9. It includes the consumer key and consumer secret as follows:
    Image Modified

Step 9 - Generate application access token

When invoking APIs in the Account and Transaction flow, application access tokens must be generated using the client credential grant type. The generated application access token is used to invoke the PaymentInitiationAPI - v3.1.1 API.

Expand
titleClick here to see how it is done...
Note

You can skip the above steps and use DCR v3.2 API to dynamically register the clients.

  1. Once the client is successfully registered, sign in to the API Store and go to the Applications tab.

    Image Modified

  2. Select your client application from the Application List. Click View of the application that you created.

  3. Choose the Production Keys or Sandbox Keys tab based on your environment.

    Image Modified

  4. The Consumer Key shown above is the client ID of your application.

  5. Generate the client assertion by signing the following JSON payload using the supported algorithms.

    Code Block
    { 
    "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://<<OB_HOST>>:8243/token>>" 
    } 
    
    <signature>
  6. Run the following cURL command in a command prompt to generate the access token. Update the placeholders with the relevant values.

    Code Block
    curl -k  POST \
      https://<WSO2_OB_APIM_HOST>:8243/token \ 
      -H 'Cache-Control: no-cache' \
      -H 'Content-Type: application/x-www-form-urlencoded' \ 
      --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
       -d 'grant_type=client_credentials&scope=payments%20openid%20&client_assertion=<CLIENT_ASSERTION_JWT>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&redirect_uri=<APPLICATION_CALLBACK_URL>'

    The access token is now generated.


    Tip

    You can use the same cURL command to re-generate the access token.