Introduction
Definitions
| Term | Definition |
| Authorisation | The XS2A API will allow an ASPSP to implement OAuth2 as a support for the authorisation of the PSU towards the TPP for the payment initiation and/or account information service. In this case, the TPP will be the client, the PSU the resource owner and the ASPSP will be the resource server in the abstract OAuth2 model. |
| Consent | A range of rules on security, providing access to accounts, and enabling traceability and the mitigation of fraud risks. |
| Provider | Represents the ASPSP. A bank or financial institution that offer payment accounts with online access. |
| TPP | A third party provider application. |
| Customer | A bank account holder. The end-user of payment services. |
| AISP | Account Information Service Provider. A Client application that allows a Customer to list account and holder information. |
| Session | Any activity that is forwarded by Salt Edge PSD2 Compliance on behalf of a Customer. |
| Scopes | A set of permissions granted to a TPP application. |
| SCA | Strong Customer Authentication using SaltEdge Authenticator. |
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 or QWAC 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 into account, transactions, kyc scopes, while a PISP certificate will result into payments, funds_availability scopes. The available scopes can be seen when creating an TPP Application.
TPP configuration and API keys
TPP may have a number of TPP Applications, them being essentially API keys(ID and secret). These applications serve to identify a specific TPP configuration. For example, say we have a company X that identifies itself as a PFM. Suppose it targets mobile devices(iOS, Android) and web browsers, thus they would have to configure three TPP applications, one for Apple devices, another for Android devices, and one for web browsers. Or maybe Company X needs to test their new features within staging environment first, then it would be convenient to configure another client application for these purposes.
But before managing API keys it is wise to check the TPP configuration. In order to do this, navigate to TPP Settings. Here it is possible to modify TPP's name, email, as well as other business details.
Take into consideration that all TPP Applications will have the same, predefined during registration, scopes. This will ensure that an AISP license certificate will be used only for getting information about Customer's banking details and PISP license certificates will allow creation of payment orders on behalf of Customer.
In order to be able to go Live, TPP has to supply a valid certificate. This could be accomplished using tpp-certificates endpoint.
Now back to managing API keys. The very first test application will be created during the TPP registration process. To configure it navigate to applications page.
Proceed by selecting Test application.
On the page presented above it is possible to change application's name regenerate application secret and set up callback (also doubles as redirect) URL for updates from Salt Edge PSD2 Compliance Solution. In order for your TPP to go live, you must have configured at least one TPP application.
Requesting Provider access
After successful registration and configuration, Salt Edge PSD2 Compliance Team will move TPP into Test status.
This will allow TPP to start making request to all sandboxes available to Salt Edge PSD2 Compliance Solution.
After TPP finishes development, it can ask Salt Edge PSD2 Compliance Team to change its status to Live. This way, TPP will be able to request access for Live banks connected to Salt Edge PSD2 Compliance Solution.
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 then on the PSU ID and the stored consent addressed by consentId, respectively the OAuth2 access token. 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 SaltEdge 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 then on the stored consent addressed by consentId, respectively the OAuth2 access token. |
| /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. |
| /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 sub-resource. |
| /berlingroup/v1/bulk-payments/:payment_product/:bulk_payment_id/cancellation-authorisations/:cancellation_id | GET | This method returns the SCA status of a payment initiation's authorisation sub-resource. |
| /berlingroup/v1/bulk-payments/:payment_product/:bulk_payment_id/cancellation-authorisations | GET | Will deliver an array of resource identifications to all generated cancellation authorisation sub-resources. |
| /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/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 and stored on Salt Edge Compliance system. The addressed list of card accounts depends then 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 and stored on the Salt Edge Compliance system. The addressed details of this account depends then 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 sub-resource. |
| /berlingroup/v1/consents | POST | This method create 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 is returning the data for the TPP especially in cases, where the consent was directly managed between ASPSP and PSU e.g. in a re-direct 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 sub-resource. |
| /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 | GET | This method returns payment data. |
| /berlingroup/v1/payments/:payment_product/:payment_id/status | GET | This method returns payment status. |
| /v1/tpp/certificates | POST | Used for adding an OBSEAL certificate. On successful response (200 status code), the UK TPPs’ existing eIDAS certificate will be switched with the OBSEAL certificate obtained from the OpenBanking Directory. The body of the request has to contain the JWT built from the parameters below and signed with the OBSEAL Certificate. |
| /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. |
Certificate Roles
| Type | Description |
|---|---|
| PSP_AI | "accounts", "transactions", "kyc" |
| PSP_PI | "payments" |
| PSP_CI | "funds_availability" |
| PSP_AS | "accounts", "transactions", "kyc", "payments", "funds_availability" |
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 |
| kyc | grants TPP access to view Customer's KYC data |
| 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 |
|---|---|---|
| ServiceInvalid | 400 | Something went wrong on Provider(ASPSP) side. |
| ConsentUnknown | 401 | The Consent-ID cannot be matched by the ASPSP relative to the TPP. |
| ConsentInvalid | 401 | The consent was created by this TPP but is not valid for the addressed service/resource. |
| ConsentExpired | 401 | The consent was created by this TPP but has expired and needs to be renewed. |
| 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. |
| 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. |