• API Overview
  • EBICS API
  • FinTS API
  • XS2A API
  • SEPA API
Search Results for

    Class EbicsContact

    Collects all information required for EBICS communication of a particular user with a particular bank.

    Inheritance
    System.Object
    EbicsElement
    EbicsContact
    Implements
    IEbicsJsonConverter
    Inherited Members
    EbicsElement.BuildXmlDocument(EbicsVersion)
    EbicsElement.Load(Stream, EbicsVersion)
    EbicsElement.Load(String, EbicsVersion)
    EbicsElement.Save(Stream, EbicsVersion)
    EbicsElement.Save(String, EbicsVersion)
    EbicsElement.FromBuffer(EbicsDataBuffer, EbicsVersion)
    EbicsElement.ToBuffer(EbicsVersion)
    System.Object.Equals(System.Object)
    System.Object.Equals(System.Object, System.Object)
    System.Object.GetHashCode()
    System.Object.GetType()
    System.Object.MemberwiseClone()
    System.Object.ReferenceEquals(System.Object, System.Object)
    Namespace: Subsembly.EBICS
    Assembly: Subsembly.EBICS.Core.dll
    Syntax
    public sealed class EbicsContact : EbicsElement, IEbicsJsonConverter
    Remarks

    Whenever a property is changed the complete contact data is re-saved in it's ContactFolder. Thus, in order to optimize updating multiple properties the method BeginUpdate() should be called before, and the method EndUpdate() should be called after changing the properties. This ensures that the contact data is only saved once at the end of the update.

    Constructors

    EbicsContact()

    Declaration
    public EbicsContact()

    EbicsContact(EbicsContact)

    Creates a new EbicsContact using another EbicsContact as an initialisation template.

    Declaration
    public EbicsContact(EbicsContact aContact)
    Parameters
    Type Name Description
    EbicsContact aContact
    Remarks

    As it is a new EbicsContact it is initialised with a new ContactGuid. The new contact is not added to an IEbicsContactFolder. None of user or bank keys are copied to the newly created contact.

    Exceptions
    Type Condition
    System.ArgumentNullException

    The parameter aContactwas null.

    EbicsContact(EbicsVersion)

    Creates an all new EBICS contact from scratch.

    Declaration
    public EbicsContact(EbicsVersion nVersion)
    Parameters
    Type Name Description
    EbicsVersion nVersion

    The EBICS version for which to create a new contact. Use the value Default to create a contact for the recommended default EBICS version.

    Fields

    DEFAULTHOSTTIMEOUT

    The default host response timeout in milliseconds.

    Declaration
    public const int DEFAULTHOSTTIMEOUT = 60000
    Field Value
    Type Description
    System.Int32

    MAXHOSTIDLENGTH

    Maximum length of HostID (=35).

    Declaration
    public const int MAXHOSTIDLENGTH = 35
    Field Value
    Type Description
    System.Int32
    Remarks

    In earlier EBICS versions the maximum length of the HostID was defined as 8 characters. In the current version it is 35 characters, which is the value that is defined here.

    MAXPARTNERIDLENGTH

    Maximum length of PartnerID (=35).

    Declaration
    public const int MAXPARTNERIDLENGTH = 35
    Field Value
    Type Description
    System.Int32
    Remarks

    In earlier EBICS versions the maximum length of the PartnerID was defined as 8 characters. In the current version it is 35 characters, which is the value that is defined here.

    MAXSYSTEMIDLENGTH

    Maximum length of SystemID (=35).

    Declaration
    public const int MAXSYSTEMIDLENGTH = 35
    Field Value
    Type Description
    System.Int32
    Remarks

    In earlier EBICS versions the maximum length of the SystemID was defined as 8 characters. In the current version it is 35 characters, which is the value that is defined here.

    MAXUSERIDLENGTH

    Maximum length of UserID (=35).

    Declaration
    public const int MAXUSERIDLENGTH = 35
    Field Value
    Type Description
    System.Int32
    Remarks

    In earlier EBICS versions the maximum length of the UserID was defined as 8 characters. In the current version it is 35 characters, which is the value that is defined here.

    Properties

    AuthenticationVersion

    Declaration
    public EbicsSecurityCode AuthenticationVersion { get; set; }
    Property Value
    Type Description
    EbicsSecurityCode

    BankAuthenticationPubKey

    Declaration
    public EbicsPubKeyInfo BankAuthenticationPubKey { get; set; }
    Property Value
    Type Description
    EbicsPubKeyInfo

    BankEncryptionPubKey

    Declaration
    public EbicsPubKeyInfo BankEncryptionPubKey { get; set; }
    Property Value
    Type Description
    EbicsPubKeyInfo

    CanCreateIniLetter

    Indicates whether all information and public keys that are needed by CreateIniLetter(String, String) is available in this contant.

    Declaration
    public bool CanCreateIniLetter { get; }
    Property Value
    Type Description
    System.Boolean

    ContactFolder

    The ContactFolder from which this EbicsContact instance was loaded.

    Declaration
    public IEbicsContactFolder ContactFolder { get; set; }
    Property Value
    Type Description
    IEbicsContactFolder

    ContactGuid

    A GUID that uniquely identifies this contact.

    Declaration
    public Guid ContactGuid { get; }
    Property Value
    Type Description
    System.Guid
    Remarks

    This property is managed automatically by the EbicsContact class and therefore can only be read. A newly created EbicsContact will always get a new GUID. If an EbicsContact instance is stored, its GUID is stored with it, and also restored when loaded.

    This GUID is used as the primary key when storing an EbicsContact in an IEbicsContactFolder.

    ContactName

    Optional human readable contact name.

    Declaration
    public string ContactName { get; set; }
    Property Value
    Type Description
    System.String

    The contact name may be null or a nonempty string of up to 256 characters. The default value of this property is null.

    Exceptions
    Type Condition
    System.ArgumentException

    An attempt was made to set an empty contact name string.

    CountryCode

    Two letter ISO country code. If this is not set, then "DE" will be assumed.

    Declaration
    public string CountryCode { get; set; }
    Property Value
    Type Description
    System.String
    Remarks

    The country code is needed to adopt to national variations in the EBICS implementation. In particular it is needed to enable keys with certificates in France.

    DefaultAuthorisationLevel

    The default authorisation level for signatures created by this user.

    Declaration
    public EbicsAuthorisationLevel DefaultAuthorisationLevel { get; set; }
    Property Value
    Type Description
    EbicsAuthorisationLevel
    Remarks

    This authorisation level is only applied, if the AuthorisationLevel was not explicitly set. If this is Null, then a default signature will be assumed by Send(EbicsOrder, IEbicsSecurityMedium, IEbicsTransport).

    EncryptionVersion

    Declaration
    public EbicsSecurityCode EncryptionVersion { get; set; }
    Property Value
    Type Description
    EbicsSecurityCode

    HaveBankKeys

    Declaration
    public bool HaveBankKeys { get; }
    Property Value
    Type Description
    System.Boolean

    HaveUserKeys

    Declaration
    public bool HaveUserKeys { get; }
    Property Value
    Type Description
    System.Boolean

    HostID

    Declaration
    public string HostID { get; set; }
    Property Value
    Type Description
    System.String

    HostTimeout

    Response timeout for each message in milliseconds.

    Declaration
    public int HostTimeout { get; set; }
    Property Value
    Type Description
    System.Int32

    Time in milliseconds. Must not be negative. The value zero means that the timeout is not set, and thus the DEFAULTHOSTTIMEOUT shall be used.

    Remarks

    After sending a request message to the EBICS host, the transaction engine will at most wait HostTimeout milliseconds for a response message from the EBICS host. If the EBICS host does not respond within this timeout, then the transaction is aborted.

    HostURL

    The complete URL to the EBICS host including the https: prefix.

    Declaration
    public string HostURL { get; set; }
    Property Value
    Type Description
    System.String

    IniLetterNeeded

    Stored flag that indicates whether an Ini-Letter must probably be sent for this contact.

    Declaration
    public bool IniLetterNeeded { get; set; }
    Property Value
    Type Description
    System.Boolean
    Remarks

    This is just a stored flag and no real indication of the user state. The flag is set, whenever all new keys are created for the user. It is reset, whenever an Ini-Letter is generated.

    Parameters

    Collection of additional custom parameters

    Declaration
    public EbicsParameters Parameters { get; }
    Property Value
    Type Description
    EbicsParameters
    Remarks

    This EbicsParameters collection can be used to store additional custom parameters with this contact.

    PartnerID

    Declaration
    public string PartnerID { get; set; }
    Property Value
    Type Description
    System.String

    SecurityMedium

    The value for the EBICS SecurityMedium XML element.

    Declaration
    public string SecurityMedium { get; set; }
    Property Value
    Type Description
    System.String

    SecurityMediumAssemblyName

    Optional name of assembly that contains a custom implementation of the IEbicsSecurityMedium interface for this contact.

    Declaration
    public string SecurityMediumAssemblyName { get; set; }
    Property Value
    Type Description
    System.String

    SecurityMediumClassName

    Name of class that implements the IEbicsSecurityMedium interface for this contact.

    Declaration
    public string SecurityMediumClassName { get; set; }
    Property Value
    Type Description
    System.String

    If this is null, then a default implementation based on the SecurityMediumType will be used. The default value is null

    SecurityMediumID

    Declaration
    public string SecurityMediumID { get; set; }
    Property Value
    Type Description
    System.String

    SecurityMediumType

    Selects the implementation of the user's security medium.

    Declaration
    public EbicsSecurityMediumType SecurityMediumType { get; set; }
    Property Value
    Type Description
    EbicsSecurityMediumType

    ServiceMap

    The EbicsServiceMap that shall be used with this contact.

    Declaration
    public EbicsServiceMap ServiceMap { get; set; }
    Property Value
    Type Description
    EbicsServiceMap
    Remarks

    This value is temporary and is not persisted. It must be set again whenever a EbicsContact is loaded.

    If the ServiceMap is not set, then a well known service map for the CountryCode will be returned, if available. If there is no well known service map, then the universal Default service map will be returned. Hence, the return value is never null.

    SignatureVersion

    Declaration
    public EbicsSecurityCode SignatureVersion { get; set; }
    Property Value
    Type Description
    EbicsSecurityCode

    SpoolerActions

    Chooses whether this contact opts-in to automated EBICS Spooler processing.

    Declaration
    public EbicsFileSpoolerActions SpoolerActions { get; set; }
    Property Value
    Type Description
    EbicsFileSpoolerActions

    By default all contacts are excluded from automated EBICS Spooler processing. This boolean must be set in order to opt-in.

    SpoolerOrderTypeC52

    The classic EBICS order type that the EBICS spooler uses for CAMT 052 downloads.

    Declaration
    public string SpoolerOrderTypeC52 { get; set; }
    Property Value
    Type Description
    System.String

    If this is null, then the default "C52" is used. This may be set to "VMK" to download SWIFT MT-942 and have it converted automatically to CAMT 052.

    Exceptions
    Type Condition
    System.ArgumentException

    An attempt was made to set a non-null value that is not a valid order type.

    SpoolerOrderTypeC53

    The classic EBICS order type that the EBICS spooler uses for CAMT 053 downloads.

    Declaration
    public string SpoolerOrderTypeC53 { get; set; }
    Property Value
    Type Description
    System.String

    If this is null, then the default "C53" is used. This may be set to "STA" to download SWIFT MT-940 and have it converted automatically to CAMT 053.

    Exceptions
    Type Condition
    System.ArgumentException

    An attempt was made to set a non-null value that is not a valid order type.

    SpoolerOrderTypeC54

    The classic EBICS order type that the EBICS spooler uses for CAMT 054 downloads.

    Declaration
    public string SpoolerOrderTypeC54 { get; set; }
    Property Value
    Type Description
    System.String

    If this is null, then the default "C54" is used.

    Exceptions
    Type Condition
    System.ArgumentException

    An attempt was made to set a non-null value that is not a valid order type.

    SpoolerOrderTypeHAC

    The classic EBICS order type that the EBICS spooler uses for EBICS protocol downloads.

    Declaration
    public string SpoolerOrderTypeHAC { get; set; }
    Property Value
    Type Description
    System.String

    If this is null, then the default "HAC" is used. This may be set to "PTK" to download old style text protocols.

    Exceptions
    Type Condition
    System.ArgumentException

    An attempt was made to set a non-null value that is not a valid order type.

    SpoolerSecret

    This field is reserved for the EBICS spooler to store secret data needed for execution.

    Declaration
    public string SpoolerSecret { get; set; }
    Property Value
    Type Description
    System.String

    This value is only meaningful to the EbicsFileSpooler. To store a password the EbicsFileSpooler method StorePassword(EbicsContact, String) must be used. A masked password pattern for the stored password can be obtained via GetPasswordPlaceholder(EbicsContact). Setting this property to null effectively clears any stored password.

    SystemID

    Declaration
    public string SystemID { get; set; }
    Property Value
    Type Description
    System.String

    UserAuthenticationPubKey

    Declaration
    public EbicsPubKeyInfo UserAuthenticationPubKey { get; }
    Property Value
    Type Description
    EbicsPubKeyInfo

    UserEncryptionPubKey

    Declaration
    public EbicsPubKeyInfo UserEncryptionPubKey { get; }
    Property Value
    Type Description
    EbicsPubKeyInfo

    UserID

    Declaration
    public string UserID { get; set; }
    Property Value
    Type Description
    System.String

    UserSignaturePubKey

    Declaration
    public EbicsPubKeyInfo UserSignaturePubKey { get; }
    Property Value
    Type Description
    EbicsPubKeyInfo

    UsesCertificates

    Indicates whether this EBICS user uses keys with X.509 certificates.

    Declaration
    public bool UsesCertificates { get; }
    Property Value
    Type Description
    System.Boolean
    Remarks

    Starting with EBICS 3.0 the usage of X.509 certificates is mandatory. When connecting to a French system, X.509 certificates are also mandatory for older EBICS versions.

    Version

    Declaration
    public EbicsVersion Version { get; set; }
    Property Value
    Type Description
    EbicsVersion

    Methods

    AdoptSecurityKeyFile(String, String, Boolean, Boolean, out String)

    Adopt the given key file as the security medium for this EbicsContact.

    Declaration
    public bool AdoptSecurityKeyFile(string sKeyFilePath, string sKeyFilePassword, bool fAdoptContact, bool fInternalizeKeyFile, out string sErrorMessage)
    Parameters
    Type Name Description
    System.String sKeyFilePath

    Complete path and filename to the key file to be adopted. The EbicsContact will store a reference to this path, so the key file must remain at this location, even after it was adopted, unless the parameter fInternalizeKeyFile was true.

    System.String sKeyFilePassword
    System.Boolean fAdoptContact

    If true, then an attempt is made to read EBICS contact data (HostID, UserID, etc.) from the key file. The contact data from the key file will overwrite the existing contact data in this contact.

    System.Boolean fInternalizeKeyFile

    If true, then all key data, including the private keys, will be imported into this contact. The external key file is no longer needed after the key file was imported. The internalized key file will still require the entry of the same key file password.

    System.String sErrorMessage
    Returns
    Type Description
    System.Boolean

    AdoptSecurityMedium(IEbicsSecurityMedium)

    Adopt the given security medium for this EbicsContact.

    Declaration
    public void AdoptSecurityMedium(IEbicsSecurityMedium aSecurityMedium)
    Parameters
    Type Name Description
    IEbicsSecurityMedium aSecurityMedium

    The security medium that shall be adopted. This can be in any state. It is NOT released by this method. It is up to the caller to release the security when he is done with it.

    Remarks

    This method will set all security and security medium related properties of this instance to effectively adopt the given security medium. It may also change the Version if needed to match the security medium.

    Exceptions
    Type Condition
    System.ArgumentNullException

    The parameter aSecurityMedium was null.

    Authenticate(String)

    Obtains a new authenticated security medium instance for this contact.

    Declaration
    public IEbicsSecurityMedium Authenticate(string sPassword)
    Parameters
    Type Name Description
    System.String sPassword

    The password (or PIN) that shall be used to authenticate the security medium configured for this contact.

    Returns
    Type Description
    IEbicsSecurityMedium

    Always returns an authenticated IEbicsSecurityMedium instance. This never returns null, as errors are thrown as exceptions.

    Exceptions
    Type Condition
    System.InvalidOperationException

    No security medium is configured for this contact.

    EbicsException

    If the security medium could not be authenticated, then an EbicsException will be thrown.

    BeginUpdate()

    Begin a series of property changes.

    Declaration
    public void BeginUpdate()
    Remarks

    Changing multiple properties should be optimized by calling this method before changing the properties and EndUpdate() after changing the properties.

    BlockKeys(IEbicsSecurityMedium, IEbicsTransport)

    Creates an EbicsOrderSPR instance and uses it to block the users keys at the bank (SPR).

    Declaration
    public EbicsOrderSPR BlockKeys(IEbicsSecurityMedium aSecMedium, IEbicsTransport aTransport = null)
    Parameters
    Type Name Description
    IEbicsSecurityMedium aSecMedium

    Authenticated security medium of the user. Must not be null.

    IEbicsTransport aTransport

    An IEbicsTransport implementation for sending the HTTP request. If this is null, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

    Returns
    Type Description
    EbicsOrderSPR

    Returns the created EbicsOrderSPR instance. This can be used to check whether the request was successful.

    BuildXml(XmlDocument, EbicsVersion)

    Declaration
    public override XmlElement BuildXml(XmlDocument xmlDocument, EbicsVersion nEbicsVersion)
    Parameters
    Type Name Description
    System.Xml.XmlDocument xmlDocument
    EbicsVersion nEbicsVersion

    The given EBICS version is currently ignored but should be Contact in order to ensure compatibility with future versions.

    Returns
    Type Description
    System.Xml.XmlElement
    Overrides
    EbicsElement.BuildXml(XmlDocument, EbicsVersion)
    Remarks

    This method always builds an XML element according to its own rules using an unnamed default namespace.

    ChangeKeys(IEbicsSecurityMedium, EbicsSecurityCode, EbicsSecurityCode, EbicsSecurityCode, IEbicsTransport)

    Creates a complete set of new user keys (signature, authentication and encryption) and initiates a user key update via HCS upload order.

    Declaration
    public EbicsOrderHCS ChangeKeys(IEbicsSecurityMedium aSecMedium, EbicsSecurityCode nSignatureVersion, EbicsSecurityCode nAuthenticationVersion, EbicsSecurityCode nEncryptionVersion, IEbicsTransport aTransport = null)
    Parameters
    Type Name Description
    IEbicsSecurityMedium aSecMedium

    Authenticated security medium of the user for the new keys. Must not be null. This security medium must implement IEbicsSecurityMediumPrivKeys, hence smart cards are not supported.

    EbicsSecurityCode nSignatureVersion

    New User Signature Key Version. This must be either A004, A005, or A006. If this contact already uses H005, or later, then A004 is not allowed.

    EbicsSecurityCode nAuthenticationVersion

    The Version of the new Authentication Key. This must be either X001, or X002.

    EbicsSecurityCode nEncryptionVersion

    The Version of the new Encryption Key. This must be either E001, or E002.

    IEbicsTransport aTransport

    An IEbicsTransport implementation for sending the HTTP request. If this is null, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

    Returns
    Type Description
    EbicsOrderHCS
    Exceptions
    Type Condition
    System.ArgumentNullException

    Either aSecMedium or aTransport was null.

    System.ArgumentException

    An invalid value for nSignatureVersion, nAuthenticationVersion, or nEncryptionVersion was given.

    System.InvalidOperationException

    The given aSecMedium does not support management of private keys.

    ChangeSystemKeys(IEbicsSecurityMedium, EbicsSecurityCode, EbicsSecurityCode, IEbicsTransport)

    Creates an EbicsOrderHCA instance and uses it to change the system keys (HCA)

    Declaration
    public EbicsOrderHCA ChangeSystemKeys(IEbicsSecurityMedium aSecMedium, EbicsSecurityCode nAuthenticationVersion, EbicsSecurityCode nEncryptionVersion, IEbicsTransport aTransport = null)
    Parameters
    Type Name Description
    IEbicsSecurityMedium aSecMedium

    Authenticated security medium of the user. Must not be null. This security medium must implement IEbicsSecurityMediumPrivKeys, hence smart cards are not supported.

    EbicsSecurityCode nAuthenticationVersion

    The Version of the new Authentication Key. This must be either X001, or X002.

    EbicsSecurityCode nEncryptionVersion

    The Version of the new Encryption Key. This must be either E001, or E002.

    IEbicsTransport aTransport

    An IEbicsTransport implementation for sending the HTTP request. If this is null, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

    Returns
    Type Description
    EbicsOrderHCA

    Returns the EbicsOrderHCA that was built and sent. This can be used to determine whether the key change transaction was successful.

    Exceptions
    Type Condition
    System.ArgumentNullException

    Either aSecMedium or aTransport was null.

    System.ArgumentException

    An invalid value for nAuthenticationVersion or nEncryptionVersion was given.

    System.InvalidOperationException

    The given aSecMedium does not support management of private keys.

    ChangeUserKey(IEbicsSecurityMedium, EbicsSecurityCode, IEbicsTransport)

    Creates an EbicsOrderPUB instance and uses it to change the users signature key (PUB).

    Declaration
    public EbicsOrderPUB ChangeUserKey(IEbicsSecurityMedium aSecMedium, EbicsSecurityCode nSignatureVersion, IEbicsTransport aTransport = null)
    Parameters
    Type Name Description
    IEbicsSecurityMedium aSecMedium

    Authenticated security medium of the user for the new key. Must not be null. This security medium must implement IEbicsSecurityMediumPrivKeys, hence smart cards are not supported.

    EbicsSecurityCode nSignatureVersion

    New User Signature Key Version. This must be either A004, A005, or A006. If this contact already uses H005, or later, then A004 is not allowed.

    IEbicsTransport aTransport

    An IEbicsTransport implementation for sending the HTTP request. If this is null, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

    Returns
    Type Description
    EbicsOrderPUB

    Returns the EbicsOrderPUB that was built and sent. This can be used to determine whether the key change transaction was successful.

    Exceptions
    Type Condition
    System.ArgumentNullException

    Either aSecMedium or aTransport was null.

    System.ArgumentException

    An invalid value for nSignatureVersion was given.

    System.InvalidOperationException

    The given aSecMedium does not support management of private keys.

    Clone()

    Declaration
    public EbicsContact Clone()
    Returns
    Type Description
    EbicsContact
    Remarks

    see EbicsContact(EbicsContact)

    CreateContact(JsonObject)

    Creates an new EbicsContact from its json representation.

    Declaration
    public static EbicsContact CreateContact(JsonObject jsonContact)
    Parameters
    Type Name Description
    JsonObject jsonContact

    json representation of an EbicsContact. The version property is mandatory.

    Returns
    Type Description
    EbicsContact
    Exceptions
    Type Condition
    System.ArgumentNullException

    The specified jsonContact was null.

    System.ArgumentException

    The specified jsonContact doesn't contain a 'version' element.

    CreateIniLetter(String)

    Creates an Ini-Letter document that can be printed or converted to a PDF.

    Declaration
    public ReportDocument CreateIniLetter(string sFooterText)
    Parameters
    Type Name Description
    System.String sFooterText

    Optional text that is added at the bottom of each page. If this is null, then a default footer test is added. In order to remove the footer, pass an empty string in this parameter.

    Returns
    Type Description
    Subsembly.Printing.ReportDocument
    Remarks

    Invoke the methods CreatePDF or WritePDF on the returned document in order to create a binary PDF representation.

    See Also
    CreateIniLetter(String, String)
    EbicsIniLetter

    CreateIniLetter(String, String)

    Creates an Ini-Letter document that can be printed or converted to a PDF.

    Declaration
    public ReportDocument CreateIniLetter(string sAddressLines, string sFooterText)
    Parameters
    Type Name Description
    System.String sAddressLines

    Optional address text that is included at the top of the first page. The address lines must be separated by CRLF or just LF characters.

    System.String sFooterText

    Optional text that is added at the bottom of each page. If this is null, then a default footer test is added. In order to remove the footer, pass an empty string in this parameter.

    Returns
    Type Description
    Subsembly.Printing.ReportDocument
    Remarks

    Invoke the methods CreatePDF or WritePDF on the returned document in order to create a binary PDF representation.

    See Also
    EbicsIniLetter

    CreateSecurityMedium()

    Creates a new instance of the IEbicsSecurityMedium implementation required for this contact.

    Declaration
    public IEbicsSecurityMedium CreateSecurityMedium()
    Returns
    Type Description
    IEbicsSecurityMedium

    DownloadBankKeys(IEbicsSecurityMedium, IEbicsTransport)

    Creates an EbicsOrderHPB instance and uses it to download the bank keys (HPB).

    Declaration
    public EbicsOrderHPB DownloadBankKeys(IEbicsSecurityMedium aSecMedium, IEbicsTransport aTransport = null)
    Parameters
    Type Name Description
    IEbicsSecurityMedium aSecMedium

    Authenticated security medium of the user. Must not be null.

    IEbicsTransport aTransport

    An IEbicsTransport implementation for sending the HTTP request. If this is null, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

    Returns
    Type Description
    EbicsOrderHPB

    If the transaction was sent, then the completed EbicsOrderHPB instance is returned. If the transaction could not be built, then null is returned.

    Even if successful, the downloaded bank keys are NOT stored in the given EbicsContact. The downloaded bank keys are only returned through the EbicsOrderHPB instance. It is up to the caller to store these bank keys in this contact.

    EndUpdate()

    Finish a series of property changes.

    Declaration
    public void EndUpdate()

    ExportKeys(String, String, String, Boolean)

    Export all user keys and user data from this contact into a new, external key file.

    Declaration
    public EbicsSecurityMediumErrorCode ExportKeys(string sFilename, string sContactPassword, string sKeyFilePassword, bool fAdoptKeyFile)
    Parameters
    Type Name Description
    System.String sFilename

    The complete path of the new key file that shall be created.

    System.String sContactPassword

    The password for this contact.

    System.String sKeyFilePassword

    Password that will be used for the new key file.

    System.Boolean fAdoptKeyFile

    If this is true, then this EbicsContact will be reconfigured to reference the newly created external key file and dismiss the previous security medium.

    Returns
    Type Description
    EbicsSecurityMediumErrorCode

    If the export was successful, then the explicit value Success is returned. If the export failed, then a suitable error code will be returned.

    Exceptions
    Type Condition
    System.ArgumentNullException

    Any of the parameters was null.

    ExpulseSecurityMedium()

    Reset all any any information about the security medium associated with this contact.

    Declaration
    public void ExpulseSecurityMedium()

    FromJson(JsonObject)

    Initializes an EbicsContact from its json representation. FromJson(JsonObject).

    Declaration
    public void FromJson(JsonObject jsonObject)
    Parameters
    Type Name Description
    JsonObject jsonObject

    ImportKeys(String)

    Declaration
    public EbicsSecurityMediumErrorCode ImportKeys(string sPassword)
    Parameters
    Type Name Description
    System.String sPassword
    Returns
    Type Description
    EbicsSecurityMediumErrorCode

    LoadContact(String)

    Load an EbicsContact from a file where it was previously saved.

    Declaration
    public static EbicsContact LoadContact(string sFileName)
    Parameters
    Type Name Description
    System.String sFileName
    Returns
    Type Description
    EbicsContact

    ModifyContact(JsonObject)

    Declaration
    public void ModifyContact(JsonObject jsonObjectChanges)
    Parameters
    Type Name Description
    JsonObject jsonObjectChanges

    ParseXml(XmlElement, EbicsVersion)

    Declaration
    public override void ParseXml(XmlElement xmlElement, EbicsVersion nEbicsVersion)
    Parameters
    Type Name Description
    System.Xml.XmlElement xmlElement
    EbicsVersion nEbicsVersion

    The given EBICS version is currently ignored but should be Contact in order to ensure compatibility with future versions.

    Overrides
    EbicsElement.ParseXml(XmlElement, EbicsVersion)
    Remarks

    This method always expects an XML element that was built by BuildXml(XmlDocument, EbicsVersion) which uses an unnamed default namespace.

    Send(EbicsOrder, IEbicsSecurityMedium, IEbicsTransport)

    Send an EBICS order, authenticated by this contact.

    Declaration
    public EbicsErrorClass Send(EbicsOrder aOrder, IEbicsSecurityMedium aSecurityMedium, IEbicsTransport aTransport = null)
    Parameters
    Type Name Description
    EbicsOrder aOrder
    IEbicsSecurityMedium aSecurityMedium

    Authenticated security medium which will be used to create the authentication signature on the EBICS request. Must not be null. The referenced security medium must be in the Authenticated state.

    IEbicsTransport aTransport

    An IEbicsTransport implementation for sending the HTTP request. If this is null, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

    Returns
    Type Description
    EbicsErrorClass

    Returns the worse error class from the technical and business return codes (if any). If some error with the security medium occured, then SecurityMediumError is returned. If the transaction failed completely without ever receiving a return code, then an exception is thrown.

    Remarks

    This method automatically signs any upload orders that require a signature, unless they are already signed.

    Exceptions
    Type Condition
    System.ArgumentNullException

    One of the arguments was null.

    System.ArgumentException

    Either the given EbicsOrder was incomplete or the security medium was not in the Authenticated state.

    See Also
    Send(EbicsOrder, String)

    Send(EbicsOrder, String)

    Send an EBICS order on behalf of this contact.

    Declaration
    public EbicsErrorClass Send(EbicsOrder aOrder, string sPassword)
    Parameters
    Type Name Description
    EbicsOrder aOrder
    System.String sPassword

    The password or PIN that shall be used to authenticate the security medium configured for this contact. This must not be null.

    Returns
    Type Description
    EbicsErrorClass
    Remarks

    This method does not work with smart card readers with secure PIN entry.

    Exceptions
    Type Condition
    System.InvalidOperationException

    This contact is not ready for sending orders.

    EbicsException

    The security medium is not available or could not be authenticated.

    Send(EbicsOrder, String, IEbicsTransport)

    Send an EBICS order on behalf of this contact.

    Declaration
    public EbicsErrorClass Send(EbicsOrder aOrder, string sPassword, IEbicsTransport aTransport = null)
    Parameters
    Type Name Description
    EbicsOrder aOrder
    System.String sPassword

    The password or PIN that shall be used to authenticate the security medium configured for this contact. This must not be null.

    IEbicsTransport aTransport

    An IEbicsTransport implementation for sending the HTTP request. If this is null, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

    Returns
    Type Description
    EbicsErrorClass
    Remarks

    This method does not work with smart card readers with secure PIN entry.

    Exceptions
    Type Condition
    System.InvalidOperationException

    This contact is not ready for sending orders.

    EbicsException

    The security medium is not available or could not be authenticated.

    SendSystemKeys(IEbicsSecurityMedium, IEbicsTransport)

    Creates an EbicsOrderHIA instance and uses it to sends the system keys to the bank (HIA).

    Declaration
    public EbicsOrderHIA SendSystemKeys(IEbicsSecurityMedium aSecMedium, IEbicsTransport aTransport = null)
    Parameters
    Type Name Description
    IEbicsSecurityMedium aSecMedium

    Authenticated security medium of the user. Must not be null.

    IEbicsTransport aTransport

    An IEbicsTransport implementation for sending the HTTP request. If this is null, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

    Returns
    Type Description
    EbicsOrderHIA

    If the transaction was sent, then the completed EbicsOrderHIA instance is returned. If the transaction could not be built, then null is returned.

    SendUserKey(IEbicsSecurityMedium, IEbicsTransport)

    Creates an EbicsOrderINI instance and uses it to sends the users signature key to the bank (INI).

    Declaration
    public EbicsOrderINI SendUserKey(IEbicsSecurityMedium aSecMedium, IEbicsTransport aTransport = null)
    Parameters
    Type Name Description
    IEbicsSecurityMedium aSecMedium

    Authenticated security medium of the user. Must not be null.

    IEbicsTransport aTransport

    An IEbicsTransport implementation for sending the HTTP request. If this is null, then the EbicsTransportFactory will be used to create an IEbicsTransport implementation.

    Returns
    Type Description
    EbicsOrderINI

    If the transaction was sent, then the completed EbicsOrderINI instance is returned. If the transaction could not be built, then null is returned.

    Sign(EbicsOrder, IEbicsSecurityMedium)

    Add a signature (EU) to the given order.

    Declaration
    public EbicsSecurityMediumErrorCode Sign(EbicsOrder aOrder, IEbicsSecurityMedium aSecurityMedium)
    Parameters
    Type Name Description
    EbicsOrder aOrder

    The order to be signed. This must be completely set up and include all order data.

    IEbicsSecurityMedium aSecurityMedium

    Authenticated security medium which will be used to create the electronic signature (EU) for the order. Must not be null. The referenced security medium must be in the Authenticated state.

    Returns
    Type Description
    EbicsSecurityMediumErrorCode

    If there was an error with the security media while producing the signature, then an appropriate error code is returned. If the signature was produced successfully, then Success is returned.

    Exceptions
    Type Condition
    System.ArgumentNullException

    One of the arguments was null.

    System.ArgumentException

    Either the given EbicsOrder was incomplete or the security medium was not in the Authenticated state.

    System.InvalidOperationException

    This EbicsContact was not completely initialized.

    ToJson(JsonObject)

    Converts an EbicsContact to its json representation. ToJson(JsonObject).

    Declaration
    public JsonObject ToJson(JsonObject jsonObject)
    Parameters
    Type Name Description
    JsonObject jsonObject
    Returns
    Type Description
    JsonObject

    ToString()

    Declaration
    public override string ToString()
    Returns
    Type Description
    System.String

    Usually returns the ContactName. If the contact name is null, then a string representation of the ContactGuid is returned instead.

    Overrides
    System.Object.ToString()

    Implements

    IEbicsJsonConverter

    Extension Methods

    EbicsExtensionMethods.AuthenticateSecurityMedium(EbicsContact, IWin32Window)
    EbicsExtensionMethods.Sign(EbicsContact, IWin32Window, EbicsOrder)
    EbicsExtensionMethods.Send(EbicsContact, IWin32Window, EbicsOrder)
    EbicsExtensionMethods.InternalizeKeyFile(EbicsContact, IWin32Window)
    EbicsContactExtensions.BuildXml(EbicsContact, XmlDocument)
    EbicsContactExtensions.BuildXmlDocument(EbicsContact)
    EbicsContactExtensions.ParseXml(EbicsContact, XmlElement)
    EbicsContactExtensions.Load(EbicsContact, Stream)
    EbicsContactExtensions.Load(EbicsContact, String)
    EbicsContactExtensions.Save(EbicsContact, Stream)
    EbicsContactExtensions.Save(EbicsContact, String)
    EbicsContactExtensions.FromBuffer(EbicsContact, EbicsDataBuffer)
    EbicsContactExtensions.ToBuffer(EbicsContact)
    EbicsJsonConverterExtensions.ToJson(IEbicsJsonConverter)
    In This Article
    Back to top Copyright 2009-2025 Subsembly GmbH