Common Properties

The properties below are used in the calls to get statements, initiate payments, register a user, etc.
Depending on your working mode (Private or Gateway) some of them might not be necessary.

connectorId

Id of the connector/bank. All available connectors can be found at:
https://developer.bankingsdk.com/Connector/Index

userContext

For Private mode, serialized object containing user information for the specific connector(bank). Initially can be obtain
by calling POST /ais/user/register.
Can be updated when using other endpoints. TPP must store the latest version of that context for every
user/connector. We send it back in the response when it is modified.

For Gateway mode, you have one userContext by user, we handle the bank specific userContext internally.

tppContext

Additional TPP data for logging purposes. Following properties can be filled with any data.

• tppId
• app
• flow
• transaction
• unit

This structure contains five string fields that may contain arbitrary identifier values.

• They are not required,
• they are not used by the connectors
• nor transmitted to the bank,
• they are not supposed to mean something for us,
• keep them short, less then 50 chars.

You can consider them as a hierarchy in this order: app > unit > transaction > flow > tppId.

Those fields are stored in the bank call trace and they can used as dimensions later for records segmentation in statistics and billing.

bankSettings (Private mode only)

Settings to be used for connection with the bank. Use them only if they differ with default settings and
if they apply to the specific connector.

• ncaId – TPP NCA id / legal id,
• settingsId - a simple string that could contain your internal id of the bank credentials set used for this operation (see below)
• appClientId – client Id of the application for specific bank,
• appClientSecret – client secret of the application for specific bank,
• appApiKey – client API key of the application for specific bank,
• tlsCertificateName – PKCS12 QWAC (TLS) certificate file name with extension,
• tlsCertificatePassword – QWAC (TLS) certificate password,
• tlsCertificateKeyId – a key for QWAC (TLS) used by some banks (see bank's specific dev portal),
• signingCertificateName – PKCS12 QSEAL (signing) certificate file name with extension,
• signingCertificatePassword – QSEAL (signing) certificate password,
• signingCertificateKeyId – a key for QSEAL (signing) used by some banks (see bank's specific dev portal),
• pemFileUrl - URL to the QSEAL (signing) public key or JWSK

The TLS and signing certificates files are expected to be a PKCS12 file containing X509 and key.

Settings id

The (optional) string field "settingsId" in BankSettings field of the request allows you to memorize which bank settings you have used to establish a consent. This could be used when you have multiple certificates or bank credentials, e.g. switching to a new certificate. Example:

{
  "connectorId": 1,
  "bankSettings": {
    "settingsId": "11a3c36a-f8ef-4e10-b642-d8a9b87c6797",
    "ncaId": "PSDBE-...",
    "appClientId": "AZ98N47h6g...",

When you call get accounts, you'll found back the settingsId in the answer, for each accounts, in balance and transaction:

{
  "accounts": [
    {
      "id": "string",
      "currency": "string",
      "iban": "string",
      "description": "string",
      "transactionsConsent": {
        "consentId": "string",
        "validUntil": "2022-11-24T11:17:33.547Z",
        "status": 0,
        "statusAt": "2022-11-24T11:17:33.547Z",
        "settingsId": "11a3c36a-f8ef-4e10-b642-d8a9b87c6797"        
      },
      "balancesConsent": {
        "consentId": "string",
        "validUntil": "2022-11-24T11:17:33.547Z",
        "status": 0,
        "statusAt": "2022-11-24T11:17:33.547Z",
        "settingsId": "11a3c36a-f8ef-4e10-b642-d8a9b87c6797"        
      }
    }

This allows you to see which settings has been used during account access request to use them when getting balances or transactions or during the payment initiation to use htem

🚧

Only settingsId is stored in the usercontext. No certificates, no credentials are stored. You must pass the credentials and certificates in later calls as before

resultStatus

Indicates the result of the operation.
Available options:

• UNKNOWN (0);
• DONE (1) – operation completed;
• REDIRECT (2) – redirection necessary for SCA. After being redirected back to you, "finalize" method should be run;
• DECOUPLED (3) – SCA should be perform by PSU on bank application (outside of the flow of this SDK). The data you receive can be a simple text to display to the PSU, like "Please validate in you mobile bank app", a special link like an app link, e.g. "bankid:///xxx", that can be put in a button on phone or displayed as a QRCode on desktop to be scanned with the phone or an https link where you should redirect the PSU. After completion, "finalize" method should be run; Note that some banks returns a REDIRECT and, during this redirect check if the PSU is on phone, has the bank app installed and open this app to do the SCA;
• PASSWORD (4) – PSU password must be provided to "finalize" method;
• MORE_INFO (5) – some additional information must be provided to "finalize" method;
• SELECT_OPTION (6) – one of the provided options must be returned to "finalize" method;
• ERROR (7) – something went wrong;
• RETRY (8) – you must call again the end-point in a few seconds. Don't call too fast and stop after some minutes.

You may have multiple redirection to the bank. E.g. a first redirection to login the PSU, then a second redirection to confirm the payment. As a rule of thumb, you should be "looping" until you have an end of flow status (0/UNKNOWN, 1/DONE, 7/ERROR).

Note that, in gateway mode, options 4, 5, 6 are handled by the gateway. You can customize the CSS of those gateway pages in the settings of each application.

Go to https://developer.bankingsdk.com > Settings > Application, click on the "dice" buttons for each application

flowContext

Object generated by SDK containing necessary information to complete the flow. Must be passed
further to "finalize" method.