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.

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

Returns

Type	Description
ScraperResult

DownloadDocumentList(out JsonArray, JsonObject)

Download a list of available PDF documents for an account.

Declaration

ScraperResult DownloadDocumentList(out JsonArray jsDocList, JsonObject jsAcct)

Parameters

Type	Name	Description
JsonArray	jsDocList	Array of JSON objects with PDf document details accoring to the SUPA specification.
JsonObject	jsAcct

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.