swift_mt_message/fields/

field25.rs

use serde::{Deserialize, Serialize};
use swift_mt_message_macros::SwiftField;

///   **Field 25: Account Identification / Authorisation**
///
/// ## Purpose
/// Provides account identification or authorization information for payment instructions.
/// This field serves dual purposes: identifying accounts for payment processing and
/// providing security authorization codes between the ordering customer and the
/// account servicing financial institution.
///
/// ## Format
/// - **Swift Format**: `35x` (NoOption), `/34x` (Option A), `35x` + `4!a2!a2!c[3!c]` (Option P)
/// - **Description**: Account identifier or authorization code with optional BIC
/// - **Character Set**: Alphanumeric characters following Swift standards
///
/// ## Presence
/// - **Status**: Optional in most contexts, mandatory when account identification required
/// - **Swift Error Codes**: T61 (invalid account format), C05 (invalid BIC)
/// - **Usage Context**: Account services and authorization verification
///
/// ## Usage Rules
/// - **Account Identification**: Specifies account to be debited or credited
/// - **Authorization Security**: Contains security provisions between customer and institution
/// - **Format Selection**: Choose appropriate option based on account identification needs
/// - **BIC Validation**: When BIC provided, must be valid financial institution identifier
///
/// ## Network Validation Rules
/// - **Account Format**: Must conform to institutional account numbering standards
/// - **BIC Validation**: BIC must be registered financial institution code
/// - **Character Validation**: Only permitted characters in Swift character set
/// - **Length Compliance**: Must not exceed maximum field length restrictions
///
/// ## Field Options and Usage
///
/// ### NoOption (35x) - Authorisation
/// - **Usage**: Security authorization codes and digital signatures
/// - **Length**: Up to 35 characters
/// - **Purpose**: Authentication between customer and account servicing institution
/// - **Security Context**: Electronic device codes, digital signatures, or agreed tokens
///
/// ### Option A (/34x) - Account Identifier
/// - **Usage**: Simple account identification with slash prefix
/// - **Length**: Up to 34 characters (excluding slash)
/// - **Purpose**: Basic account identification for payment processing
/// - **Format**: Slash followed by account identifier
///
/// ### Option P (35x + BIC) - Account with Institution
/// - **Usage**: Account identification with associated financial institution
/// - **Components**: Account identifier + Institution BIC code
/// - **Purpose**: Complete account specification including servicing institution
/// - **BIC Format**: Standard 8 or 11 character BIC code
///
/// ## Business Context
/// - **Payment Processing**: Essential for routing payments to correct accounts
/// - **Security Framework**: Enables secure authorization between parties
/// - **Account Services**: Facilitates account-based financial services
/// - **Cross-Border Payments**: Provides institution identification for international transfers
///
/// ## Authorization Security
/// - **Digital Signatures**: Electronic signature verification codes
/// - **Token Authentication**: Security tokens generated by electronic devices
/// - **Bilateral Agreements**: Institution-specific authorization mechanisms
/// - **Fraud Prevention**: Additional security layer for payment authorization
///
/// ## Examples
/// ```logic
/// :25:AUTH123456789         // Authorization code (NoOption)
/// :25A:/GB82WEST12345698765432  // IBAN account identifier
/// :25A:/1234567890          // Simple account number
/// :25P:CHF1234567890        // Account with BIC
///     UBSWCHZH80XX          // Swiss bank BIC
/// ```
///
/// ## Regional Considerations
/// - **European Payments**: IBAN format compliance for SEPA transactions
/// - **US Payments**: Federal routing number integration
/// - **Asian Markets**: Local account numbering standards
/// - **Cross-Border**: International account identification requirements
///
/// ## Account Format Standards
/// - **IBAN**: International Bank Account Number for European markets
/// - **BBAN**: Basic Bank Account Number for domestic transactions
/// - **Local Formats**: Region-specific account numbering schemes
/// - **Institution Standards**: Bank-specific account identification rules
///
/// ## Error Prevention
/// - **Account Validation**: Verify account exists and is accessible
/// - **BIC Verification**: Confirm BIC is valid and active
/// - **Format Checking**: Ensure account format matches regional standards
/// - **Authorization Validation**: Verify security codes are current and valid
///
/// ## Related Fields
/// - **Field 50**: Ordering Customer (account holder identification)
/// - **Field 57**: Account With Institution (receiving account details)
/// - **Field 59**: Beneficiary Customer (final account recipient)
/// - **Field 52**: Ordering Institution (account servicing institution)
///
/// ## Security Considerations
/// - **Token Management**: Secure generation and validation of authorization tokens
/// - **Code Expiry**: Time-limited validity of authorization codes
/// - **Bilateral Security**: Institution-specific security arrangements
/// - **Audit Trail**: Comprehensive logging of authorization attempts
///
/// ## STP Compliance
/// - **Format Standardization**: Consistent account format for automated processing
/// - **Validation Enhancement**: Enhanced security validation for STP transactions
/// - **Exception Handling**: Automated handling of authorization failures
/// - **Quality Control**: Real-time validation of account and authorization data
///
/// ## Compliance and Audit
/// - **Regulatory Requirements**: Meeting account identification regulations
/// - **Security Documentation**: Maintaining records of authorization methods
/// - **Access Control**: Ensuring proper account access authorization
/// - **Investigation Support**: Authorization tracking for compliance investigations
///
/// ## See Also
/// - Swift FIN User Handbook: Account Identification Standards
/// - Authorization Guidelines: Security Code Requirements
/// - IBAN Standards: International Account Number Specifications
/// - BIC Directory: Institution Identifier Validation
///
///   **Field 25 NoOption: Authorisation**
///
/// Security authorization code or digital signature between ordering customer
/// and account servicing financial institution.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, SwiftField)]
pub struct Field25NoOption {
    /// Authorization code or digital signature
    ///
    /// Format: 35x - Security token, electronic signature, or agreed authorization code
    /// Used for additional security verification between customer and institution
    #[component("35x")]
    pub authorisation: String,
}

///   **Field 25A: Account Identifier**
///
/// Simple account identification with slash prefix for basic account specification.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, SwiftField)]
pub struct Field25A {
    /// Account identifier with slash prefix
    ///
    /// Format: /34x - Account number preceded by slash
    /// Supports IBAN, BBAN, or institution-specific account formats
    #[component("/34x")]
    pub account: String,
}

///   **Field 25P: Account with Institution**
///
/// Account identification with associated financial institution BIC code
/// for complete account specification.
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, SwiftField)]
pub struct Field25P {
    /// Account identifier
    ///
    /// Format: 35x - Account number or identifier
    /// Combined with BIC for complete account specification
    #[component("35x")]
    pub account: String,

    /// Bank Identifier Code of account servicing institution
    ///
    /// Format: 4!a2!a2!c\[3!c\] - 8 or 11 character BIC code
    /// Must be valid registered financial institution identifier
    #[component("4!a2!a2!c[3!c]")]
    pub bic: String,
}

///   **Field 25 Account Identification Enum**
///
/// Enumeration of account identification options providing flexibility
/// for different account specification needs.
#[derive(Debug, Clone, PartialEq, Serialize, Deserialize, SwiftField)]
pub enum Field25AccountIdentification {
    /// Authorization code without account specification
    NoOption(Field25NoOption),
    /// Account with institution BIC code
    P(Field25P),
}