Skip to content

Payment addenda

clsPaymentAddenda records the NACHA addenda record(s) attached to a payment. This operation is always initiated by Payment detail, events, and allocation — it has no independent entry point of its own — and is retrieve-only from a collection perspective: clsPaymentAddendaCollection provides no "new collection" constructor, since addenda rows are always created individually against a specific PaymentDetailSeqNum.

Field Value
Operation ID OP-EFT-07
Trigger clsPaymentDetail.CreateIATAddenda() (IAT payments) or CreateStandardAddenda() (non-IAT payments with addendum text)
Inputs Parent PaymentDetailSeqNum, addenda sequence number, addenda text, (for IAT) country/originator/receiver details
Outputs One or more persisted PAYMENT_ADDENDA rows with encrypted addenda text
Primary components clsPaymentAddenda, clsPaymentAddendaCollection
Entry point Business\SAIF.Business.Payment.EFT\clsPaymentAddenda.vb (invoked from clsPaymentDetail)

Steps

  1. Determine addenda type. Payment detail, events, and allocation decides whether the payment is IAT (International ACH Transaction) or domestic/standard, and calls the corresponding creation method.
  2. IAT addenda: create 7 records. CreateIATAddenda() fetches the next sequence value for each record (SQL-005, DUAL) and inserts 7 PAYMENT_ADDENDA rows with type codes 10 through 16, each representing a distinct segment of the IAT addenda specification (e.g., foreign correspondent bank information, originator/receiver name and address) (SQL-015, PAYMENT_ADDENDA).
  3. Country information is recorded using ISO country codes rather than free-text country names, reflecting the 2014 NACHA IAT format change that standardized this field.
  4. Standard addenda: create 1 record. CreateStandardAddenda() fetches a sequence value (SQL-005) and inserts a single PAYMENT_ADDENDA row of type code 05 (standard entry-class addenda) containing the free-text addendum message supplied by the caller (SQL-015, PAYMENT_ADDENDA).
  5. Encrypt addenda text. In both paths, the AddendaText value is encrypted via SAIF.Security.clsSecureEncrypt.EncryptString before being persisted, matching the encryption pattern used for bank routing/account numbers in Bank account management.
  6. Retrieve addenda for a payment. A single addenda record can be retrieved by its own sequence number (SQL-055, PAYMENT_ADDENDA), while clsPaymentAddendaCollection retrieves all addenda rows for a given PaymentDetailSeqNum, ordered by addenda sequence number, for use in generating the final NACHA output file (SQL-056).
  7. Update an addenda record. If addenda content must be corrected before the output file is generated, UPDATE PAYMENT_ADDENDA is available keyed on the addenda sequence number (SQL-083).
  8. Delete an addenda record. Addenda rows can also be physically deleted if a payment is cancelled before its output file is generated (SQL-094).

Process flow

flowchart TD
    Start([PaymentDetail lifecycle<br>reaches addenda trigger]) --> Type{IAT payment?}
    Type -->|Yes| IAT[CreateIATAddenda:<br>insert 7 records, type codes 10-16]
    Type -->|No, has addendum text| Standard[CreateStandardAddenda:<br>insert 1 record, type code 05]
    Type -->|No addendum text| Skip([No addenda created])
    IAT --> Encrypt[Encrypt AddendaText]
    Standard --> Encrypt
    Encrypt --> Persist[INSERT PAYMENT_ADDENDA]
    Persist --> BatchTime[Retrieved later by<br>PaymentDetailSeqNum for output]
    BatchTime --> Done([Assembled into NACHA output file])

Failure and edge-case behavior

  • Addenda creation is entirely driven by clsPaymentDetail; there is no standalone "create a new addenda collection" entry point, so any bug in the calling payment-detail logic that skips the addenda-creation call will silently produce a payment with no addenda even if one was expected.*
  • Country codes (not names) are required for IAT addenda per the 2014 NACHA format change; supplying a country name instead of a code would produce a malformed NACHA file that this library does not itself validate against the NACHA specification.*
  • Addenda text is encrypted at rest; any downstream reporting or file-generation process must decrypt it using the same SAIF.Security.clsSecureEncrypt mechanism used to write it.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts.

Sources

  • Business\SAIF.Business.Payment.EFT\clsPaymentAddenda.vb
  • Business\SAIF.Business.Payment.EFT\clsPaymentAddendaCollection.vb