Salt Edge PSD2 Compliance Logo



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:
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
In case you need any assistance on the above please contact us at:


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.
SCA Strong Customer Authentication using Salt Edge Authenticator.

Minimal requirements


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.

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.

New Test Authorization Type Form

The form contains 4 sections.

Section Example Description
Code oauth This field will be used by TPPs to communicate selected authorization type to Salt Edge PSD2 Compliance.
Display Name OAuth This field will be used by TPPs to present in Customer User Interface. Note that this field may be in any language, depending on Provider's country.
Scopes accounts, transactions, kyc This field will be used to limit and validate permissions of TPPs
Authorization Instruction Authentication via OAuth This field will be used by TPPs to prompt Customer with a hint on how to proceed with authentication.

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

Edit Authorization Type

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

Add Fields

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

Field Description
Code Used by TPPs to wrap values provided by Customer that will be sent to Connector.
Display Used by TPPs as a placeholder for said field.
Type Used by TPPs to determine required HTML input type for said field.
Optional Used by TPPs to determine whether the field is optional or not.

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.

Payment Templates

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.

Field Description
Description Human readable description that will be shown to Customer.
Payment type Unique template identifier which will be forwarded to Connector along with required payment attributes.
Default Should be ticked if a specific template should be selected by default.

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

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.

Field Description
Name Unique attribute identifier, will be used by TPPs to wrap values.
Label A human readable name, will be used by TPPs to show it to Customer.
Optional States whether the attribute is optional.
Type Type of attribute, may be text, number, dropdown.
Values Optional field, allows predefining possible values, only works with dropdown type.

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.

Endpoint Verb Purpose
/api/priora/v1/tokens/create POST Create an access token with a set of access rights, named scopes.
/api/priora/v1/tokens/confirm POST Confirm an existing access token
/api/priora/v1/tokens/revoke POST Revoke an existing access token, rendering it unusable further on
/api/priora/v1/tokens/cancel POST Cancel an existing access token before confirmation
/api/priora/v1/payments/show GET Get all information related to a payment order, be it one in progress or executed
/api/priora/v1/payments/create POST Initiate a payment order request
/api/priora/v1/payments/confirm POST Confirm an existing payment order request
/api/priora/v1/payments/cancel POST Cancel a payment order before confirmation
/api/priora/v1/payments/check_funds POST Check availability of funds for a specific account
/api/priora/v1/kyc GET Returns holder information associated with Customer
/api/priora/v1/accounts GET Returns Customer's accounts information
/api/priora/v1/transactions GET Returns Customer's transactions within the scope of an account

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": "" }, "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.
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

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.

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