Salt Edge PSD2 Compliance Logo

Changelog

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:
  • 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
Provider Represents the ASPSP. A bank or financial institution that offer payment accounts with online access.
TPP A third party provider application.
Connector Proxy interface before Bank’s Core API.
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.
PISP Payment Initiation Service Provider. A TPP application that allows a Customer to initiate payments on their behalf.
PIISP Payment Issuer Instrument Service Provider. A TPP application that checks coverage of a payment by Customer's account.
Session Any activity that is forwarded by Salt Edge PSD2 Compliance to Connector on behalf of a Customer.
Scopes A set of permissions granted to a TPP application.
Token A secret access token issued by Provider which represents the Customer's consent on specific scopes granted to a TPP application.

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.

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.

Client Details

In order to be able to go Live, TPP has to supply a valid certificate. This could be accomplished using tpp-certificates endpoint.

Security

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.

TPP Applications

Proceed by selecting Test application.

TPP Application details

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 requests to all sandboxes available to Salt Edge PSD2 Compliance Solution.

Provider management

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.

Postman collection

A postman collection describing all endpoints requests is available for developers, but it's important to read the documentation prior to development in order to have a graceful start.

Request verification using JWT

All requests to Salt Edge PSD2 Compliance must be signed. Salt Edge PSD2 Compliance implements request signature verification via Authorization headers. These must contain grant type Bearer followed by a JSON Web Token. A payload should be generated on a per request basis and should include exp and data claims, the former being expiration time and the latter being a JSON object including all relevant parameters for a request, if there are no such parameters it should be left empty. This payload should then be encoded into a JWT via RS256 algorithm using TPP's application's private key.

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a way to securely transmit information.

Salt Edge PSD2 Compliance API requires JWTs to authorize each API request. Implementing a standard that allows Providers and TPPs to securely transmit information provides greater protection of sensitive data and the entire Salt Edge PSD2 Compliance.

Salt Edge PSD2 Compliance uses JWTs as a vehicle to receive signed requests from TPPs and send them to Providers.

TPP is supposed to send JWT signed requests to Salt Edge PSD2 Compliance on any described endpoint in documentation.

Salt Edge PSD2 Compliance will send callbacks with a JWT signed by its private key . This allows Connector the ability to validate that the request form Salt Edge PSD2 Compliance has not been tampered with.

Example of decoded JWT header

{ "typ": "JWT", "alg": "RS256" }

Example of decoded JWT payload

{ "data": { "provider_code": "demobank", "credentials": { "authorization_type": "oauth" }, "scopes": [ "accounts", "transactions", "kyc", "payments", "funds_availability" ], "redirect_url": "https://priora-demo.saltedge.com/connections/1412" }, "exp": 1565716467 }

Salt Edge PSD2 Compliance public key

-----BEGIN PUBLIC KEY----- MIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEAw+4UebzWIN9SNnFm9WBv rvH7CiVyuobh5i2V1bKH7floZSh71xbBnvZ2FsL2kleSJrOj03gh5zpdSxmR/Nj9 MyskswkFSO09bZo2C5ZWMsnFpH0oHRdBWl5hQWJFeuV9TVJkuSuO9XyrsdQMakVK eCRisxseCOo4wux1/tRl7smAlJXoOYF1QEkhoVB6K91JjmBi1DmI0J7W0RET9gsS EHzwVi12WrjCiEKplzN0u7b2i1ydiga2GKXZLxfBu0MfQVD/RI2eCEHmh3/sJPeV u4K5bbwD3hamIM1v4DaGBs7DtR6tk9Xtms79s/hEQWiFd0fjdW2rrp4vEnljobz5 GQIDAQAB -----END PUBLIC KEY-----

JWT Anatomy

A JWT is comprised of 3 sections of url base64 encoded strings of data separated by a period.

The first 2 sections are JSON objects while the last section is a digital signature that has been url base64 encoded.

The sections are as such:

  • header - A small JSON object that specifies what type of algorithm was used to generate the digital signature. This section is denoted in the below example in red.
  • payload - A JSON object that contains the data being sent from one party to another. This section is denoted in the below example in green.
  • signature - A url base64 encoded hash value of the header and payload. This is used to verify the contents of the JWT have not been tampered with. Signatures are created with RS256 alghorithm, using a public/private key pair. The identity provider uses his private key to generate the signature, and the consumer of the JWT uses the requester public key to validate the signature. Since the public key, as opposed to the private key, doesn't need to be kept secured, most identity providers make it easily available for consumers to obtain and use (usually through a metadata URL).

Example of JWT:

eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9. eyJkYXRhIjp7InByb3ZpZGVyX2NvZGUiOiJkZW1vYmFuayIsImNyZWRlbnRpYWxzIjp7ImF1dGhvcml6YXRpb25fdHlwZSI6Im9hdXRoIn0sInNjb3BlcyI6WyJhY2NvdW50cyIsInRyYW5zYWN0aW9ucyIsImt5YyIsInBheW1lbnRzIiwiZnVuZHNfYXZhaWxhYmlsaXR5Il0sInJlZGlyZWN0X3VybCI6Imh0dHBzOi8vcHJpb3JhLWRlbW8uc2FsdGVkZ2UuY29tL2Nvbm5lY3Rpb25zLzE0MTIifSwiZXhwIjoxNTY1NzE2NDY3fQ. Xw9I7N3kUsnfrD2afoEAzaJpB2vWt0YBuaCH9c9dicy5nJwszjhyq4gLuuyNWflb6mRhIx_9C8AZrO6r4auhEu5H0Nn_nawZIwLb_LPLOhqkzlf7npz83D0dSqHnSzn6JtB57o4_dDvSupkYLbAoTY0vff1wBSLnwWya8kjcOaNbHPgV3WGBUG1gYrDzML4-reA60xTP2E1KszDU5XrPyyn2rwvpRa4jC1qqRI2gjMrlTAsAo3uww-w8FQw7MYmRJz7p7aBn85-MVVReFhl-Ivm5Ag71sKlBGlRqw1K2jzGfLxb14jypgEKXytCdRPyI2rM4u7eBWJXT1lXJfHdrew

JWT libraries

In order to use JWT tokens, you'll need to have a token generator.

You can generate JWT tokens by utilizing one of the many libraries available on the JWT website.

How to use JWT

All requests that are either forwarded by or originated on Salt Edge PSD2 Compliance will be signed using Salt Edge PSD2 Compliance private key (RS256 alghorithm) in the form of a JWT containing exp and data claims that can be verified using Salt Edge PSD2 Compliance public key.

  • exp is an UTC timestamp in seconds, preferred value is current time plus 120 seconds.
  • data may include the original_request parameters that were sent to Salt Edge PSD2 Compliance by TPP applications.

This is done to ensure that no Man-in-the-Middle attacks have occurred during request life cycle and that no data was tampered on its way from TPP to Salt Edge PSD2 Compliance to Connector. In seldom cases along parameters encoded into JWT there will be regular HTTP parameters.

Scopes

Scopes are permissions granted to a TPP application. Depending on certificate, TPP can be assigned the following scopes:

Scope Description
accounts Required for accessing Customer's account list and account data.
funds_availability Required for checking whether Customer's account has enough funds to carry out a specific payment. Required by PIISP Clients.
transactions Required for accessing Customer's transactions under specific accounts, therefore best be used along accounts scope.
kyc Required for accessing account holder information.
payments Required for accessing Customer's payment accounts as well as for payment initiation.

Events

Events are states of session and payment life cycles.

Event Description
processing Request to push session/payment into the next phase has been received by Salt Edge PSD2 Compliance and is undergoing processing.
redirect The Customer is being redirected to the Provider's page in order to perform authentication.
waiting_confirmation Session/payment is waiting for an interactive step outside of TPP application, like Strong Customer Authentication via a separate application.
waiting_confirmation_code Session/payment is waiting for an interactive step within TPP application, like One Time Password or SMS confirmation.
fetched_accounts Account information has been fetched from the bank and can be requested using #accounts-all endpoint.
fetched_transactions Transaction information has been fetched from the bank and can be requested using #accounts-transactions endpoint.
fetched_kyc Holder information has been fetched from the bank and can be requested using #accounts-holder endpoint.
closed Session/payment has been closed. To know whether it was a success or a failure, peer into success_at/ fail_at fields from the response.

Example of unpacked Authorization header with session identifier

{ "data": { "session": { "id": "79", "secret": "8ee0cb1722615ebe_1510819559" } }, "exp": 1565622287 }

Example of unpacked Authorization header with payment identifier

{ "data": { "session": { "id": "79", "secret": "8ee0cb1722615ebe_1510819559" }, "payment": { "id": "31" } }, "exp": 1565622287 }

For all asynchronous actions, such as authorizing an access token, creating a payment or refreshing account information, Salt Edge PSD2 Compliance Solution will send callbacks to the requesting TPP Application. The callback will be delivered to the "callback URL", which can be configured for each TPP Application separately in the Applications section of TPP dashboard.

Each callback will include an Authorization header that will consist of grant type Bearer followed by a JWT signed using Salt Edge PSD2 Compliance Solution private key and RS256 algorithm. When decoded, this JWT will include exp and data claims. All relevant information will be wrapped into data claim. More information regarding JWT can be found here.

The payload contains the session information (id and secret). Additionally, during the payment flow it will contain the payment information (id). The example of payload can be seen at the right.

Session Extra

Attribute Type Description
scopes array of strings, optional Token scopes.
device_info object, optional Contains mobile platform and push_token.
public_key string, optional RSA public key.
return_to string, optional URL for redirection after authentication process is carried out.
funds_available boolean, optional Whether funds are available or not.

Session Actions

Each and every session has an action associated to it that represents session's purpose.

Action Purpose
check_funds Process of checking for coverage of a payment by Customer's account.
create_token Creation of a token with the purpose of granting access to bank data for client applications.
revoke_token Revocation of an access token.
refresh_accounts Instruction for Salt Edge PSD2 Compliance to refresh data obtained from the bank.
create_payment Initiation of a payment.
reconnect_token Reconnection of an access token.
create_trusted_beneficiaries Initiation of a trusted beneficiary.

Session Statuses

The current stage of a session lifecycle is represented in status field. The status of a session can be one of the following:

Name Description
processing Salt Edge PSD2 Compliance is processing the request or response.
redirect Provider requires a redirect for authentication.
waiting_confirmation Provider is waiting for the consent of Customer.
waiting_confirmation_code Provider is waiting for a confirmation code, be it OTP for authentication or Dynamic linking for performing a payment.
closed Session is closed.
fetched_kyc Salt Edge PSD2 Compliance has received the information about Customer.
fetched_accounts Salt Edge PSD2 Compliance has received the accounts of Customer.
fetched_transactions Salt Edge PSD2 Compliance has received the transactions of Customer.
fetched_trusted_beneficiaries Salt Edge PSD2 Compliance has received the trusted beneficiaries of Customer.

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_class and error_message. Error message serves the purpose of communicating the issue to the End-Customer, whereas error class should be used by TPPs in order to be able to handle various scenarios.

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

Class Code Description
EncodingInvalid 400 Given data cannot be encoded on our side. Please use utf-8 encoding.
ScopesInvalid 400 Specified scopes don't match with the ones specified in Provider or OAuthApp. More info in error_message
ConfigurationError 400 Missing configurations in dashboard.
PublicKeyInvalid 400 Given public key is not a public key.
RequestFormatInvalid 400 Request format is wrong. Details are stored in error_message
ValueOutOfRange 400 One of specified values are out of range.
SessionClosed 400 Session specified in request is already closed and cannot be modified.
JWTDecodeError 400 Authorization Token header has wrong format.
JWTExpiredSignature 400 Authorization Token header has expired.
JWTVerificationError 400 Salt Edge PSD2 Compliance could not verify specified Authorization Token
JWTIncorrectAlgorithm 400 Authorization Token was encrypted with incorrect algorithm. Please use RSA256 algorithm for encrypting.
JWTClaimMissing 400 Authorization Token expiration is not provided. Please specify exp alongside data field.
TokenMissing 400 This request cannot be performed without Access_Token header.
AccessDenied 401 Action you want to perform is not allowed. More in error_message
AuthorizationMissing 401 Authorization header is missing.
TokenExpired 401 Token specified in request is expired and cannot be used.
TokenNotFound 401 Token specified in request does not exist or cannot be retrieved.
TokenRevoked 401 Token specified in request is revoked and cannot be used anymore.
AuthTokenNotFound 401 Token specified in request does not exist or cannot be retrieved.
AuthorizationTypeNotFound 401 Authorization Type specified in request does not exist or cannot be retrieved.
WrongRequiredFields 401 Specified required fields were not provided. More info in error_message
ClientNotFound 401 Client specified in request does not exist or cannot be retrieved.
SessionExpired 401 Found session is expired and cannot be processed anymore.
SessionFinalised 403 Session specified in request is already finalised and cannot be processed.
UnknownCurrency 404 Unknown Currency code
PaymentNotFound 404 Payment specified in request does not exist or cannot be retrieved.
OauthAppNotFound 404 OAuth Application specified in request does not exist or cannot be retrieved.
TemplateNotFound 404 Template specified in request does not exist or cannot be retrieved.
TrustedBeneficiaryNotFound 404 Trusted Beneficiary specified in request does not exist or cannot be retrieved.
CertificateNotFound 404 Certificate has no permissions.
SessionNotFound 404 Session specified in request does not exist or cannot be retrieved.
AccountNotFound 404 Account specified in request does not exist or cannot be retrieved.
CustomerNotFound 404 PSU specified in request does not exist or cannot be retrieved.
ProviderNotFound 404 Provider specified in request does not exist or cannot be retrieved.
RouteNotFound 404 Wrong request URL.
FetchingError 404 There were some problems while fetching PSU's data. Please, retry later.
ClientDisabled 406 Cooperation with specified Client is impossible.
ProviderDisabled 406 Cooperation with specified Provider is impossible.
ActionNotAllowed 406 You're not allowed to perform this action. This might be a configuration problem or parameters incompatibility.
Deprecated 410 Specified resource has been deprecated and cannot be used anymore.
InternalServerError 500 Something went wrong on our side. You can report this behaviour, but most probably our developers have already started working on it.
InternalProviderError 500 Something went wrong on Provider(ASPSP) side.