NAV
SaltEdge PSD2 Compliance Logo

Getting Started

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

I.e. AISP cerfificate will result into account, transactions, kyc scopes, while a PISP cerficate 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.

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

Using the API

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 senzitive data and the entire Salt Edge PSD2 Compliance Solution.

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.

Priora will send callbacks with a JWT signed by its private key . This allows Connector the ability to validate that the request form Priora 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 }

Priora 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:

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 Priora will be signed using Priora private key (RS256 alghorithm) in the form of a JWT containing exp and data claims that can be verified using Priora public key.

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 TTP to Priora 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 cerfiticate, 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 Priora 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.

Callbacks

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.

Sessions

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.
refresh_token Refreshing of an expired access token.
revoke_token Revocation of an access token.
refresh_accounts Instruction for Priora 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 Priora 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 Priora has received the information about Customer.
fetched_accounts Priora has received the accounts of Customer.
fetched_transactions Priora has received the transactions of Customer.
fetched_trusted_beneficiaries Priora has received the trusted beneficiaries of Customer.

Payments

Payment Statuses

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

Name Description
processing Priora 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.

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_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 has been already closed and cannot be modified.
JWTDecodeError 400 Authorization Token header has wrong format.
JWTExpiredSignature 400 Authorization Token header has been expired.
JWTVerificationError 400 SaltEdge PSD2 Compliance could not verify specified Authorization Token
JWTIncorrectAlgorithm 400 Authorization Token was encrypted with incorrect algorithm. Please use RSA256 algorithm for ecnrypting.
JWTClaimMissing 400 Authorization Token expiration is not provided. Please specify exp alongside data field.
AuthorizationMissing 400 Authorization header is missing.
TokenMissing 400 This request cannot be performed without Access_Token header.
RefreshTokenMissing 400 This request cannot be performed without Refresh-Token header.
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
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.
AuthTokenNotFound 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.
ClientNotFound 401 Client specified in request does not exist or cannot be retrieved.
SessionExpired 401 Found session has been expired and cannot be processed anymore.
AccountNotFound 404 Account specified in request does not exist or cannot be retrieved.
CustomerNotFound 404 Customer specified in request does not exist or cannot be retrieved.
PaymentNotFound 404 Payment 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.
OauthAppNotFound 404 OAuth Application specified in request does not exist or cannot be retrieved.
SessionNotFound 404 Session specified in request does not exist or cannot be retrieved.
TemplateNotFound 404 Template specified in request does not exist or cannot be retrieved.
FetchingError 404 There were some problems while fetching Customer's data. Please, retry later.
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.
Go to next page