02 - Initiate a Payment

Description

For the purpose of carrying out a payment initiation with the XS2A APIs, it is necessary to establish a consent between the TPP, the PSU and the ASPSP. In order to do that, comdirect offers two different transaction flows. One follows a Redirect OAuth2 approach, the other one follows a Decoupled approach.

Redirect OAuth2

In this approach, the PISP has to proceed with an OAuth2 authorization. The consent is established and validated thanks to a redirection of the PSU towards the ASPSP Authentication platform.
See How to Perform a Strong Customer Authentication for details.

Note that to access payment resources, you don't need to provide an access token in requests if the payment has been initiated through a redirect Oauth2 workflow

Decoupled

The decoupled approach is similar to the redirect one. The difference is that the ASPSP asks the PSU to authenticate e.g. by sending a push notification with transaction details to a dedicated mobile app or via any application or device independent from the online banking frontend.
In difference to the redirection flow, there is no impact on the PSU/TPP interface during the technical processing.
See How to Perform a Strong Customer Authentication for details.

Decision matrix : on POST {payment-service}/{payment-product}
Request Headers Response Headers
TPP-Explicit-AuthorisationPreferred PSU-ID and PSU-ID-Type TPP-Redirect-Preferred TPP-Decoupled- Preferred ASPSP-SCA-Approach (Response from ASPSP) Explanation
true Decision will be done on POST authorisations API
false/not provided not provided true/false/not provided true/false/not provided REDIRECT

provided

Currently supported PSU-ID-TYPE: "retail" as default value. "" is also accepted.

 true false/not provided REDIRECT
true true REDIRECT / DECOUPLED 1. Decoupled workflow is the default process, if PSU is eligible.
2. If PSU is not eligible for decoupled workflow, DECOUPLED will be provided.
false/not provided true/false/not provided REDIRECT / DECOUPLED 1. Decoupled workflow is the default process, if PSU is eligible.
2. If PSU is not eligible for decoupled workflow, DECOUPLED will be provided.
Decision matrix : on POST authorisations
Request Headers Response Headers
PSU-ID and PSU-ID-Type TPP-Redirect-Preferred TPP-Decoupled-Preferred ASPSP-SCA-Approach(Response from ASPSP) Explanation
Not provided true/false/not provided true/false/not provided REDIRECT

provided

Currently supported PSU-ID-TYPE: "retail" as default value. "" is also accepted.

 true false/not provided REDIRECT
true true REDIRECT / DECOUPLED 1. DECOUPLED workflow is the default process, if PSU is eligible.
2. If PSU is not eligible for decoupled workflow, DECOUPLED will be provided.
false/not provided true/false/not provided REDIRECT / DECOUPLED 1. DECOUPLED workflow is the default process, if PSU is eligible.
2. If PSU is not eligible for decoupled workflow, DECOUPLED will be provided.

Payment Initiation

Initiate Payment Resource
POST /berlingroup/v1/{payment-service}/{payment-product}

Creates a payment resource at the ASPSP for a given payment service and product. Specificities for this API and available services and products are listed in the dedicated HowTo.

Create an authorisation resource on a given payment
POST /berlingroup/v1/{payment-service}/{payment-product}/{paymentId}/authorisations

Create an authorisation sub-resource of the payment resource and start the authorisation process.

The usage of this access method is only necessary if the TPP has asked to start the authorisation process separately from the payment initiation (using the “TPP-Explicit-Authorisation-Preferred” Header).

Authorization request
GET /berlingroup/authorization/authorize/{authorisation-id}

Requests an authorisation from a PSU following the OAuth2 protocol. Details of the authentication workflow and user interfaces are described in the dedicated HowTo section.
Our specificities regarding the OAuth2 protocol are listed below.

response_type : code
code_challenge_method : S256

After successful authorisation, the user will be redirected to the redirect URI provided in the request with the following parameters :

https://your_redirect_uri?code=authorization_code&state=test

Payment with no IBAN / Combined Service.

The PIS with no IBAN / Combined Service is a feature of the AIS consent. It allows a PISP to retrieve the list of account through an AIS request when it should not be able to do so.

Thanks to this feature, a PISP can offer a smooth PIS workflow where the PSU select a debtor IBAN from his/her account list instead of entering the IBAN manually.

Prerequisites

TPPs with only the PISP role can only use the global consent scope availableAccounts: allAccounts.

An AIS Combined Service Consent can be one-off.

The property combinedServiceIndicator has to be set to true in the body of the request.

The combined service AIS consent is not supported for a multi authorization payment.

Specific BerlinGroup Implementation on Payment Initiation Service

For specific BerlinGroup Implementation on the Payment Initiation Service, please refer to specific implementation How To.

Enable "on this page" menu on doc section
On

01 - Manage Consents for Account Information Service

Description

To access all AIS APIs, it is necessary to establish a consent between the TPP, the PSU and the ASPSP. In order to do that, comdirect offers two different transaction flows. One follows a Redirect OAuth2 approach, the other follows a Decoupled approach.

Redirect OAuth2

In this approach, the AISP has to proceed with an OAuth2 authorization in order to retrieve a time-limited access token.
This access token is mandatory to access all the AIS PSD2 APIs. It is associated to the consent established and validate thanks to a redirection of the PSU towards the ASPSP Authentication platform.
See How to Perform a Strong Customer Authentication for details.

Decoupled

The decoupled approach is similar to the redirect one. The difference is that the ASPSP asks the PSU to authenticate e.g. by sending a push notification with transaction details to a dedicated mobile app or via any other application or device which is independent of the online banking frontend.
In difference to the redirection flow, there is no impact on the PSU/TPP interface during the technical processing and no access token has to be retrieved after the consent validation.
See How to Perform a Strong Customer Authentication for details.

Decision matrix : on POST /berlingroup/v1/consents
Request Headers Response Headers
TPP-Explicit-AuthorisationPreferred PSU-ID and PSU-ID-Type TPP-Redirect-Preferred TPP-Decoupled- Preferred ASPSP-SCA-Approach (Response from ASPSP) Explanation
true Decision will be done on POST authorisations API
false/not provided not provided true/false/not provided true/false/not provided REDIRECT

provided

Currently supported PSU-ID-TYPE: "retail" as default value. "" is also accepted.

 true false/not provided REDIRECT
true true REDIRECT / DECOUPLED 1. Decoupled workflow is the default process, if PSU is eligible.
2. If PSU is not eligible for decoupled workflow, DECOUPLED will be provided.
false/not provided true/false/not provided REDIRECT / DECOUPLED 1. Decoupled workflow is the default process, if PSU is eligible.
2. If PSU is not eligible for decoupled workflow, DECOUPLED will be provided.
Decision matrix : on POST authorisations
Request Headers Response Headers
PSU-ID and PSU-ID-Type TPP-Redirect-Preferred TPP-Decoupled-Preferred ASPSP-SCA-Approach(Response from ASPSP) Explanation
Not provided true/false/not provided true/false/not provided REDIRECT

provided

Currently supported PSU-ID-TYPE: "retail" as default value. "" is also accepted.

 true false/not provided REDIRECT
true true REDIRECT / DECOUPLED 1. DECOUPLED workflow is the default process, if PSU is eligible.
2. If PSU is not eligible for decoupled workflow, DECOUPLED will be provided.
false/not provided true/false/not provided REDIRECT / DECOUPLED 1. DECOUPLED workflow is the default process, if PSU is eligible.
2. If PSU is not eligible for decoupled workflow, DECOUPLED will be provided.

Consent Establishment

Establish AIS Consent
POST /berlingroup/v1/consents

Creates a consent resource at the ASPSP regarding access to accounts specified in this request. Specificities for this API are listed in the dedicated HowTo.

Create an authorisation resource on a specific consent
POST /berlingroup/v1/consents/{consentId}/authorisations

Creates an authorisation sub-resource of the consent resource and start the authorisation process.

The usage of this access method is only necessary if the TPP has asked to start the authorisation process separately from the consent establishment (using the “TPP-Explicit-Authorisation-Preferred” Header)

Authorisation request
GET /berlingroup/authorization/authorize/{authorisation-id}

Requests an authorisation from a PSU following the OAuth2 protocol. Details of the authentication workflow and user interfaces are described in the dedicated HowTo section.
Our specificities regarding the OAuth2 protocol are listed below.

response_type : code
code_challenge_method : S256

After successful authorisation, the user will be redirected to the redirect URI provided in the request with the following parameters :

https://your_redirect_uri?code=authorization_code&state=test
Access Token Request
POST /berlingroup/v1/token

Requests an access token using the authorization code retrieved from the PSU authorization. This Access Token can be refreshed. The duration of access token is 1 hour, and the duration of refresh token is 180 days.
The token is not required if the consent was established with a decoupled approach.

Consent Management

Retrieve the Consent
GET /berlingroup/v1/consents/{consentId}

The TPP can retrieve the consent resource using the API above.

Retrieve the Consent’s status
GET /berlingroup/v1/consents/{consentId}/status

The TPP can retrieve the consent's status using the API above.

Get the authorisations of a specific consent resource
GET /berlingroup/v1/consents/{consentId}/authorisations

The TPP can retrieve the list of all the autorisations linked to the consent resource using the API above.

Get an authorisation from a specific consent resource
GET /berlingroup/v1/consents/{consentId}/authorisations/{authorisationId}

The TPP can retrieve the status of an autorisation linked to the consent resource using the API above.

Delete a Consent resource
DELETE /berlingroup/v1/consents/{consentId}

The TPP can use this API to terminate a consent.

One-off consents

Submitting a POST /consents request with the property recurringIndicator=false and frequencyPerDay=1 allows you to create a one-off consent.

In this particular case, all AIS accounts access are authorised for a period of 20 minutes

Multiple Consents Service

comdirect offers TPP a Multiple Consents Service that follows the Berlin Group NextgenPSD2 suggested implementation.

This service allows TPP to have multiple valid consents at the same time. This implies that TPPs may have different valid access token for the same PSU.

If this feature is used by the TPP, it is its responsibility to relate the consented data with the proper consent and access token.

The main impact of this service lies in the fact that, in case of a pre-existing and currently valid consent, a newly validated consent creation request will not automatically revoke the pre-existing consent. The TPP is then also responsible of revoking consents that are not used by the PSU anymore.

Specific BerlinGroup Implementation on Account Information Service

For specific BerlinGroup Implementation on the Account Information Service, please refer to the specific implementation How To.

Enable "on this page" menu on doc section
On
blog

Outage // 15.10.2025 from 05:41 AM to 06:57 AM

Dear developers,

we would like to inform you that we had an outage this morning from 05:41AM until 06:57AM.

The problem is solved ,and all services are running again.

We apologize for any inconvenience.

blog

Maintenance Announcement 12.10.2025 - 13.10.2025

Dear developers,

due to maintenance work, we have an expected downtime (for at least limited availability) for all our services (including the API) from 12.10.2025 22:00PM till approximately 13.10.2025 05:00AM .

Subscribe to