Changelog

Definitions

Minimal requirements

TLS

Salt Edge PSD2 Compliance Solution supports the following versions: TLSv1.2 and TLSv1.3.

Why does this matter?

Older TLS versions are vulnerable to security breaches with the wrong cipher suites. Be sure to upgrade your TLS version up to TLSv1.3.

What is TLS?

TLS stands for “Transport Layer Security.” It provides privacy and data integrity between two communicating applications. It is used to authenticate one or both applications, and protect the confidentiality and integrity of information that passes between them.

Registration and API Keys

Generate RSA key pair

openssl genrsa -out private.pem 2048
openssl rsa -pubout -in private.pem -out public.pem

1. Go to Bank Registration page and input your Bank's name, your email, and password.
2. Confirm your email address.
3. Provide your business details, such as legal name, address, and phone number.
4. Read and agree to Terms of Service.

After successful registration you may proceed to configure your Provider account.

1. Go to your connection details tab and save your app_id and app_secret. Please note that you may generate a new app_secret at any moment.
2. Provide the URL of your Connector implementation. This will be used to forward client requests to your Connector.
3. Generate at least 4096 bit RSA Key and export the RSA Public Key.
4. Go to your profile security tab and paste your RSA Public Key there. This key will be used to verify the signature of requests that come to Salt Edge PSD2 Compliance from your Connector instance.

Configure authorization types

In order to be able to authorize Customers, Bank should provide information regarding authorization types supported by Connector. This can be done via Settings page in Authorization Types tab.

A new authorization type can be created by clicking Create auth type button. Please make sure that code field is unique in terms of authorization types supported by your Bank, as it will be used by Salt Edge PSD2 Compliance to identify the authorization type used by TPPs.

The form contains 4 sections.

After submitting this form you will be able to add both required and interactive fields as well as modify freshly added authorization type.

You will have to proceed by adding either a required or MFA(Interactive) field.

The forms for adding Required and MFA fields are the same.

Configure payment templates

In order to be able to receive payment orders from TPPs, payment templates should be configured first. A payment template is a structure that corresponds to a payment type supported by the bank. These templates will be exposed to TPPs.

Any template can be switched between enabled and disabled states, which toggles its visibility to TPPs. In addition, a template can be removed. This action keeps the template for reference purpose, but marks it as removed permanently, rendering it unusable further on.

Each template contains three properties which are mandatory for configuration.

After creating a payment template, it is required to configure the payment attributes.

A payment attribute configuration consists of name, label, type, values (if it's a dropdown) and flag whether the attribute is optional or not.

Order in which attributes should appear may be selected on template configuration page.

API Endpoints

In order to receive callbacks as well as TPP request forwards, Connector must implement all of the following endpoints. These should respond to and with JSON payloads.

Request verification using JWT

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 send and receive signed requests to and from Connector. Connector is supposed to receive JWT signed requests from Salt Edge PSD2 Compliance on any of [Connector endpoints](#connector-endpoints) described in documentation and respond with a JSON. Connector is required to send a JWT signed request on any of [Salt Edge endpoints](#saltedge-endpoints) described in documentation and receive an empty JSON with a HTTP status code as a response.

Salt Edge PSD2 Compliance will always send requests 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", "scopes": [ "accounts", "transactions", "kyc", "payments", "funds_availability" ], "consent_period_days": 90, "credentials": { "required_key": "value" }, "redirect_url": "https://user.will.be/redirected/here" }, "exp": 1560162919 }

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. eyJkYXRhIjp7InByb3ZpZGVyX2NvZGUiOiJkZW1vYmFuayIsInNjb3BlcyI6WyJhY2NvdW50cyIsInRyYW5zYWN0aW9ucyIsImt5YyIsInBheW1lbnRzIiwiZnVuZHNfYXZhaWxhYmlsaXR5Il0sImNvbnNlbnRfcGVyaW9kX2RheXMiOjkwLCJjcmVkZW50aWFscyI6eyJyZXF1aXJlZF9rZXkiOiJ2YWx1ZSJ9LCJyZWRpcmVjdF91cmwiOiJodHRwczovL3VzZXIud2lsbC5iZS9yZWRpcmVjdGVkL2hlcmUifSwiZXhwIjoxNTYwMTYyOTE5fQ. O6edlfyG_tuh_ZHJC05gua1g9ZjIBDLev7wCJdDwm2ovCFWRR3vTOHhDf87dCNT3to-xW84iiYpeGWTDEzBQNug7TcJAIQF69bXr-Jh2hyT2Szlq44aWut-Qxr_nlQ7nfXaOfC30FfiG7TFq-njVY4-Z4Ham8hpnXkMy5b6PlMGaSmN6L9-QccdxpkS0ocXG3s0wHYi3P6WSUuGZIfXKVBDtud7qMkKzTEEl9xqhWHQiXeHxiM9SugzvU5CYfQd1H0KFw-qEUGIhXQc1OdaZNOAljawMCe8xwyqe5mYGnfCX6Cf1mR9zrp9MAxBB1Tfz61Km0aAYXKaa8HkQcqLDgA

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.

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