Payment Initiation

Sign up as a TPP user

1. Navigate to the API Store while signed in as a TPP user.

2. Click the Sign Up link at the top-left and navigate to the sign-up screen.  

3. Provide the requested details as follows:

   1. Generic details

      Field	Description
      Username/Email	The username/email with which the TPP user signs in to the API Store.
      Retype Password	This prevents the TPP user from accidentally setting an incorrect password.
      Password	The password with which the TPP user signs in to the API Store.
      Last Name	The last name of the TPP user.
      First Name	The first name of the TPP user.

   2. 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 under which the TPP is registered.
      Company Registration Number	The identifier issued at the TPP registration.
      Address Line 1	The first line of the TPP address.
      Address Line 2	The second line of the TPP address.
      City	The city in which TPP is located.
      Postal Code	The postal code of the TPP's geographical location.
      Country	The country in which TPP is located.

   3. Competent Authority registration details

      Field	Description
      Competent Authority	The regulatory body that authorizes and supervises the open banking services delivered by the TPP.
      Competent Authority Country	The country of the competent authority that authorized 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	The URL of the page that has the list of organizations authorized by the given competent authority.
      Open Banking Roles	This 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 be authorized by 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 the PISP, indicate whether or not the TPP is authorized 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 or not the TPP has applied for registration.

4. Agree to the terms and conditions by selecting the check box.

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

Approve the TPP user

1. Navigate to the Admin Portal  while signed in as an Approver user.

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

3. Click Start to start the approval process.

4. Select Approve and click Complete. The TPP user can now sign in to the API Store.

Sign-in as a TPP user

1. Navigate to the API Store while signed in as a TPP user.

2. Click Sign In and navigate to the sign in screen.

3. Enter the username and password you entered at user sign up.

4. Click Sign In. The API Store home screen is displayed along with the APIs. Remain in the API Store to create an application.

Create an application

1. Sign in as a TPP user, and then click Applications on the API Store.

2. Click Add Application.

3. Enter application details:

   Field	Description
   Name	The application name.
   Per Token Quota	This determines the maximum number of API requests accepted within a given duration.
   Description	This describes the purpose of the application.

4. Click Add. The application is created. Remain on the same page to generate application access tokens.

Subscribe to APIs

1. Navigate back to the API Store while signed in as a TPP user.

2. Click APIs.

3. Select the Payment API version v1.1.

4. Select the application you created above.

5. Set the throttling policy to Unlimited.

6. Click Subscribe.

Create the certificates

1. While signed in as a TPP user, create a keystore file by issuing the command below. Make sure that you update the following placeholders:  

1. alias: A preferred alias for the keystore file  

2. preferred-filename: A preferred name for the keystore file

   keytool -genkey -alias <<alias>> -keyalg RSA -keystore <<filename>>.jks

2. Convert the keystore from the jks format to PKCS12. Make sure you update the following placeholders:

   1. keyStoreName: This is the name of the keystore.

   2. PKCS12FileName: This is the name of the keystore in the PKCS12 format.

      keytool -importkeystore -srckeystore <<keystoreStoreName>>.jks -destkeystore <<PKCS12FileName>>.p12 -deststoretype PKCS12

3. Create the application certificate (.pem) file using the keystore in the PKCS12 format, e.g. tpp.p12. Make sure you update the following placeholders:

   1. PKCS12FileName: This is the name of the keystore in the PKCS12 format.

   2. PublicCertPem: This is the name of the application certificate that is created in the .pem format.

   3. PrivateCertPem: Private certificate that can be used to sign the requests.

      public certificate : - openssl pkcs12 -in <PKCS12FileName>.p12 -nokeys -out <PublicCertPem>.pem
      
      private certificate :- openssl pkcs12 -in <PKCS12FileName>.p12 -nodes -nocerts -out <PrivateCertPem>.pem

4. Generate the fingerprint of the certificate using the command below:

   keytool -list -v -keystore <>.jks

Request access keys

1. While signed in as a TPP user, click either of the following on the application details page:

1. Production Keys to generate access tokens in the production environment.

2. Sandbox Keys to generate access tokens in the sandbox environment.

2. Provide the requested details as described below:

   Field	Description
   Grant Types	These determine the credentials that are used to generate the access token. There are six grant types available in WSO2 Open Banking: Refresh Token: This renews expired access tokens. 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 authorization 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 uppercase only, no separator) hyphen-minus "-" PSP identifier (authorization number as specified by NCA)
   Callback URL	The URL used by the AISP/PISP to receive the authorization code sent from the Account Servicing Payment Service Provider (ASPSP), e.g. the bank. The authorization code can be used later to generate an OAuth2 access token.
   Application Certificate	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. A request to approve the token generation is sent to the Approver user.

4. Click Generate Keys if you generated sandbox keys. The consumer key and consumer secret are generated.  

Approve production key generation

1. Navigate to the Admin Portal  while signed in as an Approver user.

2. Click Tasks > Application Registration.

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

4. Click Start to start the approval process.

5. Select Approve and click Complete.

6. Navigate back to the API Store and click Applications.

7. Click View of the application that you created to navigate to the application details page.

8. Click on the Production Keys tab and observe the generated keys: the consumer key and the consumer secret.

Generate an application access token

1. While signed in as a TPP user, extract the fingerprint of the certificate created above.

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

   {
     "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> 

3. Issue the following cURL command in a command prompt. Make sure you update the placeholders with the relevant values.

   curl -v POST -H "Content-Type: application/x-www-form-urlencoded;charset=ISO-8859-1" -k -d "grant_type=client_credentials&scope=payments+openid&client_assertion_type=urn%3Aietf%3Aparams%3Aoauth%3Aclient-assertion-type%3Ajwt-bearer&client_assertion=<<pass the signed key generated in the above>>&redirect_uri=<<The callback URL of your application>>" https://<<OB_HOST>>:8243/token/

   The access token is generated.

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

Invoke the Payment Initiation API

1. Navigate back to the API Store while signed in as a TPP user.

2. Click APIs.

3. Select the PaymentAPI v1.1 API.

4. The Berlin flow supports 3 payment types:

   1. Single Payment Initiation

   2. Bulk Payment Initiation

   3. Periodic Payment Initiation

5. The above are under any of the following 4 payment product types:

   1. Sepa-credit-transfers

   2. Instant-sepa-credit-transfers

   3. Target-2-payments

   4. Cross-border-credit-transfers

Single payment initiation

1. Click the POST/bulk-payments/{payment-product} resource.

2. Use one of the above payment product types as the payment-product path parameter. For example, Sepa-credit-transfers.

3. Provide values for the following mandatory header parameters:

   Content-Type : application/json
   
   X-Request-ID: A UUID (eg: 70561774-09ee-447d-8a5e-9b0c0b713396)(use an unique value for each API call)
   
   Authorization: The user access token you created in the Generate User Access Token section. Use the Bearer:<< access token>> format.
   
   PSU-IP-Address
   
   Date  : (eg :Sat, 15 Sep 2018 15:01:16 IST )

4. Use the following as the body:

   {
        "instructedAmount": {
        "currency": "EUR",
        "amount": 123.50
        },
        "debtorAccount": {
        "iban": "DE40100100103307118608"
        },
        “creditorName": "Merchant123",
        "creditorAccount": {
        "iban": "DE02100100109307118603"
        },
        "remittanceInformationUnstructured": "Ref Number Merchant"
     }

5. Click Try it out!. The API response will bear the PaymentId and TransactionStatus.

Bulk payment Initiation

1. Click the POST/payments/{payment-product} resource.

2. Use one of the above payment product types as the payment-product path parameter. For example, Sepa-credit-transfers.

3. Provide values for the mandatory header parameters, similar to step 3 in the previous section.

4. Use the following as the body:

   [
       {
         "instructedAmount": {
        "currency": "EUR",
        "amount": 123.50
         },
         "debtorAccount": {
        "iban": "DE40100100103307118608"
         },
         "creditorName": "Merchant123",
         "creditorAccount": {
        "iban": "DE02100100109307118603"
         },
         "remittanceInformationUnstructured": "Ref Number Merchant"
       },
   
       {
   
         "instructedAmount": {
        "currency": "EUR",
        "amount": 250.50
         },
         "debtorAccount": {
        "iban": "DE40100100103307764533"
         },
         "creditorName": "Merchant124",
         "creditorAccount": {
        "iban": "DE02100100109307118603"
         },
         "remittanceInformationUnstructured": "Ref Number Merchant"
       }
    ]

5. Click Try it out!. The API response will bear the PaymentId and TransactionStatus.

Periodic payment initiation

1. Click the POST/periodic-payments/{payment-product} resource.

2. Use one of the above payment product types as the payment-product path parameter. For example, Sepa-credit-transfers.

3. Provide values for the mandatory header parameters, as in step 3 in the previous section.

4. Use following as the body:

   {
      "instructedAmount": {
    "currency": "EUR",
    "amount": 123
      },
      "debtorAccount": {
    "iban": "DE40100100103307118608"
      },
      "creditorName": "Merchant123",
      "creditorAccount": {
    "iban": "DE23100120020123456789"
      },
      "remittanceInformationUnstructured": "Ref Number Abonnement",
      "startDate": "2018-03-01",
      "executionRule": "latest",
      "frequency": "EVERY_TWO_WEEKS",
      "dayOfExecution": "01"
   } 

5. Click Try it out!. The API response will bear the PaymentId and TransactionStatus.

Invoke the /authorize API

In this step, the TPP redirects the bank customer to authenticate and approve/deny application-provided consents on behalf of the bank customer.

1. Get the well-known configuration endpoint returned from above initiation call response as the scaOAuth value in the _links response object. Invoke that endpoint and get the Authorize API URL value from the response.

2. Run the following in a browser to prompt the invocation of the Authorize API API. Make sure you update the placeholders with the relevant values.

   https://<<OB_HOST>>:8243/authorize/?response_type=<<This can be code or code id_token>>&client_id=<<the client-id of your application>>&scope=payments+openid+PIS:<paymentId>&redirect_uri=<<The Callback URL of your application>>&state=YWlzcDozMTQ2&prompt=login&nonce=<<nonce value>>&code_challenge_method=<<code challenge method>>&code_challenge=<<code challenge>>

3. Once you pass this call, you are directed to a login page. Log in with the credentials of a user having a subscriber role.

4. If a secondary factor is required, e.g., SMSOTP, provide the relevant values.

5. Upon successful authentication, the user is redirected to the consent management page.

6. Upon providing consent, an authorization code is generated.

Invoke the PaymentAPI to get transaction status

GET payment status

1. This retrieves the status of a payment initiation.

2. Click either of the following API resources relevant to the payment resource you invoked to generate the PaymentId in Invoke the Payment Initiation API.

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

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

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

3. Give the path parameters with the relevant payment-product type used and the PaymentId that you generated.

4. Provide values for the following mandatory header parameters.

   Content-Type: application/json
   
   X-Request-ID: A UUID (eg: 70561774-09ee-447d-8a5e-9b0c0b713396) (use a unique value for each API call)
   
   Authorization: The user access token you created in the Generate User Access Token section. Use the Bearer:<< access token>> format.
   
   Date: (e.g. Sat, 15 Sep 2018 15:01:16 IST)

5. Click Try it out!. The API response will bear the TransactionStatusof the payment initiation.

GET payment request

1. This retrieves the content of an initiated payment object.

2. Click either of the following API resources relevant to the payment resource you invoked to generate the the PaymentId in Invoke the Payment Initiation API.

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

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

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

3. Give the path parameters with the relevant payment-product type used and the PaymentId that you generated.

4. Provide values for the following mandatory header parameters.

   Content-Type: application/json
   
   X-Request-ID: A UUID (eg: 70561774-09ee-447d-8a5e-9b0c0b713396) (use a unique value for each API call)
    
   Authorization: The user access token you created in the Generate User Access Token section. Use the Bearer:<< access token>> format.
    
   Date: (e.g. Sat, 15 Sep 2018 15:01:16 IST)

5. Click Try it out!. The API response will bear the content of  the requested payment object with its TransactionStatus.