DNB Luxembourg S.A

DNB Luxembourg S.A. XS2A (Berlin Group)

Version:  1.13220190215.037.005
State:  Prototyped
Environment: Sandbox
Base URI: https://ubnllull-psd2api-sbx.luxhub.com/bg/v1
Authorization Endpoint: https://ubnllull-cb-sbx.luxhub.com/api/oauth/authorize
Token Endpoint: https://ubnllull-psd2api-sbx.luxhub.com/api/oauth/token
Categories: PSD2
Passport :

Payment Initiation Services (PIS)

The APIs we are exposing for PISP - as for AISP - use the OAuth2 for authorization. The PSU identification, authentication and the signing of payment requests is based on the Strong Customer Authentication (SCA) and it is done in the realm of the bank.

Depending on the bank you would like to integrate with, you have to implement Berlin Group or STET PSD2 API specification.

Below we will show you an example of both types for a simple Payment Initiation Request. For Berlin Group standard, the payment initiation endpoints are separated according to the type of payment product and payment service. As well, additional flows are supported for this standard, namely multiple SCA and signing baskets. These specifics flows are currently out of scope of the present document, but are fully supported by LUXHUB platform. Please refer Berlin Group PSD2 API official documentation for support in this direction.

Berlin Group

This diagram shows the requests to be performed in the case of an API of a bank which uses the Berlin Group specification for Payment initiation.

The requests shown in yellow are explained in details below.

It is to be noted for Berlin Group specifications that the Payment Initiation resource management and life cycle is fully separated from the life cycle and management of the Authorisation resource. Basically the Authorisation resource is used for authorizing the Payment Initiation resource, hence the Authorisation resource endpoints need to be protected by Authorization Code Grant, which involve PSU authentication, whereas Payment Initiation resource can be protected by Client Credentials Grant only. This kind of approach will allow for the Payment Initiation resource, and its status, retrieval by the TPP even before authorization by the PSU. The payment flow will allow to the TPP to retrieve Payment Initiation resource, and dependent entities like Authorisation, before authorization by the PSU. This way, simple management of implicit and explicit authorisation flows can be achieved. Signing Baskets flows will also benefit from the same feature.

Another benefit of this approach is a unified handling of payment flows between Berlin Group specifications and STET, which actually employs exactly the model mentioned above from an authorization perspective, while maintaining a simplified resource representation that does not involve the additional Authorisation resource.

In the example requests below, we will use the sepa-credit-transfer simple payments for illustrating the requests to be made by a TPP for payment initiation.

1. To start, you have to obtain an access token using the client credentials flow. This access token is not related to a PSU’s resources.
  • example request:
curl \
     -H 'Authorization: Basic ' \
     -H 'Content-Type : application/x-www-form-urlencoded' \
     -d 'grant_type=client_credentials&scope=PIS:payment' \
     -X POST 'https://<Token Endpoint>' \
     --cert QWAC-cert.pem --key QWAC-key.pem​

2. The next step is to call the products endpoint to create a new payment resource.

  • example request:

    curl \
         -H 'PSU-IP-Address: "123.123.123.123"' \
         -H 'TPP-Redirect-Preferred: true' \
         -H 'Signature: ' \
         -H 'Authorization: Bearer ' \
         -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
         -H 'Content-Type: application/json' \
         -d '{"endToEndIdentification":"123456-1234-1234-1234567890ab", "debtorAccount":{"iban":"FR7612345987650123456789014","currency":"EUR"}, "instructedAmount":{"currency":"EUR","amount":"30"}, "creditorAccount":{"iban":"FR1420041010050500013M02606","currency":"EUR"}, "creditorName":"SFR","creditorAddress":{"street":"rue blue","buildingNumber":"89","city":"Paris","postalCode":"75000","country":"FR"}, "remittanceInformationUnstructured":"AwesomeTPP"}' \
         -X POST 'https://<Base URI>/payments/sepa-credit-transfers' \
         --cert QWAC-cert.pem --key QWAC-key.pem​

 

3. In the following step, you will have to create an authorization resource for this payment.
  • example request:

    curl \
         -H 'Signature: ' \
         -H 'Authorization: Bearer ' \
         -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
         -H 'Content-Type: application/json' \
         -X POST 'https://<Base URI>/payments/<payment_id>/authorisations' \
         --cert QWAC-cert.pem --key QWAC-key.pem​

 

4. This current step is described from the point of view of a TPP accessing the API of a bank that implemented Berlin Group standard for payments using the concept of “explicit authorisation”. In this concept the authorisation resource has to be created explicitly by the TPP, i.e. by calling the POST endpoint of this resource. This model is more generic and allows as well for multiple SCA flow.

5. There is another model of payment accepted by Berlin Group specification, the so called “implicit authorisation”. In this model, the authorisation resource is created implicitly by the bank together with the payment initiation resource, so there is no need to explicitly call the POST /authorisations endpoint. This model can be applied only for the single SCA flow, where the payment is authorized by a single PSU.

  • Additional details about these two models can be found in the official documentation of Berlin Group.

6. The next step will actually authorize the payment authorisation resource. This is achieved by redirecting the PSU to his bank for SCA.
  • example request:

    curl \
         -X GET 'https://<Authorization Endpoint>?response_type=code&scope=PIS:<consent_id>&client_id=<client_id>&redirect_uri=http%3A%2F%2F127.0.0.1%3A9003%2Fredirect/_payment&state=12345678-1234-1234-1234-1234567890ab&resource=payments/<payment_authorization_id>/ '

 

7. Your application has to retrieve the OAuth2 authorization code. This is achieved by the bank’s SCA redirecting the PSU to the redirect URL defined in your request.
Your application should accept the parameters specified below.
You can try this redirection by pasting the GET request from step 3 into your browser (you have to configure your browser to use the Mock Certificate) while ensuring that your application is listening at the specified redirection URL.
  • example request:

    curl \
         -X GET 'http://127.0.0.1:9003/redirect?code=<authorization_code>'​

 

8. Once you have received the authorization code, you can ask for OAuth2 access and refresh tokens to access the status of the payment initiation.
  • example request:

    curl \
         -H 'Authorization: Basic ' \
         -H 'Content-Type : application/x-www-form-urlencoded' \
         -d 'grant_type=authorization_code&redirect_uri=http%3A%2F%2F127.0.0.1%3A9003%2Fredirect_payment&code=<authorization_code>&scope=PIS:<consent_id>' \
         -X POST 'https://<Token Endpoint>' \
         --cert QWAC-cert.pem --key QWAC-key.pem​

 

9. Your payment initiation request is now authorized and you can check its status by calling the following request
  • example request:

    curl \
         -H 'Signature: ' \
         -H 'Authorization: Bearer ' \
         -H 'X-Request-ID: 12345678-1234-1234-1234-1234567890ab' \
         -H 'Content-Type: application/json' \
         -X GET 'https://<Base URI>/payments/ ' \
         --cert QWAC-cert.pem --key QWAC-key.pem​

Multiple SCA flows

Berlin Group specification for APIs allows supporting multiple SCA for payment initiation (and consent authorization), based on the introduction of an additional entity called Authorisation. There will be such an entity created for each SCA that needs to be performed; the rules for how many SCA needs to be done are specific - per ASPSP, account, etc. - therefore there is a need to communicate to the TPP when it needs to perform additional authorisations. Below flow describes the approach a TPP needs to use in order to implement multi SCA.

It is of note, that multiple SCA can be implemented only by using explicit authorisation resource creation and, for now, only available only from ASPSP implementing Berlin Group API standard.

There is of note an extension to the Berlin Group standard API that is proposed in the diagram below: AUTHORISATION_FINALIZED value can be added by implementing ASPSP to the list of valid values returned after SCA, i.e. when last authorisation resource is signed/authorized by PSU. As such it will be a clear indication for TPP that authorization process is finished; otherwise the TPP has to query the transactionStatus of the payment to know if additional authorisations are required or the existing authorisation have to still be approved by the PSU.

 

 

Note: also see Berlin Group Implementation Guidelines 1.3 sections 5.1.9, 5.8, 6.4.4, 8.3. Most of the banks will have multi SCA implemented for payment initiation services only.

 

 
 

This website uses cookies. By continuing to use our website, you accept the use of these cookies.