TPP Journey

The information contained in this section is intended to facilitate TPP in the development of applications using the BDSK PSD2 API.

PSD2 API Sandbox enables training and help developers familiarize themselves with methods of accessing data within PSD2 open banking. The API follows the Berlin Interoperability Interface Interoperability Specifications of the Berlin Group and the BISTRA National Market Initiative. The BDSK API can be enriched to expand scope. The current Sandbox implementation and services are based on BISTRA version 1.2. We encourage you to provide feedback in order for us to improve our services by sending an email to apigate@dskbank.bg .

Versions

API name  Version Date for Sandbox Date for production Maintenance
AIS  V1  14.09.2018  14.03.2019  Yes
PIS  V1  14.09.2018  14.03.2019  Yes
COF  V1  14.09.2018  14.03.2019  Yes

 

Developer Portal – on-boarding

  1. Use the GETTING STARTED tab for detailed information. At the bottom of the page you can download complete instructions for the DSK Bank Developer Portal

  2. Sign up now to create an account and get started. It is free to join. Create an account by clicking the button on the top right of the portal. After filling in the required information you will receive an e-mail for successful registration

  3. Log into the Developer Portal by clicking the 'Log in' button on the top right of the portal.

  4. To use the API you have to register your application. Application registration is available after you login. When you register an application, the application is assigned a unique client ID and client secret. You must use the client ID when you call an API that requires you to identify your application by using a client ID, or a client ID and client secret. Check the API description for the details. When creating your new application, give it a name, a description and a redirect URL. To use PSD2 APIs, you also need to add the public part of a QWAC (Qualified Website Authentication Certificate) when registering your application. For this purpose please use the test certificate from here.

  5. Once you've created an app, you need to subscribe to the API you want to develop. Select it from the "API PRODUCTS" section and click on the subscription button and select the application you created in step 4.

  6. After subscribing, you can begin testing.

 

PSD2 API Information 

  • APIs in sandbox are secured with TLS Mutual Authentication. 

  • We do not support JWS client assertion.

  • As part of our implementation we support registration of an application with single oAuth2 redirect URLs. The TPP registers a redirect URL when creating an application on the Developer Portal, however once an application has been created and the Client ID and Client Secret generated it can be changed.

  • Signing the data requests - in this release signing is not used for all API’s endpoints. Signing on application layer will be mandatory on upcoming releases.

  • JSON format is used for services.

  • The API sandbox consists of static mocked data for:

    • Account Information Services (AIS) as defined by article 67 in the PSD2 Directive.

    • Payment Initiation services (PIS) as defined by Article 66 in the PSD2 Directive.

    • Confirmation on the availability of funds (COF) as defined by Article 65 in the PSD2 Directive.

    • PSU data used for creating consent and request an OAuth2 token.

  • API PIS SANDBOX does not provide the ability to perform PSU's SCA tests after initiating a TPP payment.

The approach used for SCA is REDIRECT and after the PSU is redirected to the Bank's authorization site, the action will be taken entirely by the PSU. In the real process, but in the productive environment, after the SCA process is completed, the authorization site will redirect the PSU to the application URL of the TPP application (the URL specified when registering the App in the Developer Portal).

  • The character set is UTF 8 encoded. This specification is only using the basic data elements "String", "Boolean", "ISODateTime", "ISODate", "UUID" and "Integer" (with a byte length of 32 bits) and ISO based code lists.

  • We do not provide a paginated response for GET operations that return multiple records.

  • Max records for the answer are 500.

 

Work with the PSD2 APIs in Sandbox

Authorization for using API

For information about the Authorization process, predefined User Credential used for the developing take a look here:

https://developer.dskbank.bg/authorization

The callback URL you registered in the application MUST match the redirect_uri you pass as query parameter in this process.

API name 

Endpoint

Scope

OAuth2 – Sandbox

https://identity.dskbank.bg/connect/authorize

Depends on the selected API

API AIS v1 – Sandbox

https://apigate.dskbank.bg/dsk/sb/v1/accounts

Scope: ais.sandbox

API PIS v1 – Sandbox

https://apigate.dskbank.bg/dsk/sb/v1/payments

scope: pis.sandbox

API COF v1 – Sandbox

https://apigate.dskbank.bg/dsk/sb/v1/funds-confirmations

scope: cof.sandbox

 

Call the API endpoint

To be able to use and connect to the API there are requirements: 

  • In the request header Authorization with a value of Bearer (also called token authentication) followed by a string of characters. This value WILL be validated in ALL flows in the sandbox.
  • X-Request-ID must be unique per request. This is a mandatory header throughout the API.
  • Date must be added to request header. This is a mandatory header throughout the API.

Use API’s swagger for other information.

Error Codes and Responses

Every response returned by APIs has a response code. Response codes can be used to check the result of the requests e.g. was the request successful or did it fail.
The following table shows the return codes used by API.

Status code

Description

200 OK

GET - Request was fulfilled. Also used for COF POST

201 Created 

POST Response code where Payment Initiation or Consent Request was correctly performed. 

204 No Content 

DELETE Response code where a consent resource was successfully deleted. The code indicates that the request was performed, but no content is returned.

400 Bad Request 

Validation error occurred. This code will cover malformed syntax in request or incorrect data in payload. 

401 Unauthorized

The TPP or the PSU is not correctly authorized to perform the request. Retry the request with correct authentication information. 

403 Forbidden 

Returned if the resource that was referenced in the path exists but cannot be accessed by the TPP or the PSU. This code should only be used for non-sensitive id references as it will reveal that the resource exists even though it cannot be accessed. 

404 Not found 

Returned if the resource that was referenced in the path does not exist or cannot be referenced by the TPP or the PSU.

405 Method Not Allowed 

This code is only sent when the http method (PUT, POST, DELETE, GET etc) is not supported on a specific endpoint. It has nothing to do with the consent, payment or account information data model. 

406 Not Acceptable 

The ASPSP cannot generate the content that the TPP specified in the Accept header. 

408 Request Timeout 

The server is still working correctly, but an individual request has timed out. 

415 Unsupported Media Type 

The TPP has supplied a media type which the ASPSP does not support.

429 Too Many Requests

The TPP has exceeded the number of requests allowed by the consent or by the RTS. 

500 Internal Server Error 

Internal server error occurred. 

503 Service Unavailable

The server is currently unavailable.

 

Additional information about the error may be passed using the data element “tpp_messages” in any JSON response message.

Account information service API (AIS)

Services and end points

Service

Endpoints

Implemented in version

Receive valid consent

GET /consents

v1

Create consent

POST /consents

v1

Consent details info

GET /consents/{consent-id}

v1

Consent status info

GET /consents/{consent-id}/status

v1

Delete consent

DELETE /consents/{consent-id}

v1

List of accounts

GET /accounts

v1

Account details

GET /accounts/{account-id}

v1

Account balances

GET /accounts/{account-id}/balances

v1

Account transaction list

GET /accounts/{account-id}/transactions

v1

 

Rules

Consent:

  • the maximum validity of consent is 90 days

Account information service:

  • the list of account contains only the accounts the user has given access to TPP
  • “Date from” of a transaction list must be up to 90 days back

 

Payment initiation service API (PIS)

Services and end points

Service

Endpoints

Implemented in version

Initiate single payment 

POST /payments/{payment-product}

v1

Content of a payment object

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

v1

Status of payment object

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

v1

 

Payment product - v1

  • domestic-credit-transfers-bgn

  • domestic-budget-transfers-bgn

  • sepa-credit-transfers

  • cross-border-transfers

Rules

  • Only positive amounts will be accepted;

  • Initiating payment from an account that requires multiple signatures:

API provides initiation of payment and first authorization, after which other authorizations have to be made via the online banking.

Confirmation of funds API (COF)

 

Services and end points

Service

Endpoints

Implemented in version

confirm availability of funds 

POST /funds-confirmations

v1

 

Rules

  • Only positive amount will be checked