Introduction
Change log
| Timestamp | Change/note |
|---|---|
| 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:
|
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. |
| 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. |
| QWAC | Qualified Website Authentication Certificate is a qualified digital certificate under the trust services defined in the eIDAS Regulation. |
| PSD2 | The Second Revised Payment Services Directive. The directive of the European Parliament and of the Council of the European Union which requires financial 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. |
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
Examples of BerlinGroup Headers
{ "X-Request-ID": "5b2d13ae-f7e8-4088-b98f-0acf05ac3303" }
{ "Digest": "SHA-256=yL4tyKu3UC0isKZgiGYDu1guWcLIJyZkLQUb1e35zYw=" }
{ "Date": "Wed, 23 Mar 2022 10:03:06 GMT" }
{ "TPP-Signature-Certificate": "LS0tLS1CRUdJTiBDRVJUS ... lGSUNBVEUtLS0tLQo=" }
{ "Signature": "Signature keyId=\"SN=0,DN=/organizationIdentifier=TppSaltTest000/CN=certSIGNSALTTEST Web CA/O=SaltTest/C=RO\",algorithm=\"rsa-sha256\",headers=\"x-request-id digest date\",signature=\"ODP6GRM+IjqAKi5z+iea93YR3Qox5dp13r7GjQdHuJOxXEMs3nWy8mKA1CuKKB7CyZONgWAqi6Zev4gQ1Zs7AjGZ4TNxrK1OtT7f8ICtAPtmPyoP4yiDqZLcikcprrG2DRfIu5DS2QWy/wg1EYOiIi+mQEMlDYm5fWMOa6wog5+OL369t/ZV3T+g1ZIdbbK9CVKwQQJ4TiCpLgCvEa8s8Nw4P9doOYCUyHkYWBWfYRkW0wWnnhgGAzT4L3CXi+vWXHWbvENrUDAhcEZ3YCHEljWF2r+xroaT5GVhIob9GspH+W5bX9+XySm1d6aZyf5T6K00O2pAtOS1BnEUwyLDWg==\"" }
{ "Signature keyId": "SN=0,DN=/organizationIdentifier=TppSaltTest000/CN=certSIGNSALTTEST Web CA/O=SaltTest/C=RO\"" }
{ "Algorithm": "rsa-sha256" }
{ "Headers": "x-request-id digest date" }
{ "Signature": "LweOMKvt2qun5u7Thz3yrohkt ... lGSUNBVEUtLS0tLo==" }
{ "SIGNING_HEADERS": "x-request-id: 7e0cece5-72e3-4109-8a72-451d73d1ac21\ndigest: SHA-256=JZGKETBzhD+QcSaXB9bFhKrcNL0+wCXjuDuhHNdJuVY=\ndate: Wed, 23 Mar 2022 11:03:32 GMT" }
Registration BerlinGroup Headers
Instruction to create BerlinGroup Signature
To register as a TPP, the first thing you must do is get a valid EIDAS certificate.
The required headers for this call are:
-
X-Request-ID:
Is a unique id for your call, e.g. a GUID.
X-Request-ID => SecureRandom.uuid -
Digest:
Is a hashed and encoded value of the body of the API call.
Digest => "SHA-256=" + Digest::SHA256.base64digest(YOUR_REQUEST_BODY) -
Date:
Is just the date of the call, in the following format: „Fri, 04 Feb 2022 17:16:59 GMT“
Date => Time.now.httpdate -
TPP-Signature-Certificate:
Is the cert used to sign the message.
TPP-Signature-Certificate => Base64.strict_encode64(CERTIFICATE_PEM) -
Signature:
Is the signed value of the message, and is constructed in the following way.
Signature => "Signature keyId=" "SN=" + certificate.serial,"DN=" + certificate.issuer", "algorithm" = "rsa-sha256", "headers" = "x-request-id digest date", "signature" = Base64(RSA-SHA256(signing string))-
Signature keyId:
Is combinated string of Certificate Serial Number and Certificate Issuer. Certificate serial number must be in decimal notation.
Signature keyId => "SN=" + (CERTIFICATE_SERIAL),"DN=" + (CERTIFICATE_ISSUER)" -
Algorithm:
Is SHA256 algorithm.
Algorithm => "rsa-sha256" -
Headers:
Selected required headers.
Headers => "x-request-id digest date" -
Signature:
Is Base64 encoded string.
Signature => Base64.strict_encode64(PRIVATE_KEY.sign("RSA-SHA256", SIGNING_HEADERS))
SIGNING_HEADERS: Is required headers with values. Where `\n` is used as headers delimiter.
SIGNING_HEADERS => "x-request-id: 5b2d13ae-f7e8-4088-b98f-0acf05ac3303\n" + "digest: SHA-256=yL4tyKu3UC0isKZgiGYDu1guWcLIJyZkLQUb1e35zYw=\n" + "date: Wed, 23 Mar 2022 10:03:06 GMT"
-
Signature keyId:
Is combinated string of Certificate Serial Number and Certificate Issuer. Certificate serial number must be in decimal notation.
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. |
| /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/: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/:authorisation_id | GET | This method returns the SCA status of a payment cancellation'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 | 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/authorisations | POST | Starts the authorisation process for a payment initiation. |
| /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/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/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/: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/:authorisation_id | GET | This method returns the SCA status of a payment cancellation'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 | POST | This method is used to instruct Salt Edge PSD2 Compliance Solution to initialize the payment creation. |
| /berlingroup/v1/payments/:payment_product/:payment_id/authorisations | POST | Starts the authorisation process for a payment initiation. |
| /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/: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/:authorisation_id | GET | This method returns the SCA status of a payment cancellation'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 | 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/authorisations | POST | Starts the authorisation process for a payment initiation. |
| /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/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 |
|---|---|---|
| CountryNameInvalid | 400 | Country doesn't exist or name is in incorect format. Should be in 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. |
| SignatureMalformed | 401 | Given signature is malformed. |
| 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. |
×
![]()