• Release Notes
  • Subsembly.Scraper
  • Subsembly.Json

Interface IScraperSession

This is the central interface that must be implemented by scrapers, or a web API client such as a PSD2 access to account (XS2A) API.

Inherited Members
IScraperPersist.Load(JsonObject)
IScraperPersist.Save()
IScraperPersist.IsDirty
Namespace: Subsembly.Scraper
Assembly: Subsembly.Scraper.dll
Syntax
public interface IScraperSession : IScraperPersist
Remarks

A scraper session must be serializable through the IScraperPersist base interface. A client may call any method on any thread during a session, but it must not invoke more than one method at a time.

There is a default implementation ScraperSession which can be used as a convenient base class for implementing a concrete scraper session.

An account is always identified by a JSON object that holds the account details. Which account details are required depends on the account type and the actual scraper implementation. In all cases the fields of the JSON object must be filled according to the Subsembly SUPA specification. The following fields may be used by a scraper implementation.

AcctTpCdThe account type. Currently this must be either CACC for ordinary bank account, or CRDC for credit cards. This must always be provided.
AcctIBANIBAN of the account, if it has any. If no IBAN is available, e.g. for credit cards, then the field AcctNo must be used.
AcctNoThe domestic account number. For credit cards, this shall contain the credit card number. This field should always be provided.
AcctBICBIC of the account servicer of the account, if it has any.
AcctBankCodeDomestic bank code of the account servicer of the account, if it has any.
AcctCcyAccount currency ISO code. Only optional for securities portfolios. Mandatory for any other account specifications, including credit cards.
AcctCtryFor bank accounts with domestic bank code and account number the country of the bank account must be provided. This is not needed for credit cards.
Additional fields may exist. These are to be ignored by scraper implementations.

Properties

Accounts

Provides a list of accounts after a successful Login(JsonObject).

Declaration
JsonObject[] Accounts { get; }
Property Value
Type Description
JsonObject[]
Remarks

If possible, then the scraper shall provide an array of JSON account objects for all accounts that are accessible by the most recent Login(JsonObject). If a list of accounts cannot be provided, then this property shall be null.

Contact

Back reference to IScraperContact instance that created this session.

Declaration
IScraperContact Contact { get; }
Property Value
Type Description
IScraperContact

UserDetails

Additional details about the logged on user, retrieved from the PSP during Login(JsonObject).

Declaration
JsonObject UserDetails { get; }
Property Value
Type Description
JsonObject
Remarks

This property is optional and my be null. If it is provided, then it may contain the following fields, each of which is optional:

NameThe first and/or last name of the logged on user, just as it was retrieved from the PSP. This is not necessarily the name of the account holder or card owner.
IdentificationThe unique identification code assigned to the logged on user by the PSP, e.g. a "VR Kennung" or a "Legitimations-ID".
DateOfBirthThe date of birth of the logged in user. This must be given as a string in ISO format, e.g. 2019-03-18.
EMailAddressesAn array (!) of e-mail addresses of the logged in user.
PhoneNumbersAn array of phone numbers of the logged in user.
AddressesAn array of street/city addresses of the logged in user in free text format. Each entry is multi-line field, seperated by a single newline character. If possible the first line should contain the street address, the second line should contain the post code and city name.
CardDetailsAn array (!) of objects with card details for every card that is accessible to the logged on user.

For every object in the CardDetails the following fields may be included.

CardHolderNameThe name of the card holder as it is usually embossed on the card.
MaskedCardNumberThe masked credit card number. This must not contain any blanks. It must only contain digits and the asterisk '*' as the mask character for unknown digits. Other mask characters are not allowed. The total length of the masked credit card number must conform to the usual length of credit card numbers of this PSP.

Methods

ContinueLogin(JsonObject)

Declaration
ScraperResult ContinueLogin(JsonObject jsCredential)
Parameters
Type Name Description
JsonObject jsCredential

This must include all the credentials that have been passed to Login(JsonObject) and additional data, as required by the ScraperResult returned from Login(JsonObject). Depending on the scraper this may be fields like:

OAuthToken
ChallengeResponseIf a challenge response was requested, then the challenge response value entered by the user shall be passed in this item.

Returns
Type Description
ScraperResult

Login(JsonObject)

Declaration
ScraperResult Login(JsonObject jsCredential)
Parameters
Type Name Description
JsonObject jsCredential

The users login credentials. Must not be null. Depending on the scraper this may contain the following items:

UserID
Password
UserInvolvedIf this log-in was triggered interactively from the account owning user, then this boolean value shall be included with the value true. If this is false or absent, then it is assumed that the request was done by some automated background service.

Returns
Type Description
ScraperResult

If log on was successful, then a ScraperResult with Success will be returned. If the service needs an additional challenge response for a successful log on, then ChallengeResponseNeeded is returned. If so, the client shall obtain the challenge response from the given challenge and call ContinueLogin(JsonObject), including the ChallengeResponse.

If log on failed because the credentials probably have been wrong, then the special LoginFailure must be returned. Only if a log on failure is certainly not due to wrong credentials, then some other failure code may be returned.

Logout()

Unconditionally log out from service.

Declaration
void Logout()
Remarks

This method must not fail and cannot report any errors. If it really cannot logout, then it should just fail silently.

Back to top Copyright 2017-2022 Subsembly GmbH