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

MaxStatementDays

Provides the max number of history days for which statement data can be downloaded via DownloadStatement(out SepaDocument, JsonObject, DateTime). Only available after a successful Login(JsonObject).

Declaration

int MaxStatementDays { get; }

Property Value

Type	Description
System.Int32

Remarks

By default the PSD2 RTS default value 90 should be assumed.

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.

Methods

DownloadBalances(out SepaBalance[], JsonObject)

Downloads and returns all available balances.

Declaration

ScraperResult DownloadBalances(out SepaBalance[] vaBalances, JsonObject jsAcct)

Parameters

Type	Name	Description
Subsembly.Sepa.SepaBalance[]	vaBalances	Array of balances with different Subsembly.Sepa.SepaBalanceType type. If the ScraperResult indicates success, then at least one balance must be returned in this array. On failure, a `null` reference shall be returned.
JsonObject	jsAcct

Returns

Type	Description
ScraperResult

Remarks

All implementations must return at least either an Subsembly.Sepa.SepaBalanceType.Expected balance (XPCD), or a Subsembly.Sepa.SepaBalanceType.ClosingBooked balance (CLBD). They may return both or even more balances. Additional permitted balance types are Subsembly.Sepa.SepaBalanceType.ClosingAvailable balance (CLAV) and Subsembly.Sepa.SepaBalanceType.ForwardAvailable balance (FWAV).

If a line of credit is available, then it should be included in the Subsembly.Sepa.SepaBalance.CreditLineAmount property of all returned balances.

DownloadDocument(out Byte[], JsonObject, JsonObject)

Download the PDF data for a particular document.

Declaration

ScraperResult DownloadDocument(out byte[] vbPDF, JsonObject jsAcct, JsonObject jsDoc)

Parameters

Type	Name	Description
System.Byte[]	vbPDF
JsonObject	jsAcct
JsonObject	jsDoc	Specification of the document for which to download the PDF data. The fields must be initialized accoring to SUPA. It is recommended to just pass the JSON object returned by DownloadDocumentList(out JsonArray, JsonObject, DateTime).

Returns

Type	Description
ScraperResult

DownloadDocumentList(out JsonArray, JsonObject, DateTime)

Download a list of available PDF documents for an account.

Declaration

ScraperResult DownloadDocumentList(out JsonArray jsDocList, JsonObject jsAcct, DateTime tFromDate)

Parameters

Type	Name	Description
JsonArray	jsDocList	Array of JSON objects with PDf document details accoring to the SUPA specification.
JsonObject	jsAcct
System.DateTime	tFromDate	The starting date from which documents should be returned, up to today. If this is `DateTime.MinValue`, then all available documents are returned.

Returns

Type	Description
ScraperResult

DownloadStatement(out SepaDocument, JsonObject, DateTime)

Download statement entries for the requested time period.

Declaration

ScraperResult DownloadStatement(out SepaDocument aCamtDoc, JsonObject jsAcct, DateTime tFromDate)

Parameters

Type	Name	Description
Subsembly.Sepa.SepaDocument	aCamtDoc	A complete and valid ISO 20022 CAMT document. Depending on the scraper implementation and data available, this may be either a CAMT.052 account report, or a CAMT.053 account statement. Usually this is a matter of whether the account service provides a closing balance, or not.
JsonObject	jsAcct
System.DateTime	tFromDate	The booking date from which statement entries shall be returned. If this is `DateTime.MinValue`, then all available statement entries are returned.

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