swift_mt_message/fields/
field33.rs

1use serde::{Deserialize, Serialize};
2use swift_mt_message_macros::SwiftField;
3
4///   **Field 33B: Currency / Instructed Amount**
5///
6/// ## Purpose
7/// Specifies the currency code and original instructed amount when the settlement amount
8/// differs from the instructed amount due to currency conversion, exchange rate application,
9/// or charge deductions. This field preserves the original instruction details for audit,
10/// reconciliation, and regulatory reporting purposes.
11///
12/// ## Format
13/// - **Swift Format**: `3!a15d`
14/// - **Currency Component**: `3!a` - ISO 4217 currency code
15/// - **Amount Component**: `15d` - Decimal amount with comma separator
16/// - **Precision**: Follows currency-specific decimal place rules
17///
18/// ## Presence
19/// - **Status**: Conditional - Required when currency conversion performed
20/// - **Swift Error Codes**: T52 (invalid currency), T40/T43 (invalid amount), T51 (format error)
21/// - **Usage Context**: Cross-currency transactions and charge applications
22///
23/// ## Usage Rules
24/// - **Currency Conversion**: Mandatory when different from settlement currency
25/// - **Amount Preservation**: Original instructed amount must be maintained
26/// - **Forwarding**: Must be forwarded unchanged through transaction chain
27/// - **Reconciliation**: Enables matching with original customer instructions
28///
29/// ## Network Validation Rules
30/// - **Currency Validation**: Must be valid ISO 4217 currency code
31/// - **Amount Format**: Decimal comma mandatory, proper precision required
32/// - **Positive Amount**: Amount must be greater than zero
33/// - **Precision Rules**: Must follow currency-specific decimal places
34/// - **Format Compliance**: Exact adherence to Swift format specifications
35///
36/// ## Business Context
37/// - **Cross-Currency Payments**: Preserves original currency and amount
38/// - **Exchange Rate Application**: Shows amount before rate conversion
39/// - **Charge Processing**: Amount before charge deductions
40/// - **Multi-Currency Processing**: Original instruction currency preservation
41///
42/// ## Currency Conversion Logic
43/// ```logic
44/// Field 33B (Instructed Amount) × Field 36 (Exchange Rate) = Converted Amount
45/// Converted Amount ± Charges = Field 32A (Settlement Amount)
46/// ```
47///
48/// ## Examples
49/// ```logic
50/// :33B:USD1250,00     // Original instruction: USD 1,250.00
51/// :33B:EUR950,50      // Original instruction: EUR 950.50
52/// :33B:GBP750,25      // Original instruction: GBP 750.25
53/// :33B:JPY125000      // Original instruction: JPY 125,000 (no decimals)
54/// ```
55///
56/// ## Currency Precision by Type
57/// - **Most Currencies**: 2 decimal places (USD, EUR, GBP, CHF, etc.)
58/// - **Japanese Yen**: 0 decimal places (JPY)
59/// - **Bahraini Dinar**: 3 decimal places (BHD)
60/// - **Special Cases**: Currency-specific precision requirements
61///
62/// ## Transaction Flow Integration
63/// - **Customer Instruction**: Original amount specified by customer
64/// - **Bank Processing**: Conversion and charge application
65/// - **Settlement**: Final amount after all adjustments
66/// - **Reporting**: Original vs. settled amount reconciliation
67///
68/// ## Regional Considerations
69/// - **European Payments**: EUR conversion requirements for SEPA
70/// - **US Payments**: USD conversion for domestic processing
71/// - **Asian Markets**: Local currency conversion needs
72/// - **Cross-Border**: Multiple currency conversion scenarios
73///
74/// ## Error Prevention
75/// - **Currency Validation**: Verify currency code is valid and supported
76/// - **Amount Verification**: Confirm amount format and precision
77/// - **Conversion Logic**: Ensure proper relationship with exchange rate
78/// - **Forwarding Rules**: Maintain amount integrity through transaction chain
79///
80/// ## Related Fields
81/// - **Field 32A**: Value Date, Currency, Settlement Amount (final amount)
82/// - **Field 36**: Exchange Rate (conversion factor)
83/// - **Field 71F**: Sender's Charges (deducted amounts)
84/// - **Field 71G**: Receiver's Charges (additional charges)
85///
86/// ## Reconciliation Support
87/// - **Amount Matching**: Links original instruction to settlement
88/// - **Audit Trail**: Maintains complete transaction history
89/// - **Variance Analysis**: Explains differences between instructed and settled
90/// - **Compliance Reporting**: Supports regulatory reporting requirements
91///
92/// ## STP Processing
93/// - **Format Standardization**: Consistent currency and amount formatting
94/// - **Automated Conversion**: System-driven currency conversion processing
95/// - **Validation Enhancement**: Real-time format and precision validation
96/// - **Exception Handling**: Automated detection of conversion discrepancies
97///
98/// ## Compliance Framework
99/// - **Regulatory Reporting**: Original instruction amount for compliance
100/// - **AML Monitoring**: Enhanced monitoring of currency conversion patterns
101/// - **Audit Documentation**: Complete record of instructed vs. settled amounts
102/// - **Investigation Support**: Original instruction details for compliance reviews
103///
104/// ## Multi-Currency Scenarios
105/// - **Trade Finance**: Original contract currency preservation
106/// - **Treasury Operations**: Multi-currency deal processing
107/// - **Corporate Payments**: Group company cross-currency transfers
108/// - **Investment Services**: Portfolio currency conversion tracking
109///
110/// ## See Also
111/// - Swift FIN User Handbook: Currency and Amount Specifications
112/// - ISO 4217: Currency Code Standards
113/// - Exchange Rate Guidelines: Conversion Calculation Rules
114/// - Reconciliation Standards: Original vs. Settlement Amount Matching
115///
116///   **Field 33B: Currency/Instructed Amount Structure**
117///
118/// Contains the original instructed currency and amount before conversion
119/// and charge applications.
120#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, SwiftField)]
121pub struct Field33B {
122    /// Currency code of original instruction
123    ///
124    /// Format: 3!a - ISO 4217 currency code (USD, EUR, GBP, etc.)
125    /// Must be valid and supported currency for cross-border transactions
126    #[component("3!a")]
127    pub currency: String,
128
129    /// Original instructed amount
130    ///
131    /// Format: 15d - Decimal amount with comma separator
132    /// Precision must match currency requirements (JPY=0, BHD=3, most=2)
133    #[component("15d")]
134    pub amount: f64,
135}
swift_mt_message/fields/field33.rs

swift_mt_message/fields/
field33.rs
