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.

...

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. 

    It is verified in the TPP Onboarding process. For example, in Dynamic Client Registration, the TPP is dynamically registered with ASPSPs when the client sends a registration request with its metadata. Therefore, the ASPSP is required to upload the root and issuer certificates obtained from Open Banking Implementation Entity. For more information, see  Dynamic Client Registration v3.2.

    This is the name of the keystore in the .PKCS12 format.
    Multiexcerpt
    MultiExcerptNameInitialSteps

    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:

    Excerpt
    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 TPP roles.

    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.

    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.

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


    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.

    3. Click Start to start the approval process.
    4. 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.


    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 a PISP 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.


    2. Click Add Application.

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

    4. Click Add

    Note

    An application can be used to subscribe to multiple APIs. See Subscribe to an API for the instructions.


    Step 5 - Subscribe to API

    The TPP user needs to subscribe to the PaymentInitiationAPI - v3.1 API in order to access API resources. Once subscribed, the users can access 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.

    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 and upload 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...
    <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;

    Anchor
    sourcekeystorePSsourcekeystorePS<PKCS12FileName>
    Tip

    You can also create a self-signed certificate the following instructions given below and try out the API flow:

    Note

    When you are using self-signed certificates, make sure to disable the certificate revocation validation:

    1. Open the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml file
    2. Navigate to the certificate revocation validation configuration and disable it as follows:

      Code Block
      <CertificateManagement>
          <!-- Enable certificate OCSP and CRL validation -->
          <CertificateRevocationValidationEnabled>true</CertificateRevocationValidationEnabled>
      /CertificateManagement>
    Expand
    titleClick here to see a self-signed certificate is created...
    Note

    In order to use self-signed certificates as mentioned in the below steps, disable the <CertificateRevocationValidationEnabled> configuration under <CertificateManagement> in the <WSO2_OB_KM_HOME>/repository/conf/finance/open-banking.xml and <WSO2_OB_APIM_HOME>/repository/conf/finance/open-banking.xml files.

    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:

    <keyStoreName>This is the name of the <filename>, given above.
    1. <alias>A preferred alias for the keystore file.
      <filename>A preferred name for the keystore file.
      Code Block
      keytool -
    importkeystore
    1. genkey -
    srckeystore
    1. alias 
    <keystoreStoreName>.jks
    1. <alias> -
    destkeystore
    1. keyalg 
    <PKCS12FileName>.p12
    1. RSA -
    deststoretype
    1. keystore 
    PKCS12
    1. <filename>.jks

      During the command execution, the TPP user requires to;

      1. Anchor
        sourcekeystorePS
        sourcekeystorePS
        Set a password for the
    destination
      1. 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.

      1. Provide information, acquired when registering with a governing entity.
      2. Set a password for user-defined alias (<alias>).
    1. Convert the keystore from the .jks format to .PKCS12.  Make sure to update the following placeholders:

    <PKCS12FileName><PEMFileName>
    1. <keyStoreName>This is the name of the
    keystore in the PKCS12 format, as mentioned above for the <PKCS12FileName>.
    1. <filename>, given above.
      <PKCS12FileName>This is the name of the
    application certificate that is created
    1. keystore in the .
    pem
    1. PKCS12 format.
      Code Block
    openssl pkcs12
    1. keytool -importkeystore -srckeystore <keystoreStoreName>.jks -
    in
    1. destkeystore <PKCS12FileName>.p12 -
    nokeys -out <PEMFileName>.pem
    1. deststoretype PKCS12

      During the command execution, the TPP user requires to;

      1. Set a password
    to import
      1. for 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...
  • 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.

    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

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

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

  • 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 Removed
    5. Select Approve and then click Complete.
      Image Removed
    6. Navigate back to the API Store and click Applications.
      Image Removed
    7. On the Applications tab in the API Store, click View of the application that you created. Image Removed
    8. Click Production Keys tab to find the generated keys.
      Image Removed
    9. It includes the consumer key and consumer secret as follows:
      Image Removed

    Step 9 - Generate application access token

    When invoking APIs in the payment 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 API.
      1. destination keystore.
      2. Enter the source keystore password, as defined in the above step .
    1. 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.

     Once you create a self-signed certificate, upload it 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
    • Use the following command to upload the self-signed certificate:

    Code Block
    keytool -import -alias <alias> -keystore cacerts -file <PEMFileName>.pem

    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.

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

    { "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 issuerImage Added
  • It includes the consumer key and consumer secret as follows:
    Image Added
  • 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.

      Once the client is successfully registered, sign in
    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 Added
    5. Select Approve and then click Complete.
      Image Added
    6. Navigate back to the API Store and go to the click Applicationstab.

      Image Removed

      Select your client application from the Application List. Click Image Added
    7. On the Applications tab in the API Store, click View of the application that you created. Image Added
    8. Choose the Click Production Keys or Sandbox Keys tab based on your environment tab to find the generated keys.

      Image Removed

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

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

    Localtab Group
    Localtab
    titleclient_assertion format
    Code Block

    Step 9 - Generate application access token

    When invoking APIs in the payment 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 API.

    curl -k POST \ https://<WSO2_OB_APIM_HOST>:8243/token \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/x-www-
  • 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 Added

    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 Added

    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.

      Localtab Group
      Localtab
      titleclient_assertion format
      Code Block
      { 
      "alg": "<<This will be the algorithm used for signing>>", 
      "kid": "<<This will be the certificate fingerprint>>", 
      "typ": "JWT" 
      } 
      
      { 
      "iss": "<<This is the issuer 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>
      Localtab
      titlesample client_assertion
      Code Block
      eyJraWQiOiJoY2dleHVndVZiNXJZU1lWQnNsLWM5aEJQdlkiLCJhbGciOiJQUzI1NiJ9.eyJzdWIiOiJpMkJmbFJyeWIxVkdsRUpHNlpTMDR0bTNHaGNhIiwiYXVkIjoiaHR0cHM6Ly9sb2NhbGhvc3Q6ODI0My90b2tlbiIsImlzcyI6ImkyQmZsUnJ5YjFWR2xFSkc2WlMwNHRtM0doY2EiLCJleHAiOjE1OTkxODcyMDEsImlhdCI6MTU2NTcyMDUzNywianRpIjoiMTU2NTcyMTUzOCJ9.THAG1Ox8hAoGe3hXUvX8rrsIoU7SJfcfSWOxNkdnERb827hxDx2FbVN2wrNhe4A93AYMaCYsHqq8s6p4gkeREWGbJ_IGSjmzJPATWC0oAfAP8hRqdFNUfnTufN7lNlWwySJ7OyBgqorq_ABOx1i741bnld4Jyz8e58gi9UPRi7lFuWnvO-6RwlZY771B1qYNQFTULitV5jX38XJXTX2jrdc_2OkoAS3cL_2x05zZqNFpIvtoK-6XJP1HgRrlDdYx3jzuhAk9F5Q-4BlrbdiUS6QP0PFA_by4y-1vScBAGBhCH4_ViUuGdT9c0FSBGE9_3sLkyj_4SLJRPiQwn6NLbg
    6. Run the following cURL command in a command prompt to generate the access token. Update the placeholders with the relevant values.

    Multiexcerpt
    MultiExcerptNameapplicatinAccesstoken
    Code Block
    Note

    The value of the aud claim should contain the same value as the Identity Provider Entity ID.

    Expand
    titleClick here to view the Identity Provider Entity ID:
    1. Sign in to the Identity and Access Management console at  https://localhost:9446/carbon
    2. In the Main menu, go to Home > Identity > Identity Providers > Resident.
    3. 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.

    Multiexcerpt
    MultiExcerptNameapplicatinAccesstoken
    Code Block
    curl  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 regenerate the access token.




  • Step 10 - Initiate domestic payment consent

    ...

    curl -X POST \ https://<WSO2_OB_APIM_HOST>:8243/open-banking/v3.1/pisp/domestic-payment-consents \ -H 'Authorization: Bearer <APPLICATION_ACCESS_TOKEN>' \ -H 'Cache-Control: no-cache' \ -H 'Content-Type: application/json' \ -H 'x-fapi-financial-id: open-bank' \ -H 'x-idempotency-key: 188610727' \ -H 'x-jws-signature: fdffv' \ -d '{ "Data": { "Initiation": { "InstructionIdentification": "ACME412", "EndToEndIdentification": "FRESCO.21302.GFX.20", "InstructedAmount": { "Amount": "165.88", "Currency": "GBP" }, "CreditorAccount": { "SchemeName": "UK.OBIE.SortCodeAccountNumber", "Identification": "08080021325698", "Name": "ACME Inc", "SecondaryIdentification": "0002" }, "DebtorAccount

    Expand
    titleClick here to see how it is done

    POST /domestic-payment-consents

    This endpoint allows the PISP to ask an ASPSP to create a new domestic-payment-consent resource. The ASPSP creates the domestic-payment-consent resource and responds with a unique ConsentId to refer to the resource.

    • Use the following format in the request body.

      Code Block
      {
        "Data": {
          "Initiation": {
            "InstructionIdentification": "string",
            "EndToEndIdentification": "string",
            "LocalInstrument": [
              "UK.OBIE.BACS",
              "UK.OBIE.BalanceTransfer",
              "UK.OBIE.CHAPS",
              "UK.OBIE.Euro1",
              "UK.OBIE.FPS",
              "UK.OBIE.Link",
              "UK.OBIE.MoneyTransfer",
              "UK.OBIE.Paym",
              "UK.OBIE.SEPACreditTransfer",
              "UK.OBIE.SEPAInstantCreditTransfer",
              "UK.OBIE.SWIFT",
              "UK.OBIE.Target2"
            ],
            "InstructedAmount": {
              "Amount": "string",
              "Currency": "string"
            },
            "DebtorAccount": {
              "SchemeName": [
                "UK.OBIE.BBAN",
                "UK.OBIE.IBAN",
                "UK.OBIE.PAN",
                "UK.OBIE.Paym",
                "UK.OBIE.SortCodeAccountNumber"
              ],
              "Identification": "string",
              "Name": "string",
              "SecondaryIdentification": "string"
            },
            "CreditorAccount": {
              "SchemeName": [
                "UK.OBIE.BBAN",
                "UK.OBIE.IBAN",
                "UK.OBIE.PAN",
                "UK.OBIE.Paym",
                "UK.OBIE.SortCodeAccountNumber"
              ],
              "Identification": "string",
              "Name": "string",
              "SecondaryIdentification": "string"
            },
            "CreditorPostalAddress": {
              "AddressType": "Business",
              "Department": "string",
              "SubDepartment": "string",
              "StreetName": "string",
              "BuildingNumber": "string",
              "PostCode": "string",
              "TownName": "string",
              "CountrySubDivision": "string",
              "Country": "string",
              "AddressLine": [
                "string"
              ]
            },
            "RemittanceInformation": {
              "Unstructured": "string",
              "Reference": "string"
            },
            "SupplementaryData": {}
          },
          "Authorisation": {
            "AuthorisationType": "Any",
            "CompletionDateTime": "2019-07-26T06:03:44.272Z"
          }
        },
        "Risk": {
          "PaymentContextCode": "BillPayment",
          "MerchantCategoryCode": "string",
          "MerchantCustomerIdentification": "string",
          "DeliveryAddress": {
            "AddressLine": [
              "string"
            ],
            "StreetName": "string",
            "BuildingNumber": "string",
            "PostCode": "string",
            "TownName": "string",
            "CountrySubDivision": [
              "string"
            ],
            "Country": "string"
          }
        }
      }
    • Add all mandatory headers:
      • x-fapi-financial-id - The unique id of the ASPSP to which the request is issued. This id will be issued by the OBIE.
      • Authorization - An Authorisation Token as per https://tools.ietf.org/html/rfc6750. Enter the application access token, you generated from the above step .

      • x-idempotency-key - Every request will be processed only once per x-idempotency-key. The Idempotency key will be valid for 24 hours.
      • x-jws-signature - A detached JWS signature of the body of the payload.
    • A sample request follows the format given below.

    Code Block
    Code Block
    {
      "Data": {
        "Initiation": {
            "SchemeNameInstructionIdentification": "UK.OBIE.SortCodeAccountNumberANSM023",
     
          "IdentificationEndToEndIdentification": "11280001234567FRESCO.21302.GFX.37",
     
          "NameInstructedAmount": "Andrea Smith"
        {
     },       "RemittanceInformationAmount": {"20.00",
            "ReferenceCurrency": "FRESCO-101GBP",
          },
     "Unstructured": "Internal ops code 5120101"
         "DebtorAccount": {
         }     }
      }"SchemeName": "UK.OBIE.SortCodeAccountNumber",
      "Risk": {     "PaymentContextCodeIdentification": "EcommerceGoods11280001234567",
            "MerchantCategoryCodeName": "5967Andrea Smith",
         "MerchantCustomerIdentification": "053598653254" },
          "DeliveryAddressCreditorAccount": {
            "AddressLineSchemeName": ["UK.OBIE.SortCodeAccountNumber",
            "Flat 7Identification": "08080021325698",
            "Acacia Lodge"Name": "Bob Clements"
          ]},
          "StreetNameRemittanceInformation": "Acacia Avenue",{
            "BuildingNumberReference": "27FRESCO-037",
          "PostCode": "GU31 2ZZ",
          "TownName""Unstructured": "Sparsholt",
          "CountrySubDivision": [Internal ops code 5120103"
          }
      "Wessex"  }
      },
     ], "Risk": {
        "CountryPaymentContextCode": "UKPartyToParty"
        }
      }
    }'

    The response will bear the ConsentId.

    Code Block
    {
        "Data": {
            "Status": "AwaitingAuthorisation",
            "StatusUpdateDateTime": "2019-07-26T08:08:12Z",
            "CreationDateTime": "2019-07-26T08:08:12Z",
            "ConsentId": "4a40cde1-e596-4612-93dc-85e2aa083dbb",
            "Initiation": {
                "DebtorAccount": {
                    "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                    "Identification": "11280001234567",
                    "Name": "Andrea Smith"
                },
                "RemittanceInformation}
  • Add all mandatory headers:
    • x-fapi-financial-id - The unique id of the ASPSP to which the request is issued. This id will be issued by the OBIE.
    • Authorization - An Authorisation Token as per https://tools.ietf.org/html/rfc6750. Enter the application access token, you generated from the above step .

    • x-idempotency-key - Every request will be processed only once per x-idempotency-key. The Idempotency key will be valid for 24 hours.
    • x-jws-signature - A detached JWS signature of the body of the payload.
  • A sample request follows the format given below.

    Code Block
    curl POST  /
      https://<WSO2_OB_APIM_HOST>:8243/open-banking/v3.1/pisp/domestic-payment-consents \
      -H 'Authorization: Bearer <APPLICATION_ACCESS_TOKEN>' \
      -H 'x-idempotency-key: FRESCO.21302.GFX.20' \
      -H 'x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==' \
      -H 'x-fapi-financial-id: open-bank' \
      -H 'x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 GMT' \
      -H 'x-fapi-customer-ip-address: 104.25.212.99' \
      -H 'x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json' \
      --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
    -d '{
      "Data": {
        "Initiation": {
          "InstructionIdentification": "ANSM023",
            "UnstructuredEndToEndIdentification": "Internal ops code 5120101FRESCO.21302.GFX.37",
          "InstructedAmount": {
            "ReferenceAmount": "FRESCO-101"20.00",
            "Currency": "GBP"
      },    },
            "EndToEndIdentificationDebtorAccount": "FRESCO.21302.GFX.20",{
                "InstructionIdentificationSchemeName": "ACME412UK.OBIE.SortCodeAccountNumber",
                "CreditorAccountIdentification": {"11280001234567",
            "Name": "Andrea  Smith"
        "SecondaryIdentification": "0002"  },
          "CreditorAccount": {
            "SchemeName": "UK.OBIE.SortCodeAccountNumber",
            "Identification": "08080021325698",
            "IdentificationName": "08080021325698Bob Clements",
          },
             "NameRemittanceInformation": {
    "ACME  Inc"      "Reference": "FRESCO-037",
         },   "Unstructured": "Internal ops code 5120103"
         "InstructedAmount": {}
        }
      },
      "Risk": {
        "AmountPaymentContextCode": "165.88PartyToParty",
      }
    }'
  • The response will bear the ConsentId.

    Code Block
    {
          "Data": {
         "CurrencyConsentId": "GBP7290",
        "Status": "AwaitingAuthorisation",
        "CreationDateTime":  }"2017-06-05T15:15:13+00:00",
        "StatusUpdateDateTime": "2017-06-05T15:15:13+00:00",
       } "Initiation": {
      },     "RiskInstructionIdentification": {"ANSM023",
            "PaymentContextCodeEndToEndIdentification": "EcommerceGoodsFRESCO.21302.GFX.37",
            "DeliveryAddressInstructedAmount": {
       
            "StreetNameAmount": "Acacia Avenue20.00",
       
            "CountrySubDivisionCurrency": ["GBP"
            },
           "WessexDebtorAccount": {
               ],
    "SchemeName": "UK.OBIE.SortCodeAccountNumber",
               "AddressLineIdentification": ["11280001234567",
            "Name": "Andrea Smith"
         "Flat 7"},
          "CreditorAccount": {
            "SchemeName"Acacia Lodge": "UK.OBIE.SortCodeAccountNumber",
                ],
     "Identification": "08080021325698",
              "BuildingNumberName": "27Bob Clements",
          },
          "TownNameRemittanceInformation": "Sparsholt",
       {
            "CountryReference": "UKFRESCO-037",
       
            "PostCodeUnstructured": "GU31 2ZZInternal ops code 5120103"
          }
     },   }
      },
      "MerchantCategoryCodeRisk": "5967",{
            "MerchantCustomerIdentificationPaymentContextCode": "053598653254PartyToParty"
     
      },
        "Links": {
            "Self": "https://localhost:8243obank.com/open-banking/v3.1/pisp/domestic-payment-consents/4a40cde1-e596-4612-93dc-85e2aa083dbb7290"
        },
        "Meta": {}
    }
  • GET /domestic-payment-consents/{ConsentId}

    A PISP is able to retrieve a payment consent resource that they have created to check its status. The PISP must have an access token issued by the ASPSP using a client credentials grant.

    • Add the mandatory headers.
      • ConsentId - The unique id of the consent which you want to retrieve.
      • x-fapi-financial-id - The unique id of the ASPSP to which the request is issued. This id will be issued by the OBIE.
      • Authorization - An Authorisation Token as per https://tools.ietf.org/html/rfc6750. Enter the application access token, you generated from the above step.
    • A sample request follows the format given below.

      Code Block
      curl -X GET \
        https://<WSO2_OB_APIM_HOST>:8243/open-banking/v3.1/pisp/domestic-payment-consents/<ConsentId> \
        -H 'Authorization: Bearer <APPLICATION_ACCESS_TOKEN>' -k \
        -H 'Cache-Control: no-cache' \
        -H 'Content-Type: application/json' \
        -H -H 'x-fapi-financial-id: open-bank''x-fapi-financial-id: open-bank' \
        --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
    • Following is a sample response.

      Code Block
      {
          "Data": {
              "Status": "AwaitingAuthorisation",
              "StatusUpdateDateTime": "2019-07-26T08:08:12Z",
              "CreationDateTime": "2019-07-26T08:08:12Z",
              "ConsentId": "4a40cde1-e596-4612-93dc-85e2aa083dbb",
              "Initiation": {
                  "DebtorAccount": {
                      "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                      "Identification": "11280001234567",
                      "Name": "Andrea Smith"
                  },
                  "RemittanceInformation": {
                      "Unstructured": "Internal ops code 5120101",
                      "Reference": "FRESCO-101"
                  },
                  "EndToEndIdentification": "FRESCO.21302.GFX.20",
                  "InstructionIdentification": "ACME412",
                  "CreditorAccount": {
                      "SecondaryIdentification": "0002",
                      "SchemeName": "UK.OBIE.SortCodeAccountNumber",
                      "Identification": "08080021325698",
                      "Name": "ACME Inc"
                  },
                  "InstructedAmount": {
                      "Amount": "165.88",
                      "Currency": "GBP"
                  }
              }
          },
          "Risk": {
              "PaymentContextCode": "EcommerceGoods",
              "DeliveryAddress": {
                  "StreetName": "Acacia Avenue",
                  "CountrySubDivision": [
                      "Wessex"
                  ],
                  "AddressLine": [
                      "Flat 7",
                      "Acacia Lodge"
                  ],
                  "BuildingNumber": "27",
                  "TownName": "Sparsholt",
                  "Country": "UK",
                  "PostCode": "GU31 2ZZ"
              },
              "MerchantCategoryCode": "5967",
              "MerchantCustomerIdentification": "053598653254"
          },
          "Links": {
              "Self": "https://localhost:8243obank.com/open-banking/v3.1/pisp/domestic-payment-consents4a40cde1consents/4a40cde1-e596-4612-93dc-85e2aa083dbb"
          },
          "Meta": {}
      }
    Multiexcerpt
    MultiExcerptNameUserAccessToken

    Step 11 - Authorizing payment consents

    The PISP redirects the bank customer to authenticate and approve/deny application-provided consents.

    Expand
    titleClick here to see how it is done
    1. Generate the request object by signing the following JSON payload using the supported algorithms.

      Code Block
      {
        "kid": "<CERTIFICATE_FINGERPRINT>",
        "alg": "<SUPPORTED_ALGORITHM>",
        "typ": "JWT"
      }
      {
        "max_age": 86400,
        "aud": "<This is the audience that the ID token is intended for. e.g., https://<WSO2_OB_APIM_HOST>:8243/token>",
        "scope": "accountspayments openid",
        "iss": "<APPLICATIONT_ID>",
        "claims": {
          "id_token": {
            "acr": {
              "values": [
                "urn:openbanking:psd2:sca",
                "urn:openbanking:psd2:ca"
              ],
              "essential": true
            },
            "openbanking_intent_id": {
              "value": "<CONSENTID>",
              "essential": true
            }
          },
          "userinfo": {
            "openbanking_intent_id": {
              "value": "<CONSENTID>",
              "essential": true
            }
          }
        },
        "response_type": "<code:Retrieves authorize code/code id_token: Retrieves authorize token and ID token>",   
        "redirect_uri": "<CLIENT_APPLICATION_REDIRECT_URI>",
        "state": "YWlzcDozMTQ2",
        "exp": <EPOCH_TIME_OF_TOKEN_EXPIRATION>,
        "nonce": "<PREVENTS_REPLAY_ATTACKS>",
        "client_id": "<APPLICATION_ID>"
      }
    2. Run the following in a browser to prompt the invocation of the authorize API. Make sure you update the placeholders with the relevant values:

      Code Block
      https://<WSO2_OB_APIM_HOST>:8243/authorize/?response_type=<RESPONSE_TYPE>&client_id=<APPLICATION_ID>&scope=payments%20openid&redirect_uri=<APPLICATION_REDIRECT_URI>&state=YWlzcDozMTQ2&request=<REQUEST_OBJECT>&prompt=login&nonce=<REQUEST_OBJECT_NONCE>
    3. You are directed to a login page. Log in with the credentials of a user that has a subscriber role.
    4. 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.
    5. Upon providing consent, an authorization code is generated.




    Step 12 - Generate user access token

    In this section, you will be generating an access token using the authorization code generated in the section above .

    Expand
    titleClick here to see how it is done

    Run the following cURL command in a command prompt to generate the access token as a TPP user:

    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 'client_id=<APPLICATION_ID>&grant_type=authorization_code&code=<CODE_GENERATED>&redirect_uri=<APPLICATION_REDIRECT_URI>&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<CLIENT_ASSERTION>'

    The response contains an access token and a refresh token.

    Note

    The access tokens have an expiration period, once an access token expires, you need to regenerate it. Run the following cURL command to call the refresh_token endpoint and regenerate generate a new access token as a PISP:

    Code Block
    curl -X POST \
     https://<WSO2_OB_APIM_HOST>:8243/token \
     -H 'Authorization: Basic <APPLICATION CLIENTID:CLIENT_SECRET_BASE64_ENCODED>' \
     -H 'Content-Type: application/x-www-form-urlencoded' \
     -H 'cache-control: no-cache' \
    
    -k --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
    
    -d 'grant_type=refresh_token&refresh_token=<REFRESH_TOKEN>'




    ...

    Expand
    titleClick here to see how it is done

    POST /domestic-payments

    The PISP must ensure that the Initiation and Risk sections of the domestic-payment match the corresponding Initiation and Risk sections of the domestic-payment-consent resource. If the two do not match, the ASPSP must not process. Any operations on the domestic-payment resource do not result in a status change for the domestic-payment resource.

    The response contains  DomesticPaymentId along with the payment submission details. 

    Localtab Group
    Localtab
    titleRequest
    Code Block
    curl POST \
      https://<WSO2_OB_APIM_HOST>:8243/open-banking/v3.1/pisp/domestic-payments HTTP/1.1
    \
      -H 'Authorization: Bearer <USER_ACCESS_TOKEN>
    ACCESS_TOKEN>' \
      -H 'x-idempotency-key: FRESNO.1317.GFX.22' \
      -H 'x-jws-signature: TGlmZSdzIGEgam91cm5leSBub3QgYSBkZXN0aW5hdGlvbiA=..T2ggZ29vZCBldmVuaW5nIG1yIHR5bGVyIGdvaW5nIGRvd24gPw==' \
      -H 'x-fapi-financial-id: OB/2017/001
    open-bank' \
      -H 'x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 GMT' \
      -H 'x-fapi-customer-ip-address: 104.25.212.99' \
      -H 'x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d' \
      -H 'Content-Type: application/json' \
      -H 'Accept: application/json
     
     application/json' \
      --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
    -d '{
      "Data": {
        "ConsentId": "58923",
        "Initiation": {
          "InstructionIdentification": "ACME412",
          "EndToEndIdentification": "FRESCO.21302.GFX.20",
          "InstructedAmount": {
            "Amount": "165.88",
            "Currency": "GBP"
          },
          "CreditorAccount": {
            "SchemeName": "UK.OBIE.SortCodeAccountNumber",
            "Identification": "08080021325698",
            "Name": "ACME Inc",
            "SecondaryIdentification": "0002"
          },
          "RemittanceInformation": {
            "Reference": "FRESCO-101",
            "Unstructured": "Internal ops code 5120101"
          }
        }
      },
      "Risk": {
        "PaymentContextCode": "EcommerceGoods",
        "MerchantCategoryCode": "5967",
        "MerchantCustomerIdentification": "053598653254",
        "DeliveryAddress": {
          "AddressLine": [
            "Flat 7",
            "Acacia Lodge"
          ],
          "StreetName": "Acacia Avenue",
          "BuildingNumber": "27",
          "PostCode": "GU31 2ZZ",
          "TownName": "Sparsholt",
          "CountySubDivision": [
            "Wessex"
          ],
          "Country": "UK"
        }
      }
    }'
    Localtab
    titleResponse
    Code Block
    HTTP/1.1 201 Createdx-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
    x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
    Content-Type: application/json
     
    {
      "Data": {
        "DomesticPaymentId": "58923-001",
        "ConsentId": "58923",
        "Status": "AcceptedSettlementInProcess",
        "CreationDateTime": "2017-06-05T15:15:22+00:00",
        "StatusUpdateDateTime": "2017-06-05T15:15:13+00:00",
        "Initiation": {
          "InstructionIdentification": "ACME412",
          "EndToEndIdentification": "FRESCO.21302.GFX.20",
          "InstructedAmount": {
            "Amount": "165.88",
            "Currency": "GBP"
          },
          "CreditorAccount": {
            "SchemeName": "UK.OBIE.SortCodeAccountNumber",
            "Identification": "08080021325698",
            "Name": "ACME Inc",
            "SecondaryIdentification": "0002"
          },
          "RemittanceInformation": {
            "Reference": "FRESCO-101",
            "Unstructured": "Internal ops code 5120101"
          }
        }
      },
      "Links": {
        "Self": "https://apiobank.alphabank.com/open-banking/v3.1/pisp/domestic-payments/58923-001"
      },
      "Meta": {}
    }

    ...

    Expand
    titleConfirmation of funds on a domestic-payment-consent resource

    GET /domestic-payment-consents/{ConsentId}/funds-confirmation

    The API endpoint allows the PISP to ask an ASPSP to confirm funds on a domestic-payment-consent resource.

    An ASPSP can only respond to a funds confirmation request if the domestic-payment-consent resource has an Authorised status. The confirmation of funds requests do not affect the status of the domestic-payment-consent resource.

    Localtab Group
    Localtab
    titleRequest
    Code Block
    curl GET \
      https://<WSO2_OB_APIM_HOST>:8243/open-banking/v3.1/pisp/domestic-payment-consents/<ConsentId>/funds-confirmation HTTP/1.1Authorization\
      -H 'Authorization: Bearer <USER_ACCESS_TOKEN>' \
      -H 'x-fapi-financial-id: OB/2017/001
    open-bank' \
      -H 'x-fapi-customer-last-logged-time: Sun, 10 Sep 2017 19:43:31 GMT' \
      -H 'x-fapi-customer-ip-address: 104.25.212.99' \
      -H 'x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d' \
      -H 'Accept: application/json
    Localtab
    titleResponse
    Code Block
    HTTP/1.1 200 OKx-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
    x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
    Content-Type: application/json
     
    ' \
      --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
    Localtab
    titleResponse
    Code Block
    {
        "Data": {
            "FundsAvailableResult": {
                "FundsAvailableDateTime": "2017-06-05T15:15:23+00:00",
                "FundsAvailable": true
            }
        },
        "Links": {
            "Self": "https://apiobank.alphabank.com/open-banking/v3.1/pisp/domestic-payment-consents/58923/funds-confirmation"
        },
        "Meta": {}
    }
    Expand
    titleRetrieval of a domestic-payment resource

    GET /domestic-payments/{DomesticPaymentId}

    The PISP retrieves the domestic-payment resource to check its status.

    Localtab Group
    Localtab
    titleRequest
    Code Block
    curl GET \
      https://<WSO2_OB_APIM_HOST>:8243/open-banking/v3.1/pisp/domestic-payments/<DomesticPaymentId> HTTP/1.1
     \
      -H 'Authorization: Bearer <USER_ACCESS_TOKEN>' \
      -H 'x-fapi-financial-id: OB/2017/001
    open-bank' \
      -H 'x-fapi-customer-last-logged-time:  Sun, 10 Sep 2017 19:43:31 GMT
    31 GMT' \
      -H 'x-fapi-customer-ip-address: 104.25.212.99' \
      -H 'x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d' \
      -H 'Accept: application/json
    Localtab
    titleResponse
    Code Block
    HTTP/1.1 200 OK
    x-jws-signature: V2hhdCB3ZSBnb3QgaGVyZQ0K..aXMgZmFpbHVyZSB0byBjb21tdW5pY2F0ZQ0K
    x-fapi-interaction-id: 93bac548-d2de-4546-b106-880a5018460d
    Content-Type: application/json
     
    ' \
      --cert <PUBLIC_KEY_FILE_PATH> --key <PRIVATE_KEY_FILE_PATH> \
    Localtab
    titleResponse
    Code Block
     {
      "Data": {
        "DomesticPaymentId": "58923-001",
        "ConsentId": "58923",
        "Status": "AcceptedSettlementInProcess",
        "CreationDateTime": "2017-06-05T15:15:22+00:00",
        "StatusUpdateDateTime": "2017-06-05T15:15:22+00:00",
        "Initiation": {
          "InstructionIdentification": "ACME412",
          "EndToEndIdentification": "FRESCO.21302.GFX.20",
          "InstructedAmount": {
            "Amount": "165.88",
            "Currency": "GBP"
          },
          "CreditorAccount": {
            "SchemeName": "UK.OBIE.SortCodeAccountNumber",
            "Identification": "08080021325698",
            "Name": "ACME Inc",
            "SecondaryIdentification": "0002"
          },
          "RemittanceInformation": {
            "Reference": "FRESCO-101",
            "Unstructured": "Internal ops code 5120101"
          }
        }
      },
      "Links": {
        "Self": "https://api.alphabankobank.com/open-banking/v3.1/pisp/domestic-payments/58923-001"
      },
      "Meta": {}
    }