Class SwiftStatementLine

Namespace: Subsembly.Swift

Assembly: Subsembly.Sepa.dll

A SwiftStatementLine collects all the information from the SWIFT fields 61 and 86, which together make up a statement line.

public class SwiftStatementLine

Inheritance: object

SwiftStatementLine

Inherited Members: object.Equals(object, object)

object.GetType()

object.MemberwiseClone()

object.ReferenceEquals(object, object)

object.ToString()

Remarks

Statement lines appear in the SWIFT message types MT-940 (Customer Statement Message) and MT-942 (Interim Transaction Report) and many others.

Strictly speaking, a SWIFT Statement Line consists solely of the SWIFT field 61. In some message types the field 61 can be optionally accompanied by an immediately following field 86 (Information to Account Owner).

According to SWIFT, field 86 contains just plain text information. The german ZKA, however, defines a very special structured layout for this field. Using this structured layout, field 86 carries many more attributes about the statement line. This class supports that structured layout and can extract all information from it. If field 86 is not structured according to the ZKA, then the entire field 86 is simply taken as informational text.

Constructors

SwiftStatementLine()

Creates an all empty statement line.

public SwiftStatementLine()

Remarks

Use this constructor to create your own hand crafted statement line.

SwiftStatementLine(SwiftField)

Creates a statement line by initialising its properties from the given SWIFT field 61.

public SwiftStatementLine(SwiftField aField61)

Parameters

aField61 SwiftField: The SWIFT field 61 that provides the data for this SwiftStatementLine instance.

Remarks

If no entry date is provided in the given SWIFT field 61, then the EntryDate property will be initialised with a logical null value.

The currency of the transaction amount will be "XXX" unless a Funds Code subfield is present in the given field 61. If so, then currency will be "XX" followed by the extracted funds code letter.

Exceptions

ArgumentNullException: Parameter aField61 was null.
ArgumentOutOfRangeException: The given SWIFT field was not a non-generic field with tag 61 or its content was null.
SwiftException: The content of the SWIFT field is malformed. The SwiftExceptionCode will be MalformedFieldContent.

Fields

MaxBankRefLength

Max length of the BankRef property value.

public const int MaxBankRefLength = 16

Field Value

int

MaxCreditorIdLength

Max length of the SEPA field CreditorId property value.

public const int MaxCreditorIdLength = 35

Field Value

int

MaxEndToEndIdLength

Max length of the SEPA field EndToEndId property value.

public const int MaxEndToEndIdLength = 35

Field Value

int

MaxEntryTextLength

Max length of the EntryText property value.

public const int MaxEntryTextLength = 27

Field Value

int

MaxMandateIdLength

Max length of the SEPA field MandateId property value.

public const int MaxMandateIdLength = 35

Field Value

int

MaxOwnerRefLength

Max length of the OwnerRef property value.

public const int MaxOwnerRefLength = 35

Field Value

int

MaxPayeePayerAcctNoLength

Max length of the PayeePayerAcctNo property value.

public const int MaxPayeePayerAcctNoLength = 34

Field Value

int

MaxPayeePayerBankCodeLength

Max length of the PayeePayerBankCode property value.

public const int MaxPayeePayerBankCodeLength = 12

Field Value

int

MaxPayeePayerNameLength

Max length of the PayeePayerName1 and PayeePayerName2 property values.

public const int MaxPayeePayerNameLength = 27

Field Value

int

MaxPaymtPurposeLineLength

Max length of a single string of the string array stored in the PaymtPurpose property.

public const int MaxPaymtPurposeLineLength = 65

Field Value

int

MaxPaymtPurposeLines

Max number of strings in the string array stored in the PaymtPurpose property.

public const int MaxPaymtPurposeLines = 14

Field Value

int

MaxPrimaNotaNoLength

Max length of the PrimaNotaNo property value.

public const int MaxPrimaNotaNoLength = 10

Field Value

int

MaxSupplementaryDetailsLength

Max length of the SupplementaryDetails property value.

public const int MaxSupplementaryDetailsLength = 34

Field Value

int

Properties

Amount

The monetary amount and the currency of this transaction.

public SwiftAmt Amount { get; }

Property Value

SwiftAmt

The amount value corresponds with subfield 5 (Amount) of SWIFT field :61: (Statement Line). The Amount is a required subfield and therefore is never null after parsing.

If subfield 4 (Funds Code) of SWIFT field :61: (Statement Line) is present, then the currency will be "XX" followed by the extracted funds code letter. Otherwise the currency will be "XXX".

BankRef

The optional Account Servicing Institution’s Reference (Bankreferenz) of this transaction.

public string BankRef { get; set; }

Property Value

string

The BankRef property corresponds with subfield 8 (Account Servicing Institution’s Reference) of SWIFT field :61: (Statement Line). The value stored in this property excludes the two leading slashes (//) that separate this subfield from the preceeding subfield.

The value is optional and almost always will be null in order to indicate that no bank reference is available. Otherwise it may consist of up to 16 characters from the All character set.

Exceptions

ArgumentException: An attempt was made to set a string value that did not match the requirements for this field.

ChargesAmount

The total sum of all charges of this statement line.

public decimal ChargesAmount { get; set; }

Property Value

decimal

See Also: SupplementaryDetails

ChargesAmountCurrency

The currency code of all charges of this statement line.

public string ChargesAmountCurrency { get; set; }

Property Value

string

See Also: SupplementaryDetails

CreditorId

The optional SEPA Creditor-Identification.

public string CreditorId { get; set; }

Property Value

string

If SWIFT field :86: (Information to Account Owner) is structured according to ZKA rules and the transaction is a SEPA transaction, then the CRED or DEBT corresponds to the CreditorId property, depending on whether this is a debit or not. Otherwise the CreditorId will be null.

The ZKA SEPA specification permits any text with up to 35 characters. Thus, this is also what is enforced by this property.

Exceptions

ArgumentException: An attempt was made to set a string value that was longer than 35 characters.

Currency

The currency code of this transaction.

public string Currency { get; set; }

Property Value

string: The currency code is actually not stored in a SWIFT Statement Line, only the Funds Code is. Therefore, if subfield 4 (Funds Code) of SWIFT field :61: (Statement Line) is present, then the currency will be "XX" followed by the extracted funds code letter. Otherwise the currency will be null.

DebitCreditMark

The Debit/Credit Mark (Soll/Haben-Kennung) of this transaction.

public string DebitCreditMark { get; set; }

Property Value

string

The DebitCreditMark property corresponds with subfield 3 (Debit/Credit Mark) of SWIFT field :61: (Statement Line). The Debit/Credit Mark is a required subfield and therefore is never null after parsing.

SWIFT defines the following possible values for the Debit/Credit Mark subfield (case is significant):

C	Credit
D	Debit
RC	Reversal of credit (debit entry)
RD	Reversal of debit (credit entry)
EC	Expected credit (only allowed in MT-942 Interim Transaction Report)
ED	Expected debit (only allowed in MT-942 Interim Transaction Report)

Any of these six values are accepted, regardless of the actual SWIFT message that contains this statement line.

Exceptions

ArgumentOutOfRangeException: An attempt was made to set a string value that was none of the six defined acceptable values for this field.

DecValue

The actual decimal value of this transaction with sign.

public decimal DecValue { get; set; }

Property Value

decimal

If this is a debit transaction, then this property has a negative decimal value. Otherwise it has a positive decimal value.

When setting this property, the DebitCreditMark is set to "C" for positive values including zero and "D" for negative values.

EndToEndId

The optional SEPA End-to-End-Identification.

public string EndToEndId { get; set; }

Property Value

string

If SWIFT field :86: (Information to Account Owner) is structured according to ZKA rules and the transaction is a SEPA transaction, then the EREF corresponds to the EndToEndId property. Otherwise the EndToEndId will be null.

The ZKA SEPA specification permits any text with up to 35 characters. Thus, this is also what is enforced by this property.

Exceptions

ArgumentException: An attempt was made to set a string value that was longer than 35 characters.

EntryDate

The Entry Date (Buchungsdatum) of this transaction.

public SwiftDate EntryDate { get; set; }

Property Value

SwiftDate

The EntryDate property corresponds with subfield 2 (Entry Date) of SWIFT field :61: (Statement Line). The year component of the date (which does not exist in the SWIFT subfield) is derived from the value date. The year of the entry date is chosen such that the resulting entry date is as close as possible to the value date. For example: If the Value Date subfield is 031231 and the Entry Date subfield is 0101, then the year 2004 and not 2003 is used for the entry date, because 2004-01-01 is closer to 2003-12-31 than 2003-01-01.

If no Entry Date subfield is present in SWIFT field :61:, then it is assumed to be equal to the ValueDate. Hence, if no Entry Date subfield is present, this property returns the ValueDate instead.

The EntryDate may contain any virtual date that can be represented by the SwiftDate type!

EntryText

The optional entry text (Buchungstext) of this transaction.

public string EntryText { get; set; }

Property Value

string

If SWIFT field :86: (Information to Account Owner) is structured according to ZKA rules, then the ZKA subfield 00 corresponds to the EntryText property. Otherwise the EntryText will be null.

The ZKA subfield permits any text with up to 27 characters. Thus, this is also what is enforced by this property.

Exceptions

ArgumentException: An attempt was made to set a string value that was longer than 27 characters.

FundsCode

The funds code (3rd letter of currency code) of this transaction.

public char FundsCode { get; set; }

Property Value

char: The funds code corresponds with subfield 4 (Funds Code) of SWIFT field :61: (Statement Line). The funds code is optional and will be a nul character if not present.

Exceptions

ArgumentOutOfRangeException: An attempt was made to set a non alpha and non-nul character.

HasEntryDate

Indicates whether this EntryDate was explicitly provided, or whether it is just the ValueDate default value.

public bool HasEntryDate { get; }

Property Value

bool

IsDebit

Indicates whether this is a debit entry.

public bool IsDebit { get; }

Property Value

bool: Is true whenever the DebitCreditMark is either "D", "RC", or "ED".

IsReversal

Indicates whether this is a reversal entry.

public bool IsReversal { get; }

Property Value

bool: Is true whenever the DebitCreditMark is either "RD" or "RC".

MandateId

The optional SEPA Mandate-Identification.

public string MandateId { get; set; }

Property Value

string

If SWIFT field :86: (Information to Account Owner) is structured according to ZKA rules and the transaction is a SEPA transaction, then the MREF corresponds to the MandateId property. Otherwise the MandateId will be null.

The ZKA SEPA specification permits any text with up to 35 characters. Thus, this is also what is enforced by this property.

Exceptions

ArgumentException: An attempt was made to set a string value that was longer than 35 characters.

OriginalAmount

The originally instructed amount of this statement line.

public decimal OriginalAmount { get; set; }

Property Value

decimal

See Also: SupplementaryDetails

OriginalAmountCurrency

The currency code of the originally instructed amount of this statement line.

public string OriginalAmountCurrency { get; set; }

Property Value

string

See Also: SupplementaryDetails

OwnerRef

The Reference for the Account Owner (Kundenreferenz) of this transaction.

public string OwnerRef { get; set; }

Property Value

string

The OwnerRef property corresponds with subfield 7 (Reference for the Account Owner) of SWIFT field :61: (Statement Line). The Reference for the Account Owner is a required subfield and therefore is never null after parsing. It may consist of up to 16 characters from the All character set.

The value NONREF may (and almost always will) appear in order to indicate that no owner reference is available.

SEPA: If the SWIFT subfield contains KREF+ then the actual value is taken from the SEPA structured SWIFT field :86: KREF+ entry.

Exceptions

ArgumentException: An attempt was made to set a string value that did not match the requirements for this field.

PayeePayerAcctNo

The account number of the other payee or payer (not the account owner).

public string PayeePayerAcctNo { get; set; }

Property Value

string

If SWIFT field :86: (Information to Account Owner) is structured according to ZKA rules, then the ZKA subfield 31 corresponds to the PayeePayerAcctNo property. Otherwise the PayeePayerAcctNo will be null.

The ZKA subfield permits alphanumeric account numbers with a length of up to 34 digits. Thus, this is also what is enforced by this property.

SEPA: With SEPA payments this field will hold the IBAN of the payee or payer.

Exceptions

ArgumentException: An attempt was made to set a string value that was longer than 34 characters or did contain special characters.

PayeePayerBankCode

The bank code number of the other payee or payer account (not the owner account).

public string PayeePayerBankCode { get; set; }

Property Value

string

If SWIFT field :86: (Information to Account Owner) is structured according to ZKA rules, then the ZKA subfield 30 corresponds to the PayeePayerBankCode property. Otherwise the PayeePayerBankCode will be null.

The ZKA subfield permits alphanumeric bank codes with a length of up to 12 digits. Thus, this is also what is enforced by this property.

SEPA: With SEPA payments this field will hold the BIC of the payee or payer.

Exceptions

ArgumentException: An attempt was made to set a string value that was longer than 12 characters or did contain special characters.

PayeePayerName

The combined, complete payee payer name.

public string PayeePayerName { get; set; }

Property Value

string

Remarks

If SWIFT field :86: (Information to Account Owner) is structured according to ZKA rules, then this property is the concatenation of the ZKA subfields 32 and 33.

PayeePayerName1

The name of the other payee or payer (not the account owner).

public string PayeePayerName1 { get; }

Property Value

string: If SWIFT field :86: (Information to Account Owner) is structured according to ZKA rules, then the ZKA subfield 32 corresponds to the PayeePayerName1 property. Otherwise the PayeePayerName1 will be null.

PayeePayerName2

Optional second line of payee/payer name.

public string PayeePayerName2 { get; }

Property Value

string: If SWIFT field :86: (Information to Account Owner) is structured according to ZKA rules, then the ZKA subfield 33 corresponds to the PayeePayerName2 property. Otherwise the PayeePayerName2 will be null.

PaymtPurpose

The raw payment purpose extracted from field 86.

public string[] PaymtPurpose { get; set; }

Property Value

string[]: When parsing field 86 specially tagged SEPA fields are removed from the data. The PaymtPurpose property instead contains all payment purpose lines without any SEPA tag processing, i.e. all SEPA tags and values are still contained.

PrimaNotaNo

The optional prima nota number (Primanota-Nummer) of this transaction.

public string PrimaNotaNo { get; set; }

Property Value

string

If SWIFT field :86: (Information to Account Owner) is structured according to ZKA rules, then the ZKA subfield 10 corresponds to the PrimaNotaNo property. Otherwise the PrimaNotaNo will be null.

The ZKA subfield permits any text with up to 10 characters. Thus, this is also what is enforced by this property.

Exceptions

ArgumentException: An attempt was made to set a string value that was longer than 10 characters or did contain invalid characters.

PurposeCode

SEPA purpose code from SEPA tag PURP.

public string PurposeCode { get; set; }

Property Value

string

SepaPaymtPurpose

Provides the processed SEPA payment purpose.

public string SepaPaymtPurpose { get; }

Property Value

string

Remarks

Any SEPA fields that are not returned through any other property of this class are appended at the end of this string, separated by a Environment.NewLine sequence. The actual SEPA purpose is always in the first line of the returned string, even if it is empty.

SupplementaryDetails

The optional Supplementary Details (Weitere Informationen) of this transaction.

public string SupplementaryDetails { get; set; }

Property Value

string

The SupplementaryDetails property corresponds with subfield 9 (Supplementary Details) of SWIFT field :61: (Statement Line). The value stored in this property excludes the leading CRLF sequence that separate this subfield from the preceeding subfield.

The value is optional and almost always will be null in order to indicate that no supplementary details are available. Otherwise it may consist of up to 34 characters from the All character set.

Remarks

The SupplementaryDetails may contain the special text sequences /OCMT/3a..15d/ and/or /CHGS/3a..15d/. When parsing the SWIFT field :61:, then the values from these text sequences are copied into the properties OriginalAmount, OriginalAmountCurrency, ChargesAmount, and ChargesAmountCurrency. However, the value of this SupplementaryDetails property will still contain these sequences.

When generating the SWIFT field :61:, and this property is non-empty, then only the content of this property will be written. The property values for the OriginalAmount and the ChargesAmount are ignored. Only if this property is null or an empty string, then a supplementary details sub-field will be generated from the value of the properties OriginalAmount, OriginalAmountCurrency, ChargesAmount, and ChargesAmountCurrency.

Exceptions

ArgumentException: An attempt was made to set a string value that did not match the requirements for this field.

TextKeyExt

Three digit text key extension of this transaction.

public string TextKeyExt { get; set; }

Property Value

string

If SWIFT field :86: (Information to Account Owner) is structured according to ZKA rules, then the ZKA subfield 34 corresponds to the TextKeyExt. Otherwise the TextKeyExt will be null.

The text key extension is defined by the DTAUS specification. It consists of three digits. The text key extension is optional and may be null. Logically a null value is equivalent to three zeroes (000). The text key extension cannot be set to anything but null or a string with exactly three digits.

SEPA: With SEPA payments this field will hold a SEPA-Code.

Exceptions

ArgumentException: An attempt was made to set a string value that did not consist of exactly three digits.

TranTypeIdCode

The Transaction Type Identification Code (Buchungsschlüssel) of this transaction.

public string TranTypeIdCode { get; set; }

Property Value

string

The TranTypeIdCode property corresponds with subfield 6 (Transaction Type Identification Code) of SWIFT field :61: (Statement Line). The stored property value contains the complete four character code from this subfield, including the obligatory leading 'N' character. The Transaction Type Identification Code is a required subfield and therefore is never null after parsing.

Similar information, but derived from other SWIFT fields, is available through the ZkaTranCode, and EntryText properties.

The following table shows some of the more common transaction type ID codes, that have be seen to be actually used. For a complete list of codes, please refer to the SWIFT specification.

NMSC	Miscellaneous (Verschiedenes). Appears very often, as the banks usually do not fully support sending appropriate transaction type ID codes.
NTRF	Transfer (Übertrag). Has been seen to be used for simple single remittance transactions (Überweisung).
NSTO	Standing Order (Dauerauftrag).

Many other undefined codes have been seen in actual MT-940 samples.

Exceptions

ArgumentException: An attempt was made to set a string value that did not match the requirements for this field.

UltimateOriginatorName

The ultimate originator of this transaction (ABWA+)

public string UltimateOriginatorName { get; set; }

Property Value

string

Remarks

This may be the UltimateCreditor or the UltimateDebtor from the PaymentInformation of the original SEPA payment.

UltimatePayeePayerName

The ultimate payee or payer of this transaction (ABWE+)

public string UltimatePayeePayerName { get; set; }

Property Value

string

Remarks

This may be the UltimateCreditor or the UltimateDebtor from TransactionInformation of the original SEPA payment.

Value

The absolute decimal value of this transaction without sign.

public decimal Value { get; set; }

Property Value

decimal: Strictly positive or zero value of this transaction.

Exceptions

ArgumentOutOfRangeException: An attempt was made to set a negative value.

ValueDate

The Value Date (Wertstellungstag) of this transaction.

public SwiftDate ValueDate { get; set; }

Property Value

SwiftDate: The ValueDate property corresponds with subfield 1 (Value Date) of SWIFT field :61: (Statement Line). The Value Date is a required subfield and therefore is never null after parsing. The ValueDate may contain any virtual date that can be represented by the SwiftDate type!

ZkaTranCode

The ZKA defined numeric transaction code (Geschäftsvorfall-Code) of this transaction.

public string ZkaTranCode { get; set; }

Property Value

string

Whenever SWIFT field :86: begins with three digits, they are assumed to contain the ZKA transaction code and thus will correspond with the ZkaTranCode property. If the SWIFT field :86: does not begin with three digits, then this will be null.

If the first digit is zero, the other two digits actually correspond with the text key of a remittance.

Exceptions

ArgumentException: An attempt was made to set a string value that did not consist of exactly three digits.

Methods

AugmentInfoToAcctOwner(SwiftField)

Augment this statement line with the information from SWIFT field 86 (Information to Account Owner).

public void AugmentInfoToAcctOwner(SwiftField aField86)

Parameters

aField86 SwiftField: Instance of SwiftField that carries a SWIFT field 86 with information to be added to this statement line. If this field is structured according to the ZKA, then all its subfields are properly extracted.

Exceptions

ArgumentNullException: Parameter aField86 was null.
ArgumentOutOfRangeException: The given SWIFT field was not a non-generic field with tag 86 or its content was null.
SwiftException: The content of the SWIFT field is malformed. The SwiftExceptionCode will be MalformedFieldContent.

BuildField61()

Builds a SWIFT field 61 (Statement Line).

public SwiftField BuildField61()

Returns

SwiftField: New instance of SwiftField that contains the data from this SwiftStatementLine instance.

Remarks

At least the following properties must be set before a valid SWIFT field 61 can be generated: ValueDate, Value, DebitCreditMark, and TranTypeIdCode. The EntryDate is optional, but should always be provided for MT-940 entries.

Exceptions

InvalidOperationException: Not all required subfields for a valid field 61 have been set.

BuildField86()

Attempts to build a SWIFT field 86 (Information to Account Owner).

public SwiftField BuildField86()

Returns

SwiftField

New instance of SwiftField that contains the data from this SwiftStatementLine instance.

If the resulting field 86 would be completely empty, because no suitable properties of this SwiftStatementLine have been set, then null is returned.

Remarks

The presence and value of the ZkaTranCode determines whether a structured or unstructured field 86 will be generated. Only if ZkaTranCode is not null and does not start with the digit '9', then a structured field 86 is generated. Otherwise an unstructured field 86 is generated.

TODO: The SEPA properties EndToEndId, MandateId, and CreditorId are currently ignored. This method will never build a SEPA transaction with a structured field 86.

Equals(object)

Compares for equality.

public override bool Equals(object obj)

Parameters

obj object: Another SwiftStatementLine instance to compare this one to.

Returns

bool: Returns true if both SwiftStatementLine instances are actually duplicates.

GetHashCode()

public override int GetHashCode()

Returns

int

Remarks

TODO: The hash code currently only includes the EntryDate and the Amount. Although it should include all fields in order to match the implementation of Equals(object).