GET Accounts

Endpoint: GET /psus/{psuId}/accounts

Base URL: /xs2a/routingservice/services/ob/ais/v3

This endpoint is used to retrieve the list of accounts of the account holder.

Please note: If you want to retrieve account owner name, you need to send ownername=true in PSU registration API.

Data model

Request	Response (click to enlarge)

Consent status reflects the current state of the account holder's approval to access their financial data. The consent can be valid for at most 180 days. The Open Banking Service will provide an http 401 response with error code 123 ‘The PSU consent is expired’ if AIS data is requested after the validity of the consent is expired. You should then request a new consent.

In case of multiple consents for the same bank account, Open Banking Services will choose the consent that will be used to retrieve account data, so you do not need to maintain consent selection logic.

Consent status life cycle

Figure: Consent Status when GET consent/status API is called (click on the picture to enlarge).

Below you can find an explanation of each one of the statuses:

GET Consent Status

Endpoint: GET /psus/{psuId}/consents/{consentId}/status

Base URL: /xs2a/routingservice/services/ob/ais/v3

This endpoint is used to retrieve the status of a consent.  Alternatively, you may use Push notifications functionality.

Data model

Request	Response (Click to enlarge)

The authorisation of consents largely depends on the approach chosen by the account holder's bank:

• In the standard Redirect approach with an implicit start of authorisation, no further endpoint needs to be called. In this case, the account holder’s browser is redirected to the bank, which will handle all authorisation steps. However, banks might also require an explicit start of authorisation for the Redirect Approach. In that case, the endpoint POST Authorisations must be used. 
• In the Decoupled approach, the authorisation must be explicitly started as well, and typically, identification of the PSU is required. Therefore, the Post Identification endpoint must be called.
• For the Embedded approach, data must be added to the authorisation through multiple requests to the PUT Authorisation endpoint.

POST Identification

Endpoint: POST /psus/{psuId}/consents/{consentId}/identification 

Base URL: /xs2a/routingservice/services/ob/ais/v3

This endpoint is used in Decoupled approach to start the authorisation explicitly and identifying the account holder at the bank to enable the Push message to be sent to the user’s device.

The Initiating Party will need to poll for status changes, since the authorisation is done in Decoupled approach and no feedback is provided directly by the ASPSP to the TPP.

Data model

Request	Response

POST Authorisations

Endpoint: POST /psus/{psuId}/consents/{consentId}/authorisations/{authorisationId}

Base URL: /xs2a/routingservice/services/ob/ais/v3

This endpoint is used in 2 approaches

• Embedded approach to start the authorisation and provide the required information according the first step of the embedded authorization flow.
• Redirect approach to start explicit redirect authorisation. Mostly is being used in case of multi-level authorisation or when required by end user's bank.

Data model

Request	Response (click to enlarge)

PUT Authorisations

Endpoint: PUT /psus/{psuId}/authorisations/{authorisationId}

Base URL: /xs2a/routingservice/services/ob/ais/v3

This endpoint is used in Embedded Approach to provide the required information according to the necessary steps driven by account holder's bank.

Data model

Request	Response (click to enlarge)

There are 3 main types of consent flows:

1. Redirect

In the Redirect Approach the browser session of the account holder is redirected from your software to the bank. In that case the bank provides all the pages required for Strong Customer Authentication (SCA). Once the authorisation is complete, the account holder is being redirected back to your software.

2. Decoupled

In the Decoupled Approach no redirection takes place. Instead, the bank notifies the account holder that they need to authenticate themselves, for example using mobile banking app. The authentication is executed by the app. Since this approach is asynchronous, you need to check consent status to know when the authentication process has been finished.

3. Embedded

In the Embedded Approach you have to provide all the screens required for the authentication process and fulfil all necessary steps over the API of the Open Banking Service.

Depending on the consent flow you will need to implement a different sequence of API calls. Please check below sequence diagrams to understand each flow.

You can indicate your preferred SCA method by using PreferredScaMethod (Embedded, Decoupled, Redirect) parameter of POST consent endpoint, but there is no guarantee that the bank will actually use it to authenticate the PSU. 

For faster integration and better user experience we offer the Bank Selection Interface, it will then always become a redirect flow from you to this interface. This interface can be customised with your branding allowing to choose the account holder's bank and handling the complexity of different PSD2 authorization flows, so that you will be able to focus on your product and leave the boring stuff to us. 

The selected flow with which authentication will go through, is being identified by the name of a hyperlink, provided in the response to the POST consent API call.

Redirect Flow

The sequence diagram below is an example of a typical redirect account data flow. Depending on the individual implementation of the bank, the actual flow may differ slightly. The green vertical bars indicates who is responsible for the interaction with the account holder (PSU).

Redirect back to the Initiating Party

Once the account holder finished the interaction with the bank, the session will be redirected back to you. Here, the Open Banking Service appends the Initiating Party Return URL with the Service Name and the consent ID so that the session can be recognised. This enables the Initiating Party to display the correct screen to the PSU.

An example of a return URL is as follows: https://www.example.org/?scope=QUlTOjc1NDQzMTY3
The Initiating Party would need to base64 decode this string : QUlTOjc1NDQzMTY3
The example above results in: {ServiceName}:{paymentId}, i.e. AIS:75443167

Decoupled Flow 

Below is a sequence diagram showing a typical decoupled flow. Depending on the individual implementation of the bank, the actual flow may differ slightly. The green vertical bars indicates who is responsible for the interaction with the account holder.

Embedded Flow 

Below is a sequence diagram showing a typical embedded flow. Depending on the individual implementation of the bank, the actual flow may differ slightly. The green vertical bars indicates who is responsible for the interaction with the account holder.

Flow steering by links

The table below includes every possible step with the corresponding approach. In the response of each request the named link informs about the next request to be sent according to the actual state in the flow.

The Push Notification APIs described in this chapter need to be implemented on the Initiating Party side, if the Initiating Party decides to use them. The Open Banking Service will post notifications to these endpoints.

POST Status

Endpoint: POST /status

Base URL: URL provided by you as part of your onboarding

This API will notify the initiating party about the status of the payment. A different request will be sent for the Payment and Data. More details about the fields can be found in the API reference.

Data model

Request (click to enlarge)	Response
Displaying PaymentDetailedInformation

This page describes the pre-authentication API which can be used to request pre-authentication of the PSU.

Some ASPSP’s support the pre-authentication of the PSU. This will allow a PSU to authenticate once for a specific TPP after which the pre-authentication can be used in subsequent payments/consents requests by the TPP (The same PsuId should be used in those requests so that the pre-authentication can be connected). Each individual request still needs to be authorized by the PSU, but authentication is not longer needed. This can speed up the flow for these subsequent payments/consents.

The reach directory indicates which ASPSP’s support this functionality, see the ‘Details’ section of the Reach directory response.

The Open Banking Solution will also arrange a pre-authentication as part of the post payments flow, if mandatory. In which case it will be handled ‘behind the screens’. This pre-authentication API is meant for cases in which the TPP want’s to request the pre-authentication before a payment flows starts, so it becomes a stand-alone pre-authentication request.

Another case in which this API should be used is when ‘PreAuthenticationForEmbedded’ is returned by the post payments/consents API. In this case the pre-authentication is required and cannot be handled ‘behind the screens’.

Pre Authentication status

A pre-authentication has a status. 

Flow example

The flow below gives an example of a stand-alone pre-authentication request, combined with a payment. Notice that in the payment step authentication is no longer required due to the pre-authentication.

POST pre-authentication

Endpoint: POST /psus/{psuId}/pre-authentication

This API starts the pre-authentication request flow.

Data model

Request	Response (click to enlarge)

PUT pre-authentication

Endpoint: PUT /psus/{psuId}/pre-authentication/{preAuthenticationId}

This API is used to update a pre-authentication resource.

Data model

Request	Response (click to enlarge)

Delete pre-authentication

Endpoint: DELETE /psus/{psuId}/pre-authentication/{preAuthenticationId}

This API is used to delete a pre-authentication resource.

Data model

Request	Response
	HTML 204 (No Content, success)

Get pre-authentication status

Endpoint: GET /psus/{psuId}/pre-authentication/{preAuthenticationId}/status

This API is used to get the status of a pre-authentication resource.

Data model

Request	Response

The Push Notification APIs described in this chapter need to be implemented on the Initiating Party side, if the Initiating Party decides to use them. The Open Banking Service will post notifications to these endpoints.

POST Status

Endpoint: POST /status

Base URL: URL provided by you as part of your onboarding

This API will notify the initiating party about the status of the payment. A different request will be sent for the Payment and Data. More details about the fields can be found in the API reference.

Data model

Request (click to enlarge)	Response
Displaying: PaymentDetailedInformation

Payments have different status depending on the actual state of processing: 

• Open
• Authorised
• PartiallyAuthorised
• SettlementIinProcess
• SettlementCompleted
• ReceivedByCreditorBank
• ReceivedOnCreditorAccount
• Cancelled
• CancelledAtTPP
• Error
• Expired
• Pending (The Apsps put the payment in a pending state, this can happen for multiple reasons. This is not a final state, another get payments/status should be made to get an update on the status)

Not all ASPSPs are differentiating between all the status values listed above. The Status PartiallyAuthorised can be given for a payment in multi-authorizations if the first PSU has authorised and there are still authorizations of additional PSUs are outstanding. The Multi-Authorization is an extended service of Accout-to-Account payments.

For some ASPSPs the status of a payment isn’t updated furthermore when the Authorised status is achieved. For most ASPSPs the final status is SettlementCompleted. Information on the final status for payments for given ASPSPs can be retrieved form the Reach API.

Open Banking Services

In the following picture the status values are shown in a state diagram:

Bank Selection Interface

While using the Bank selection interface the following payment status flow is applicable:

GET Payment Status

These endpoints are used to retrieve the status of a payment.

Endpoint: GET /payments/{paymentId}/status

Endpoint: GET /periodic-payments/{paymentId}/status

Endpoint: GET /scheduled-payments/{paymentId}/status

Endpoint: GET /bulk-payments/{paymentId}/status

Data model

Request	Response (click to enlarge)

Example

Request

Address: https://localhost:8443/xs2a/routingservice/services/ob/v3/payments/11376380/status

    HttpMethod: GET

    Headers: {Accept=application/json, Digest=47DEQpj8HBSa+/TImW+5JCeuQeRkm5NMpJWZG3hSuFU=, 
X-Request-ID=de875f27-5eb7-2b3d-bb88-86e0fe0cdf65, Authorization=Bearer ec464ba833a955952646cbc834f4e6b, MessageCreateDateTime=2022-03-24T14:48:16.143Z}

Response

ResponseCode: 200

    Headers: { X-Request-ID=283c264a-3212-4240-a039-01b229fa854f, MessageCreateDateTime=2022-03-24T14:48:16.541Z}
    Payload: {"CommonPaymentData":
    "PaymentStatus": "SettlementCompleted",
    "PaymentId": "11376380",
    "AspspPaymentId": "00015952769469210",
    "AspspId": "10002"
}}

The Payment Process "Bulk payment" allows to send multiple payments at once: individual payments are bundled together into one single transaction. The Bulk Payment is used for processing refunds on PIS payments on the Routingservice. Once the refund is requested by the customer and accepted by the Initiating Party, or initialized by the Initiating Party, the IP can directly use the Refund API for Online Refunds to initiate either a single or up to ten payments on the Routing Service (using the Bulk Payment Interface).

Please also check the Refund Section

The base URL for the Payment Initiation Service API is: /xs2a/routingservice/services/ob/pis/v3

POST Bulk Payments

Endpoint: POST /bulk-payments

This endpoint is used by the Initiating Party to set up payment initiation for an ASPSP.

Example

Example of a bulk payment request body.

{
  "PaymentProduct": [
    "PSD2-SCT"
  ],
  "PaymentProductChangeable": false,
  "PsuData": {
    "AspspId": "20210",
    "AspspProductCode": "string",
    "Country": "FR"
  },
  "CommonPaymentData": {
    "PreferredScaMethod": [
      "Redirect"
    ],
    "DebtorInformation": {
      "Name": "Rob Smith",
      "Agent": "EG8BCROZMX8",
      "Account": {
        "SchemeName": "IBAN",
        "Identification": "DE89370400440532013000",
        "Currency": "EUR"
      }
    },
    "ChargeBearer": "DEBT",
    "Payments": [
      {
        "EndToEndId": "ID-0123456789-A",
        "Amount": {
          "Amount": "123.45",
          "Currency": "EUR"
        },
        "CreditorInformation": {
          "Name": "John Smith",
          "Account": {
            "SchemeName": "IBAN",
            "Identification": "DE89370400440532013012",
            "Currency": "EUR"
          },
          "Agent": "UZWHIKRXVHT",
          "UltimateCreditor": "John Media Shop U"
        },
        "RemittanceInformation": "Remittance Information",
        "RemittanceInformationStructured": {
          "Reference": "Remit-23-43-42",
          "ReferenceType": "structured",
          "ReferenceIssuer": "Reference Issuer"
        }
      },
      {
        "EndToEndId": "ID-0123456789-B",
        "Amount": {
          "Amount": "78.56",
          "Currency": "EUR"
        },
        "CreditorInformation": {
          "Name": "Simon Walker",
          "Account": {
            "SchemeName": "IBAN",
            "Identification": "NL98INGB6709624056",
            "Currency": "EUR"
          }
        },
        "RemittanceInformation": "Remittance Information"
      }
    ]
  }
}