/
Payment Initiation Service Provider Flow v1.3.6

This site contains the documentation that is relevant to older WSO2 product versions and offerings.
For the latest WSO2 documentation, visit https://wso2.com/documentation/.

Payment Initiation Service Provider Flow v1.3.6

Jul 05, 2023

This document explains the flow of events related to the Payment Information Service that a Payment Initiation Service Provider (PISP) tries. For the Berlin specific solution, the Payment Information Service is exposed as an API resource in NextGenPSD2XS2AFramework of WSO2 Open Banking. In the Payment Information Service, a  PISP initiates a payment submission on behalf of Payment Services Users (PSUs) and the PSU  authorises the payment-initiation and payment-cancellation.

Before you begin,

You need to deploy the NextGenPSD2XS2A API v1.3.6.  

 Click here to see how to deploy the API...

Loading

You can try out the Payment Initiation flow in WSO2 Open Banking using the following steps:

Loading

Step 8 - 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 NextGen PSD2 XS2A Framework API.

 Click here to see how it is done...

  1. 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:
    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 .

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

    You can use the same cURL command to regenerate the access token.

Step 9 - 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...

POST /{payment-service}/{payment-product} - Initiate payment request

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...
  1. Below mentioned are the available values for payment-service and payment-product types:

    Payment service type:

      1. Single payment
      2. Bulk payment
      3. Periodic payment

    Payment product type:

      1. sepa-credit-transfers
      2. instant-sepa-credit-transfers
      3. target-2-payments
      4. cross-border-credit-transfers

    To support a custom payment product

    By default, the solution supports the standard payment products as given in the Berlin swagger file. To support a custom payment product, the ASPSP needs to update the swagger file and republish the API as follows:

    1. Sign in to the API Publisher at https://<WSO2_OB_APIM_HOST>:9443/publisher as an API Publisher.

    2. Go to the   APIs tab in the Developer portal.

    3. Select the NextGenPSD2XS2A Framework API. 

    4. You are redirected to the API Overview page.

    5. Go to  API Definition using the left menu panel.
    6. Click  EDIT.
    7. Edit the swagger file as given below:

      1. Search for the /{payment-service}/{payment-product} path.
        Under the name: payment-product tag, add the name of the custom payment product to the enum list.

        - name: payment-product
          in: path
          description: "description"
          required: true
          schema:
            type: string
            enum:
              - sepa-credit-transfers
              - instant-sepa-credit-transfers
              - target-2-payments
              - cross-border-credit-transfers
              - new-payment-product-name
              - pain.001-sepa-credit-transfers
              - pain.001-instant-sepa-credit-transfers
              - pain.001-target-2-payments
              - pain.001-cross-border-credit-transfers

      2. Search the swagger file for paymentProduct, under the parameters section. Add the name of the payment product as shown in the step above.

        To remove support for a certain payment product that is supported by the solution by default, remove the name of the particular payment products from the enum values under the sections discussed in step i and ii.

    8. Modify the Swagger definition according to your requirements and click  UPDATE CONTENT.

    9. In the confirmation message box, click  SAVE.

  2. According to the payment-service and payment-product chose, the requests are as follows:

    • The above initiation request may contain the TPP-Brand-Logging-Information header. This is an optional header, which can be used by TPPs to inform the ASPSP about the brand used by the TPP towards the PSU. This information is meant for logging entries to enhance communication between ASPSP and PSU or ASPSP and TPP.

    The header parameter, TPP-Explicit-Authorisation-Preferred returns a boolean value.

    falseIf "TPP-Explicit-Authorisation-Preferred: false", the authorisation flow is implicit. When the authorisation is implicit, The TPP generates the authorisation URL to authorise a particular payment. The TPP uses the well-known URL in the response of the payment initiation.
    trueIf "TPP-Explicit-Authorisation-Preferred: true" , the authorisation flow is explicit. When the authorisation is explicit, the TPP generates the authorisation URL to authorise a particular payment. The TPP uses the well-known URL upon initiating an authorisation for payment when invoking POST /{payment-service}/{payment-product}/{paymentId}/authorisations API resource.

    For more information on authorisation, see Authorise the payment.

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

Users can call the following API resources once the PSU initiates the payment.

 Click here to find the consent related API calls that can be invoked after the paymen-initiation...

GET /{payment-service}/{payment-product}/{paymentId}/status - Payment Initiation status request

The TPP checks the status of a particular payment-initiation request using the sample request given below:



Step 10 - Authorise the payment

WSO2 Open Banking 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,

  1. ASPSP creates authorization sub-resources after the payment consent is received
  2. ASPSP replies with the well-known configuration of the Identity and Access Management module in the links section of the response
  3. TPP generates the authorization URL using the well-known URL
  4. PSU goes through the authorisation flow with that authorisation URL

Explicit authorisation

In this approach,

  1. TPP initiates the authorization flow by invoking the POST /{payment-service}/{payment-product}/{paymentId}/authorisations API resource
  2. At this point, the ASPSP creates authorization sub-resources and reply with the well-known configuration of the Identity and Access Management module in the links section of the response
  3. TPP has to generate the authorization URL, which the PSU uses to go through the authorization flow later
 Click here to see how it is done...

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.

Users can call the following API resources once the PSU authorises the payment.

 Click here to find the consent related API calls that can be invoked after the paymen-initiation...

GET /{payment-service}/{payment-product}/{paymentId}/authorisations - Get payment authorisation subresource's request

The TPP can invoke this API resource to get all the authorisation sub-resources that have been created. Sample request and response looks as follows:

GET /{payment-service}/{payment-product}/{paymentId}/authorisations/{authorisationId} - Read the SCA status of the authorisation request

TPP can check the SCA status of a particular subresource that was created when authorising a payment. Sample request and response look as follows:

  • Authorisation URL

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 authorisationThe response the TPP gets when initiating a payment.
    Explicit authorisationThe 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:

    Sample URL Format
    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:

    ParameterDescription

    scope

    		This is the reference to the consent resource for account access. It is in the form of pis:<consentId>
    response_typecode is recommended.
    redirect_uriThe TPP's URI that the OAuth2 server redirects the PSU's user agent after the authorisation.
    statePrevents 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_idAs 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 redirects you to the Consent page.

  • 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 11 - Retrieve payment information/ status

This is only available as a WSO2 Update from WSO2 Open Banking Identity Server Level 2.0.0.227  and WSO2 Open Banking API Manager Level 2.0.0.215 onwards. For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

Before you begin,

  1. Update the following files with the files in the latest update level:
    • dynamic-endpoint-insequence-1.3.6.xml insequence file
    • OpenAPI File
  2. Redeploy the NextGenPSD2XS2A API.
All the following endpoints need a user access token to retrieve payment information.

GET /payments/{payment-product}/{paymentId}

  • This response should be constructed by the core banking back end.
  • The transactionStatus property shows the status of the real payment at the time the request arrives at the bank backend.
  • The response to the request must comply with the response specified in the specification.

GET /bulk-payments/{payment-product}/{paymentId}

  • This response is constructed by the core banking back end.
  • The transactionStatus property shows the status of the real payment at the time the request arrives at the bank backend.
  • The response to the request must comply with the response specified in the specification.

GET /periodic-payments/{payment-product}/{paymentId}

  • This response is constructed by the core banking back end.
  • The transactionStatus property shows the status of the real payment at the time the request arrives at the bank backend.
  • The response to the request must comply with the response specified in the specification.

GET /{payment-service}/{payment-product}/{paymentId}/status

This request is applicable for instant payments, bulk payments, and periodic payments.

Given below is a sample request for a periodic payment:

  • This response is constructed by the core banking back end.
  • The transactionStatus property shows the status of the real payment at the time the request arrives at the bank backend.
  • The response to the request must comply with the response specified in the specification.

Step 12 - Cancel a payment

This is only available as a WSO2 Update from WSO2 Open Banking Identity Server Level 2.0.0.227  and WSO2 Open Banking API Manager Level 2.0.0.215 onwards. For more information on updating WSO2 Open Banking, see Updating WSO2 Products.

Before you begin,

  1. Update the following files with the files in the latest update level:
    • dynamic-endpoint-insequence-1.3.6.xml insequence file
    • OpenAPI File
  2. Redeploy the NextGenPSD2XS2A API.
  • There are three types of payments.
    • Instant payments
    • Bulk payments
    • Periodic payments
  • Only bulk payments and periodic payments can be cancelled.
  • The bank should decide whether the payment cancellation needs authorization or not.

DELETE /{payment-service}/{payment-product}/{paymentId}

To cancel an already submitted payment

  • This will go to the core banking backend and respond accordingly.
  • Successful response code will be either 204 or 202. This is decided by the bank.
  • If you get 204 as the response code, it indicates that the bank does not need authorization to cancel this payment. Therefore, the payment status must be updated by the bank as CANC. The consent status will be updated as CANC.
  • If you get 202 as the response code, it indicates that the bank needs the authorization to cancel this payment. Therefore, the payment status must be updated by the bank as ACTC. The consent status will be updated to ACTC.

Sample DELETE request for a bulk payment cancellation without authorization is given below:

If the bank decides not to require an authorization to cancel the payment, the response will be a 204 response code with no response body. The payment cancellation flow will end from there and the payment will be cancelled.

Sample DELETE request for a bulk payment cancellation with authorization is given below:

  • If the bank requires an authorization to cancel the payment, the core banking backend will return a 202 response code and the body must comply with the specification.

  • The transactionStatus property must be ACTC.

If the bank returns 202 with the above payload for the DELETE request, the POST /{payment-service}/{payment-product}/{paymentId}/cancellation-authorisations request must be sent to create an authorization resource for the cancellation. This is indicated in the response of the DELETE request in the startAuthorisationWithPsuIdentification property. This request requires an application access token. 
A sample POST cancellation authorisations request for bulk payments type is given below:
If the POST cancellation-authorisations request is successful, the TPP should send the authorization request as follows to inform the bank to cancel the payment. Then the bank displays a page similar to the consent page asking the PSU to approve or deny the cancellation authorization.
https://localhost:9446/oauth2/authorize/?scope=pis:<payment_id>&response_type=code&redirect_uri=<redirect_uri>&state=55e9d72a-218c-44bb-824e-cf0d61c3fdb1&code_challenge_method=S256&client_id=<client_id>&code_challenge=re6uXq06M40gS82XcmUM6s9SQVTxtY5bLSYCNLuS1XE
Given below is a sample page for cancellation authorization for bulk payment type: 
  • If the PSU proceeds to the cancellation by selecting Confirm,
    • The payment cancellation will be submitted to the core banking back end
    • It will be cancelled by the bank.
  • If the PSU selects Deny,
    • The cancellation flow will end without submitting the payment cancellation
    • The payment will not be cancelled.