Introduction

Changelog

Timestamp Change/note

25 Jul 2023 Following the EBA amendments under Commission Delegated Regulation (EU) 2022/2360, this dedicated interface enables the SCA consent exemption under SCA-RTS, Article 10a for AISPs. This feature allows AISPs to extend the timeline for the renewal of SCA from every 90 days to every 180 days.
To avail of the 180 days SCA consent exemption on the AIS flow, the newly created consents should contain the date value of up to 180 days in future for the validUntil parameter.
In case you need any assistance on the above please contact us at: compliance@saltedge.com

12 Apr 2023 Following the FCA recommendation under PS21/19, this dedicated interface enables the SCA exemption under SCA-RTS Article 10A for AISPs. This feature allows the AISPs to create a consent longer than 90-days, not limited. AISPs must reconfirm customer consent under Article 36(6) of the SCA-RTS, and must not access information without the customer actively requesting it unless the customer has reconfirmed the consent within the previous 90 days. When a customer fails to reconfirm consent on the AISP side after 90 days, AISP must stop accessing the customer’s account information.
In case you need any assistance on the above please contact us at: compliance@saltedge.com

23 Dec 2021

Timestamp	Change/note
25 Jul 2023	Following the EBA amendments under Commission Delegated Regulation (EU) 2022/2360, this dedicated interface enables the SCA consent exemption under SCA-RTS, Article 10a for AISPs. This feature allows AISPs to extend the timeline for the renewal of SCA from every 90 days to every 180 days. To avail of the 180 days SCA consent exemption on the AIS flow, the newly created consents should contain the date value of up to 180 days in future for the `validUntil` parameter. In case you need any assistance on the above please contact us at: compliance@saltedge.com
12 Apr 2023	Following the FCA recommendation under PS21/19, this dedicated interface enables the SCA exemption under SCA-RTS Article 10A for AISPs. This feature allows the AISPs to create a consent longer than 90-days, not limited. AISPs must reconfirm customer consent under Article 36(6) of the SCA-RTS, and must not access information without the customer actively requesting it unless the customer has reconfirmed the consent within the previous 90 days. When a customer fails to reconfirm consent on the AISP side after 90 days, AISP must stop accessing the customer’s account information. In case you need any assistance on the above please contact us at: compliance@saltedge.com
23 Dec 2021	The CBC-mode cipher encryption will be disabled on PSD2 APIs and the following cipher suites will no longer be supported since 3rd February 2022: TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384 TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256 Please find below the list of supported ciphers and make sure you support any of the below to keep the connection with the PSD2 APIs: TLS_AES_256_GCM_SHA384 TLS_CHACHA20_POLY1305_SHA256 TLS_AES_128_GCM_SHA256 TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384 TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256 TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256 In case you need any assistance on the above please contact us at: compliance@saltedge.com

The CBC-mode cipher encryption will be disabled on PSD2 APIs and the following cipher suites will no longer be supported since 3rd February 2022:

TLS_ECDHE_RSA_WITH_AES_256_CBC_SHA384
TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256

Please find below the list of supported ciphers and make sure you support any of the below to keep the connection with the PSD2 APIs:

TLS_AES_256_GCM_SHA384
TLS_CHACHA20_POLY1305_SHA256
TLS_AES_128_GCM_SHA256
TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
TLS_ECDHE_RSA_WITH_CHACHA20_POLY1305_SHA256
TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256

In case you need any assistance on the above please contact us at: compliance@saltedge.com

Definitions

Term	Definition
API	Application Programming interface. A set of definitions, protocols, and tools that can be used to create applications, interact with other applications, and exchange data.
Provider	Represents the ASPSP. A bank or financial institution that offer payment accounts with online access.
ASPSP	Account Servicing Payment Service Provider. Payment service provider providing and maintaining a payment account for a payer.
TPP	An entity authorised to access accounts on behalf of customers but that does not operate those accounts themselves. TPPs include PISPs, AISPs, and PIISPs.
PSU	Payment Service User. Natural or legal person making use of a payment service as a payee, payer or both.
AISP	Account Information Service Provider. Provides account information services as an online service with consolidated information on one or more payment accounts held by a payment service user with one or more payment service provider(s).
PISP	Payment Initiation Service Provider. Provides an online service to initiate a payment order at the request of the payment service user with respect to a payment account held at another payment service provider.
PIISP	Payment Issuer Instrument Service Provider. Provides information about the funds availability of payment transactions based on the payment cards. The related services supplied can be identified as CAF/FCS (Confirmation on the Availability of Funds Service).
SCA	Strong Customer Authentication. Authentication based on the use of two or more elements designed in such a way as to protect the confidentiality of the authentication data.
XS2A	Access to Account. The provision of secure access to accounts operated by ASPSPs using APIs.
PSD2	The Second Revised Payment Services Directive. The directive of the European Parliament and of the Council of the European Union which requires ﬁnancial institutions within the European Economic Area to provide access to their customers' accounts (XS2A), to Third Party Providers to provide account information and payment initiation services.
eIDAS	Electronic Identification, Authentication and trust Services. A set of standards for electronic identification and trust services for electronic transactions in the European Single Market.
QSEAL	Qualified Electronic Seal Certificate is a qualified digital certificate under the trust services defined in the eIDAS Regulation.

Registration

The process of TPP registration is made via an API request to TPP Register endpoint. In order to access Provider Sandbox you need to use eIDAS QSEAL test certificate.

Access to production environment is allowed only with production QSEAL certificates. It is possible to add a QSEAL certificate via API request to TPP Certficate endpoint.

After adding a certificate, the registered TPP will have assigned a set of scopes based on the provided certificate.

I.e. AISP certificate will result in account, transactions, kyc scopes, while a PISP certificate will result in payments, funds_availability scopes. The available scopes can be seen when creating an TPP Application.

Registration Endpoints

Endpoint	Verb	Purpose
/v1/tpp/certificates	POST	Used for adding certificate. After action, you will receive a letter of confirmation on your representative email.
/v1/tpp/register	POST	Used for registration in Salt Edge PSD2 Compliance Dashboard. After registration, you will receive a letter of confirmation on your representative email.

For more details, please access TPP Registration page: /docs/berlingroup/certificates

The signed request should be as:

POST /api/berlingroup/v1/tpp/certificates HTTP/1.1
Host: priora.saltedge.com
Content-Type: application/json
Date: Fri, 04 Feb 2022 17:16:59 GMT
Digest: SHA-256=RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=
X-Request-ID: 79c851ce-f543-4c27-a8e4-f9aad20724ba
Signature: keyId="SN=B83852160,CA=FIRMA PROFESIONAL",algorithm="rsa-sha-256",headers="x-request-id digest date",signature="XWyngnV7vT9ALgfBdTP5JYJumS3m5hxZa8ryx96XdJ3h6xGrrKMQg2u86qf8+YtVCZj/XpTq+POKOGFkdNQpxTrMeicP0pQKQ2S2ny/0DpFokC6QcXzyj25nazicIYmTqMBQKoNL9DvMtcWG4xTdxVsFLU51xhrqD0Bi4l4NmX73fq4J7VLjYDfiYCldaoSlu3K/p5QOOxzORGWDidRoOvpsELFleppu4Btt8CjPff6QM9oDRFmaOoxbnwBkFu0om7pLEmk5OUD711d9LGnFp65MaljEitpZfYbkNjSCJMsbyfRiYuSpwN34O7sZwzSiRYV9j72BN2C66tXxL0UZAg=="
TPP-Signature-Certificate: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1CMHdGZ0lCQURBQU1BQXdCQjhBSHdBd0FEQUZNQUFEQVFBd0FBTUJBQT09Ci0tLS0tRU5EIENFUlRJRklDQVRFLS0tLS0K
{}

BerlinGroup Headers

Instruction to create BerlinGroup Signature

The required headers for this call are:

X-Request-ID: A Universally Unique Identifier (UUID) URN Namespace. (RFC 4122) Example: 79c851ce-f543-4c27-a8e4-f9aad20724ba

Digest: Base64 request body encoded SHA256. Example: > export BODY="{}" > echo -n $BODY | openssl sha256 -binary | base64 RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=
Digest value: "SHA-256=RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o="

Date: Date/Time Format. (RFC 7231) Example: Fri, 04 Feb 2022 17:16:59 GMT

TPP-Signature-Certificate: Base64 strict encoded certificate in PEM format. Example: > export PEM="-----BEGIN CERTIFICATE-----\nMB0wFgIBADAAMAAwBB8AHwAwADAFMAADAQAwAAMBAA==\n-----END CERTIFICATE-----\n" > echo -n $PEM | base64

Signature: The signed value of the message, with the following structure. Example: /keyId=\"SN=(?.+),CA=(?.+)\",algorithm=\"(?.+)\",headers=\"(?.+)\",signature=\"(?.+)\"/
- keyId: Must be formatted as SN={serial},DN={issuer}. Example: "SN=B83852160,DN=FIRMA PROFESSIONAL"
- algorithm: Could be "rsa-sha-256" or "rsa-sha-512". Example: "rsa-sha-256"
- headers: Create a string to be using a set of request headers: date, digest, x-request-id, psu-id, psu-corporate-id and tpp-redirect-uri in this example, we will just use the mandatory ones: x-request-id, digest, date and tpp-redirect-uri. Example: "x-request-id digest date tpp-redirect-uri"
- signature: Create a string to be signed built using a set of request headers: date, digest, x-request-id, psu-id, psu-corporate-id and tpp-redirect-uri in this example, we will just use the mandatory ones: x-request-id, digest, date and tpp-redirect-uri, the final result will be: "digest date x-request-id tpp-redirect-uri". Here the order of these fields in the signing string matters and they need to be on separate lines. The order has to be exactly as in headers. You should generate a signature value that must be base-64 encoded: Example: order as in 'headers' ("x-request-id digest date tpp-redirect-uri")
  > export SIGNING_STRING="x-request-id: 79c851ce-f543-4c27-a8e4-f9aad20724ba\ndigest: SHA-256=RBNvo1WzZ4oRRq0W9+hknpT7T8If536DEMBg9hyq/4o=\ndate: Fri, 04 Feb 2022 17:16:59 GMT" > printf $SIGNING_STRING | openssl dgst -sha256 -sign certificate_private_key.pem | openssl base64 -A XWyngnV7vT9ALgfBdTP5JYJumS3m5hxZa8ryx96XdJ3h6xGrrKMQg2u86qf8+YtVCZj/XpTq+POKOGFkdNQpxTrMeicP0pQKQ2S2ny/0DpFokC6QcXzyj25nazicIYmTqMBQKoNL9DvMtcWG4xTdxVsFLU51xhrqD0Bi4l4NmX73fq4J7VLjYDfiYCldaoSlu3K/p5QOOxzORGWDidRoOvpsELFleppu4Btt8CjPff6QM9oDRFmaOoxbnwBkFu0om7pLEmk5OUD711d9LGnFp65MaljEitpZfYbkNjSCJMsbyfRiYuSpwN34O7sZwzSiRYV9j72BN2C66tXxL0UZAg==
  As result the signature value should be as:
  Example: "Signature": keyId="SN=B83852160,CA=FIRMA PROFESIONAL",algorithm="rsa-sha-256",headers="x-request-id digest date",signature="XWyngnV7vT9ALgfBdTP5JYJumS3m5hxZa8ryx96XdJ3h6xGrrKMQg2u86qf8+YtVCZj/XpTq+POKOGFkdNQpxTrMeicP0pQKQ2S2ny/0DpFokC6QcXzyj25nazicIYmTqMBQKoNL9DvMtcWG4xTdxVsFLU51xhrqD0Bi4l4NmX73fq4J7VLjYDfiYCldaoSlu3K/p5QOOxzORGWDidRoOvpsELFleppu4Btt8CjPff6QM9oDRFmaOoxbnwBkFu0om7pLEmk5OUD711d9LGnFp65MaljEitpZfYbkNjSCJMsbyfRiYuSpwN34O7sZwzSiRYV9j72BN2C66tXxL0UZAg=="

API Endpoints

The table below describes the list of all API endpoints available at Salt Edge PSD2 Compliance Solution. The endpoints are based on NextGenPSD2 Framework version 1.3.6. also known as BerlinGroup Standard. BerlinGroup endpoints are name-spaced after selected provider_code. Ex: for NextGenPSD2Demobank, the endpoints will start with /nextgenpsd2demobank/api...

Endpoint	Verb	Purpose
/berlingroup/v1/accounts/:account_id/balances	GET	Reads account data from a given account addressed by `account_id`.
/berlingroup/v1/accounts	GET	Read the identifiers of the available payment account together with booking balance information, depending on the consent granted. It is assumed that a consent of the PSU to this access is already given and stored on the ASPSP system. The addressed list of accounts depends on the PSU ID and the stored consent addressed by consentId. Returns all identifiers of the accounts, to which an account access has been granted to through the /consents endpoint by the PSU. In addition, relevant information about the accounts and hyperlinks to corresponding account information resources are provided if a related consent has been already granted. Remark: Note that the `/consents` endpoint optionally offers to grant an access on all available payment accounts of a PSU. In this case, this endpoint will deliver the information about all available payment accounts of the PSU at this ASPSP.
/berlingroup/v1/accounts/refresh	POST	This endpoint is responsible for starting the process of refreshing account information data on Salt Edge PSD2 Compliance Solution side. Due to asynchronous nature of this action, TPP has to poll the status of this process using `Accounts RefreshStatus` endpoint.
/berlingroup/v1/accounts/refresh/status	GET	This endpoint is responsible for returning the current status of fetching account information process.
/berlingroup/v1/accounts/:account_id	GET	Reads details about an account, with balances where required. It is assumed that a consent of the PSU to this access is already given and stored on the ASPSP system. The addressed details of this account depends on the stored consent addressed by consentId.
/berlingroup/v1/accounts/:account_id/transactions/:transaction_id	GET	Reads transaction data from a given account and transaction addressed by `account_id` and `transaction-id`.
/berlingroup/v1/accounts/:account_id/transactions	GET	Read transaction reports or transaction lists of a given account addressed by `account_id`, depending on the steering parameter `bookingStatus` together with balances.
/berlingroup/v1/accounts/:account_id/transactions	GET	Read transaction reports or transaction lists of a given account addressed by `account_id`, depending on the steering parameter `bookingStatus` together with balances.
/v1/aspsps	GET	Used by TPP for obtaining the list of ASPSPs which support NextGenPSD2 standard.
/v1/aspsps/product_templates	GET	Used by TPP for obtaining the list of payment products which support NextGenPSD2 standard.
/berlingroup/v1/bulk-payments/:payment_product/:bulk_payment_id/authorisations	POST	Starts the authorisation process for a payment initiation.
/berlingroup/v1/bulk-payments/:payment_product/:bulk_payment_id/authorisations/:authorisation_id	GET	This method returns the SCA status of a consent initiation's authorisation subresource.
/berlingroup/v1/bulk-payments/:payment_product/:bulk_payment_id/cancellation-authorisations	GET	Will deliver an array of resource identifications to all generated cancellation authorisation subresources.
/berlingroup/v1/bulk-payments/:payment_product/:bulk_payment_id/cancellation-authorisations/:authorisation_id	GET	This method returns the SCA status of a payment cancellation's authorisation subresource.
/berlingroup/v1/bulk-payments/:payment_product	POST	This method is used to instruct Salt Edge PSD2 Compliance Solution to initialize the payment creation.
/berlingroup/v1/bulk-payments/:payment_product	POST	This method is used to instruct Salt Edge PSD2 Compliance Solution to initialize the payment creation.
/berlingroup/v1/bulk-payments/:payment_product/:bulk_payment_id	DELETE	It initiates the cancellation of a payment order. Depending on the payment-product and the ASPSP's implementation, this TPP call might be sufficient to cancel a payment.
/berlingroup/v1/bulk-payments/:payment_product/:bulk_payment_id	GET	This method returns payment data.
/berlingroup/v1/bulk-payments/:payment_product/:bulk_payment_id	GET	This method returns payment data.
/berlingroup/v1/bulk-payments/:payment_product/:bulk_payment_id/status	GET	This method returns payment status.
/berlingroup/v1/card-accounts/:account_id/balances	GET	Reads balance data from a given card account addressed by account-id.
/berlingroup/v1/card-accounts	GET	Reads a list of card accounts with additional information, e.g. balance information. It is assumed that a consent of the PSU to this access is already given. The addressed list of card accounts depends on the PSU ID and the stored consent addressed by consentId.
/berlingroup/v1/card-accounts/:account_id	GET	Reads details about a card account. It is assumed that a consent of the PSU to this access is already given. The addressed details of this account depends on the stored consent addressed by consentId.
/berlingroup/v1/card-accounts/:account_id/transactions	GET	Read transaction reports or transaction lists of a given card account addressed by account-id.
/berlingroup/v1/card-accounts/:account_id/transactions	GET	Read transaction reports or transaction lists of a given card account addressed by account-id.
/berlingroup/v1/consents/:consent_id/authorisations/:authorisation_id	GET	This method returns the SCA status of a consent initiation's authorisation subresource.
/berlingroup/v1/consents	POST	This method creates a consent resource, defining access rights to dedicated accounts of a given PSU-ID. These accounts are addressed explicitly in the method as parameters as a core function.
/berlingroup/v1/consents/:consent_id	DELETE	This method deletes a consent.
/berlingroup/v1/consents/:consent_id	GET	Returns the content of an account information consent object. This returns the data for the TPP especially in cases, where the consent was directly managed between ASPSP and PSU e.g. in a redirect SCA Approach.
/berlingroup/v1/consents/:consent_id/status	GET	Read the status of an account information consent resource.
/berlingroup/v1/funds-confirmations	POST	Checks whether a specific amount is available at point of time of the request on an account addressed by IBAN or other available identifiers.
/berlingroup/v1/payments/:payment_product/:payment_id/authorisations	POST	Starts the authorisation process for a payment initiation.
/berlingroup/v1/payments/:payment_product/:payment_id/authorisations/:authorisation_id	GET	This method returns the SCA status of a consent initiation's authorisation subresource.
/berlingroup/v1/payments/:payment_product/:payment_id/cancellation-authorisations	GET	Will deliver an array of resource identifications to all generated cancellation authorisation subresources.
/berlingroup/v1/payments/:payment_product/:payment_id/cancellation-authorisations/:authorisation_id	GET	This method returns the SCA status of a payment cancellation's authorisation subresource.
/berlingroup/v1/payments/:payment_product	POST	This method is used to instruct Salt Edge PSD2 Compliance Solution to initialize the payment creation.
/berlingroup/v1/payments/:payment_product	POST	This method is used to instruct Salt Edge PSD2 Compliance Solution to initialize the payment creation.
/berlingroup/v1/payments/:payment_product	POST	This method is used to instruct Salt Edge PSD2 Compliance Solution to initialize the payment creation.
/berlingroup/v1/payments/:payment_product	POST	This method is used to instruct Salt Edge PSD2 Compliance Solution to initialize the payment creation.
/berlingroup/v1/payments/:payment_product/:payment_id	DELETE	It initiates the cancellation of a payment order. Depending on the payment-product and the ASPSP's implementation, this TPP call might be sufficient to cancel a payment.
/berlingroup/v1/payments/:payment_product/:payment_id	GET	This method returns payment data.
/berlingroup/v1/payments/:payment_product/:payment_id/status	GET	This method returns payment status.
/berlingroup/v1/periodic-payments/:payment_product/:periodic_payment_id/authorisations	POST	Starts the authorisation process for a payment initiation.
/berlingroup/v1/periodic-payments/:payment_product/:periodic_payment_id/authorisations/:authorisation_id	GET	This method returns the SCA status of a consent initiation's authorisation subresource.
/berlingroup/v1/periodic-payments/:payment_product/:periodic_payment_id/cancellation-authorisations	GET	Will deliver an array of resource identifications to all generated cancellation authorisation subresources.
/berlingroup/v1/periodic-payments/:payment_product/:periodic_payment_id/cancellation-authorisations/:authorisation_id	GET	This method returns the SCA status of a payment cancellation's authorisation subresource.
/berlingroup/v1/periodic-payments/:payment_product	POST	This method is used to instruct Salt Edge PSD2 Compliance Solution to initialize the payment creation.
/berlingroup/v1/periodic-payments/:payment_product	POST	This method is used to instruct Salt Edge PSD2 Compliance Solution to initialize the payment creation.
/berlingroup/v1/periodic-payments/:payment_product/:periodic_payment_id	DELETE	It initiates the cancellation of a payment order. Depending on the payment-product and the ASPSP's implementation, this TPP call might be sufficient to cancel a payment.
/berlingroup/v1/periodic-payments/:payment_product/:periodic_payment_id	GET	This method returns payment data.
/berlingroup/v1/periodic-payments/:payment_product/:periodic_payment_id	GET	This method returns payment data.
/berlingroup/v1/periodic-payments/:payment_product/:periodic_payment_id/status	GET	This method returns payment status.
/berlingroup/v1/signing-baskets/:basket_id/authorisations/:authorisation_id	GET	This method returns the SCA status of a signing basket initiation's authorisation subresource.
/berlingroup/v1/signing-baskets/:basket_id/cancellation-authorisations/:authorisation_id	GET	This method returns the SCA status of a signing basket cancellation's authorisation subresource.
/berlingroup/v1/signing-baskets/:basket_id/cancellation-authorisations	GET	Will deliver an array of resource identifications to all generated cancellation authorisation subresources.
/berlingroup/v1/signing-baskets	POST	Create a signing basket resource for authorising several transactions with one SCA method. The resource identifications of these transactions are contained in the payload of this access method.
/berlingroup/v1/signing-baskets/:basket_id	DELETE	It initiates the cancellation of a signing_basket.
/berlingroup/v1/signing-baskets/:basket_id	GET	Retrieve the signing basket content
/berlingroup/v1/signing-baskets/:basket_id/status	GET	Read the status of the signing basket.

Scopes Definition

Type	Description
payments	grants TPP right to initiate payment orders on behalf of Customer
accounts	grants TPP access to Customer's accounts data
transactions	grants TPP access to transactions which belong to Customer's account
funds_availability	grants TPP right to check availability of funds under specific account which belongs to Customer

All Errors

During any request or flow originating either on TPP or Salt Edge PSD2 Compliance side, a number of errors may appear. In order to standardize errors while still giving some degree of freedom in explaining an error callback, parameters should include both error_text and error_code. Error message serves the purpose of communicating the issue to the Customer, whereas error class should be used by TPPs in order to be able to handle various scenarios.

Contents of the error_code are entirely up to the Provider, they may even be localized. However, values sent within error_text parameter should be from the standardized list. This list may and will be extended over time.

Class	Code	Description
BadRequest	400	Given value is invalid.
CountryNameInvalid	400	Country doesn't exist or is invalid. Expected alpha 2 ISO3166 format.
ServiceInvalid	400	Something went wrong on Provider(ASPSP) side.
FormatError	400	Invalid input. More info in `error_message`
ConsentInvalid	401	The consent was created by this TPP but is not valid for the addressed service/resource.
ConsentUnknown	401	The Consent-ID cannot be matched by the ASPSP relative to the TPP.
CertificateMissing	401	This request cannot be performed without `Certificate` header.
CertificateInvalid	401	Given certificate is invalid.
RoleInvalid	401	Given certificate doesn't have required roles
SignatureMissing	401	This request cannot be performed without `Signature` header.
SignatureInvalid	401	Given signature is invalid.
ConsentExpired	401	The consent was created by this TPP but has expired and needs to be renewed.
AccessDenied	403	Action you want to perform is not allowed. More in `error_message`
ProductInvalid	403	The payment product is not supported by the addressed service/resource.
ResourceUnknown	404	The addressed resource is unknown relative to the TPP.
ProductUnknown	404	The payment product wasn't found.
CancellationInvalid	405	The addressed payment is not cancellable e.g. due to cut off time passed or legal constraints.
AccessExceeded	429	Exceeded the number of requests for this action.

Support

If support is required, please send an email to compliance@saltedge.com