PSD2 Interface

Documentation

The XS2A APIs, are developed on the basis of the Berlin Group PSD2 Access to Bank Accounts (XS2A) specification and the national BISTRA standard.

Recent Changes

2024-02-13 It is no longer necessary to obtain an access token before reaching the main XS2A API. For compatibility, the token endpoint is still working and it will return a valid token which you can pass to the main API. However, the XS2A interface could also be accessed without passing an Authorization header. Third Party Providers are encouraged to update their clients to stop obtaining access tokens and start using the interface directly. Of course a valid client certificate must still be presented.

TPP Authentication

Certificate

To access all endpoints of the PSD2 XS2A interface a third party provider (TPP) must present a valid PSD2 compliant Qualified Web Authentication Certificate (QWAC) according to ETSI TS 119 495.2. The certificate must be issued by one of the EU list of trusted providers and must specify the roles for which the provider is authorized:

Payment initiation (PSP_PI);
Account information (PSP_AI);

In addition, the certificate must contain in the subject:organizationIdentifier the auhtorization number issued by a National Competent Authority.

In most cases the TPP can access the XS2A interface directly without any notification or registration. In some cases we may be missing the root CA in which cases you should send your certificate to psd2[AT]ccbank.bg.

Endpoints

Both the production as well as the sandbox APIs are hosted at two different domains. The difference is only in the supported HTTP and TLS protocols:

https://psd2.ccbank.bg - TLSv1.2, HTTP/1.1. Uses TLS renegotiation to request a certificate.
https://xs2a.ccbank.bg - TLSv1.2, HTTP/1.1 and HTTP/2. The client certificate is required when establishing the TLS connection.

We recommend whenever possible to use xs2a.ccbank.bg in your configuration. The psd2.ccbank.bg domain is useful mostly for testing via the developer protals.

Strong Customer Authentication

SCA Approach

Customer authentication is based on Redirect SCA Approach with support for authorisation sub-resources and Implicit Start of the Authorisation Process. After the creation of consent or payment resource the authorisation process is started immediately by implicitly creating an authorisation sub-resource.

The scaRedirect links will expire if the user is not authenticated within two minutes. After the user is authenticated, the scaStatus is changed to psuAuthenticated and the link cannot be used anymore for another user authentication. The scaStatus of the resource will then change either to finalised if the user was able to confirm the main resource or to failed if the session expired. Additional authorisation sub-resources could be created by an explicit POST to the corresponding endpoint. They could be used either by the same PSU or by a different PSU to implement multilevel SCA in case of corporate accounts.

Authentication Channels

Customers of Central Cooperative Bank can use three different channels to access their accounts:

CCB Online - requires the use of Qualified Electronic Signature for login and is available only on desktop browsers.
CCB Mobile - a mobile application available for iOS and Android devices.

A customer can have access to any of the above channels. Because we do not know in advance which is the PSU or to which channels he has access the scaRedirect link opens a generic login page where depending on the device the user will be able to select and login in the appropriate channel.

The CCB Mobile application is registered for Andriod App Links and iOS Universal Links. So, if you are opnening the scaRedirect link from a mobile application you should not open it in an embedded WebView component. Instead, you should open the scaRedirect link in the system browser. On Android this is done by starting an activity for loading a Web URL using the ACTION_VIEW intent and on iOS you should open the link using open.

TPP Redirect

When creating a consent, payment or authorisation sub-resourse, the TPP can pass a TPP-Redirect-URI header. The customer will be redirected to this URL when the SCA process finishes regardless of wether the process was successful or not.

The final redirection to the TPP URL could happen on a different channel than the one on which the scaRedirect link was initially opened. For example a user is working on a desktop computer and opens the redirect link in a browser. In certain situations the browser may display a QR code which can be scanned by the mobile device of the user. The authentication and the confirmation then continues using the CCB Mobile application and the final redirect to the TPP-Redirect-URI will happen in an embedded browser in the mobile application. The TPPs should be aware of this detail and implement the redirect links accordingly.

The header TPP-Nok-Redirect-URI currently is not supported.

Consent Models

The interface supports the following consent models.

Detailed Consent

The TPP submits detailed description of the required level of account access by providing non-empty access attributes (accounts, balances or transactions).

Global Consent

The TPP is requesting access to all customer accounts. This is done by submitting one of the following access attributes: availableAccounts, availableAccountsWithBalance or allPsd2 with the value allAccounts. The attribute availableAccounts requests access only to the account list and does not require a second factor for authentication. The attribute availableAccountsWithBalance requests in addition access to balances. Finally, allPsd2 requests full access wich also includes transaction details.

Transaction Report

The list of transactions is always returned ordered in chronological order on the booking date, i.e. the oldest transaction is returned first.

If there are two many transactions for the requested period, the call to the transactions endpoint will return only an initial porition of the oldest transactions. If there are more, this will be indicated by the presence of the link transactions._links.next in the response which could be used to retrieve the next batch of transactions. The TPP can also construct this link manually by taking the value of the entryReference field from the last returned transaction and passing it in the entryReferenceFrom parameter.

Payments

Status Model

The payments submitted through the XS2A interface go through the following statuses:

RCVD - this is the initial status of submitted payments.
PATC - this status is returned if the payment is confirmed by one user but still needs to be confirmed by more users in the case of a multilevel SCA.
PDNG - this status indicates that the payment is waiting additional documents or actions, either by the bank or by the user. Examples are payments that need a declaration for origin of funds, payments with preferential exchange rate, or additional review for SWIFT payments by a bank officer.
ACTC - payments in this status have already been confirmed and are waiting for processing.
ACSP - payments in this status are being processed by the bank.
PART - this status is returned only for bulk payments and indicates that some of the individual payments have been accounted.
ACSC - this is a final status indicating successfuly executed payment.
ACCC - this is also a final status for successful execution but it is returned for instant payments indicating that the money have been also received by the creditor.
RJCT - final status indicating that the payment has been rejected for some reason, for example insufficient funds, past execution date, error in the payment data, etc.
CANC - the payment has been cancelled by the user.

Developer Portals

OpenAPI Developer Portal

The obtain login credentials for the sandbox environment please contact psd2[AT]ccbank.bg. Also note that sometimes this environment will contain upcoming changes to the API so that the TPPs will be able to test them before release.