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.

AcctTpCd	The account type. Currently this must be either CACC for ordinary bank account, or CRDC for credit cards. This must always be provided.
AcctIBAN	IBAN of the account, if it has any. If no IBAN is available, e.g. for credit cards, then the field `AcctNo` must be used.
AcctNo	The domestic account number. For credit cards, this shall contain the credit card number. This field should always be provided.
AcctBIC	BIC of the account servicer of the account, if it has any.
AcctBankCode	Domestic bank code of the account servicer of the account, if it has any.
AcctCcy	Account currency ISO code. Only optional for securities portfolios. Mandatory for any other account specifications, including credit cards.
AcctCtry	For 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:

Name	The 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.
Identification	The unique identification code assigned to the logged on user by the PSP, e.g. a "VR Kennung" or a "Legitimations-ID".
DateOfBirth	The date of birth of the logged in user. This must be given as a string in ISO format, e.g. `2019-03-18`.
EMailAddresses	An array (!) of e-mail addresses of the logged in user.
PhoneNumbers	An array of phone numbers of the logged in user.
Addresses	An 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.
CardDetails	An 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.

CardHolderName	The name of the card holder as it is usually embossed on the card.
MaskedCardNumber	The 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.
CardProductName	A user readable credit card product description, e.g. "Miles & More Credit Card".

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
ChallengeResponse	If a challenge response was requested, then the challenge response value entered by the user shall be passed in this item.

Returns

Type	Description
ScraperResult	If log on was finally 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.

Type

Description

ScraperResult

If log on was finally 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.

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

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

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.