Payment Initiation API for UK

This document explains the flow of the Payment Initiation API by OBIE. The API endpoints described here allow a PISP to: 

• Register a payment-order consent.
• Optionally confirm available funds for a payment-order (domestic and international immediate payments only).
• Subsequently, submit the payment-order for processing.
• Optionally retrieve the status of a payment-order consent or payment-order resource.

Basic flow

The diagram below shows the basic payment flow (using the Payment APIs) for all payment-order types:

PSU requests the PISP to process a transaction. The consent is between the PSU and the PISP. The PISP connects to the ASPSP that services the PSU's payment account and requests the ASPSP to initiate the transaction, a payment-order consent is created. The PISP requests the PSU to authorise the consent. The ASPSP may carry this out by using a redirection flow or a decoupled flow.

1. In a redirection flow, the PISP redirects the PSU to the ASPSP.
   1. The redirect includes the ConsentId generated in the previous step.
   2. This allows the ASPSP to correlate the payment order consent that was setup.
   3. The ASPSP authenticates the PSU.
   4. The PSU selects the debtor account at this stage (if it has not been previously specified).
   5. The ASPSP updates the state of the payment order consent resource internally to indicate that the consent has been authorised.
   6. Once the consent has been authorised, the PSU is redirected back to the PISP.
2. In a decoupled flow, the ASPSP requests the PSU to authorise consent on an authentication device that is separate from the consumption device on which the PSU is interacting with the PISP.
   1. The decoupled flow is initiated by the PISP calling a back-channel authorisation request.
   2. The request contains a 'hint' that identifies the PSU paired with the consent to be authorised.
   3. The ASPSP authenticates the PSU
   4. The PSU selects the debtor account at this stage (if it has not been previously specified)
   5. The ASPSP updates the state of the payment order consent resource internally to indicate that the consent has been authorised.
   6. Once the consent has been authorised, the ASPSP can make a callback to the PISP to provide an access token.

 Then the PSU approves the consent. The PISP may optionally invoke the following APIs during the flow:

• Confirm available funds for a payment-order - Using an access token of the Client Credentials grant type.
• Retrieve the status of a payment-order consent or payment-order resource - Using an access token of the Authorization Code grant type.

Payment Initiation Service in WSO2 Open Banking

The flow consists of 3 components:

1. Payment initiation flow

Generate application access token

• The PISP requests the ASPSP for an application access token. This call targets the Gateway in API Management module.
• There, the APIM Gateway validates the PISP’s certificates using Mutual TLS authentication and forward the request to the IAM module.
• The OAuth2 Framework in the IAM module performs further validation and provides the PISP with an application access token in the Client Credentials grant type.

Initiate payment-order consent

• The PISP communicates with the ASPSP using the Payment Initiation API available in the WSO2 Open Banking solution.
• PISP sends another request to the ASPSP to initiate a payment-order, this request contains the application access token generated in the previous step. 
• This request targets the WSO2 API Management module in the WSO2 Open Banking solution. 
• The following handlers in the API Management module will perform the given validations:
• Signature Validation Handler:  In the request, the header of the payload contains a signature. This is a detached signature, which means the encoded signature values are not attached to the payload. The Signature Validation handler validates the signature.
• Request schema validation Handler: Validates the request against the respective(Payments) Swagger file. For example, mandatory header, payload fields, pattern matching for fields.
• Consent Enforcement Handler: Forwards the request to the Consent Management module for validation.
•  The back end call of the initiation request is then redirected to the Consent Management module in WSO2 Identity and Access Management where a unique UUID for the consent (Consent Id) is generated. PISP uses the Consent Id to refer to the consent resource to check its status.

2. Payment order consent authorisation flow

• PISP sends the authorisation request and this will be captured from the Authorisation endpoint in the API Management module.
• The request details are then passed to the IAM module. 
• The Request Object Validator in WSO2 OB IAM - Identity Framework validates the request object and its claims, and share the validation results.
• These details are stored in cache against a session data key. 
• The session data key is shared with the PISP in an authentication endpoint URL. 
• The PISP needs to redirect the PSU to this URL.
• The PSU uses authentication URL to log in to the authentication endpoint.
  • Based on the authenticators that the ASPSP has configured (basic authentication or two-factor authentication), the PSU needs to provide the relevant values. Upon successful authentication, the PSU is redirected to the Consent Management page.
  • When the Shareable Accounts API is invoked a list of bank accounts that belong to the PSU is retrieved. This list is displayed in the Consent Management page mentioned above. 

• When retrieving account details from bank’s back end, the authorizationMethod field in the response specifies how many PSUs must authorise the consent. Unless all the PSUs authorise the consent a transaction will not proceed in such a scenario.

  • In a Single Authorisation scenario, the value of authorizationMethod is single. 
  • In a Multiple Authorisation scenario, the value of authorizationMethod is multiple. 
  • Now, the PSU selects the account(s) and authorise the consent.
  • The Consent Management module updates the consent details and persist them in a database.
  • The Authentication endpoint invokes the Response Type Handler and it stores a custom scope against the access token with the Consent Id. This newly added scope provides necessary details to submit a valid payment.
  • Then the IAM module generates the authorization code and share it with the PISP through the redirect URL.

3. Payment submission flow

Generate user access token

• The PISP requests for a user access token using the generated authorisation code. This call targets the Gateway in API Management module.
• There, the APIM Gateway validates the PISP’s certificates using Mutual TLS authentication and forward the request to the IAM module.
• The OAuth2 Framework in the IAM module performs further validation and provides the PISP with the user access token.

Confirm funds

• For Domestic immediate, international immediate and international scheduled (immediate debit) payment-order types there is an optional step of confirming funds before processing the transaction.
• PISP requests the ASPSP to confirm funds on a payment order consent resource. 
• ASPSP can only respond to a funds confirmation request if the payment order consent resource has an Authorised status. 

Submit payment

• The PISP makes another API call to the published Payment Initiation API in the WSO2 API store to submit payment.
• The Consent Enforcement Handler in the API Management module forwards the request to the IAM module. 
•  The Consent Validation module inside IAM validates the following:
  • Maximum Instructed Amount that can be allowed
  • Maximum future date on a scheduled-payment
  • Supported Frequency pattern of the domestic-standing-order   
• If the status of the consent is Authorised.
• Consent is valid/not expired.
• If the permissions in the initiation request and submission request are the same.  
• Published API version against the requested API version, as the specification allows cross-version accessing.
• Business Validations: For example, validate sort code pattern for an account number, validate certain value combinations, validate risk section, validate dates for standing orders/scheduled payments by making sure they’re future dated
• Cut off date time validations: ASPSP specifies a certain time period to allow requests. For the requests made outside of the given time periods, the ASPSP may decide to either reject or process the requests later.
• Payment restrictions : 
• The Consent Validation module sends details regarding single/multiple authorisation in a header as mentioned in Integrating with the Core Banking System for UK - Payment API.
• Then the API Management module will request bank backend through synapse in-sequence to process the transaction.
• Finally, the results of the payment submission is shared with the PISP.

Endpoints

Once you deploy the Payment Initiation API, you can access payment information via following API endpoints: