Changelog

Definitions

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.

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 requests 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.

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:

Events

Events are states of session and payment life cycles.

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

Session Actions

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

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:

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.