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.
public interface IScraperSession : IScraperPersist
- Inherited Members
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. |
Properties
Accounts
Provides a list of accounts after a successful Login(JsonObject).
JsonObject[] Accounts { get; }
Property Value
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.
IScraperContact Contact { get; }
Property Value
UserDetails
Additional details about the logged on user, retrieved from the PSP during Login(JsonObject).
JsonObject UserDetails { get; }
Property Value
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)
ScraperResult ContinueLogin(JsonObject jsCredential)
Parameters
jsCredential
JsonObjectThis 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
- 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)
ScraperResult Login(JsonObject jsCredential)
Parameters
jsCredential
JsonObjectThe 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 isfalse
or absent, then it is assumed that the request was done by some automated background service.
Returns
- 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.
void Logout()
Remarks
This method must not fail and cannot report any errors. If it really cannot logout, then it should just fail silently.