--- ## **🔻 Upstream Response Flow** When the upstream network processes a transaction and responds back to the device: ### **📥 Upstream Network Response Processing** ```mermaid --- id: upstream-response-flow --- flowchart TD START([Upstream Network Processes Transaction]) --> SEND_RESPONSE[📤 Network Sends Response] SEND_RESPONSE --> RECEIVE_BYTES[🔌 TCP Connection Receives Bytes] RECEIVE_BYTES --> ASYNC_CHECK{Async Correlation?} %% Async Path (High Volume Networks) ASYNC_CHECK -->|Yes - Visa/MC| ASYNC_CORRELATOR[⚡ AsyncCorrelator.handle_upstream_response] ASYNC_CORRELATOR --> UNPACK_ASYNC[📦 Unpack Response with Network Packager] UNPACK_ASYNC --> CORRELATION_LOOKUP[🔍 ETS Correlation Lookup by STAN/RRN] CORRELATION_LOOKUP --> FOUND_REQUEST{Request Found?} FOUND_REQUEST -->|Yes| CANCEL_TIMER[⏰ Cancel Timeout Timer] CANCEL_TIMER --> INVOKE_CALLBACK[📞 Invoke Response Callback Function] INVOKE_CALLBACK --> RESPONSE_PROCESSING[🔄 Response Processing Pipeline] FOUND_REQUEST -->|No| LOG_ORPHAN[⚠️ Log Orphaned Response] %% Sync Path (Low Volume Networks) ASYNC_CHECK -->|No - AmEx/Discover| SYNC_RESPONSE[🔄 UpstreamRouter.unpack_upstream_response] SYNC_RESPONSE --> UNPACK_SYNC[📦 Unpack Response with Upstream Packager] UNPACK_SYNC --> RESPONSE_PROCESSING %% Response Processing Pipeline RESPONSE_PROCESSING --> TRANSFORM_RESPONSE[🔄 Transform Response for Channel] TRANSFORM_RESPONSE --> VALIDATE_OUTGOING[✅ Validate Outgoing Message] VALIDATE_OUTGOING --> CHANNEL_TRANSFORM[🔧 Apply Channel Transformations] CHANNEL_TRANSFORM --> PACK_FOR_DEVICE[📦 Pack with Channel Packager] PACK_FOR_DEVICE --> ADD_HEADERS[📋 Add TPDU/Channel Headers] ADD_HEADERS --> SEND_TO_DEVICE[📱 Send Response to Device] SEND_TO_DEVICE --> UPDATE_DATABASE[💾 Update pos_temp_transaction] UPDATE_DATABASE --> END([Response Complete]) %% Error Handling CORRELATION_LOOKUP -->|Timeout/Error| ERROR_RESPONSE[❌ Create Error Response] UNPACK_ASYNC -->|Error| ERROR_RESPONSE UNPACK_SYNC -->|Error| ERROR_RESPONSE ERROR_RESPONSE --> PACK_FOR_DEVICE %% Styling classDef startEnd fill:#e1f5fe classDef process fill:#f3e5f5 classDef async fill:#e8f5e8 classDef sync fill:#fff3e0 classDef database fill:#fce4ec classDef error fill:#ffebee class START,END startEnd class ASYNC_CORRELATOR,CORRELATION_LOOKUP,INVOKE_CALLBACK async class SYNC_RESPONSE sync class UPDATE_DATABASE database class ERROR_RESPONSE,LOG_ORPHAN error ``` ### **🔍 Detailed Response Processing Steps** #### **1. Upstream Response Reception** ```elixir # AsyncCorrelator handles TCP response def processing(:info, {:tcp, socket, data}, %{socket: socket} = state_data) do case handle_upstream_response(data, state_data) do {:ok, new_state_data} -> {:next_state, :connected, new_state_data} {:error, reason} -> {:keep_state_and_data} end end ``` #### **2. Response Unpacking & Correlation** ```elixir defp handle_upstream_response(data, state_data) do # Unpack response with network packager packager = Map.get(state_data.network_config, :packager) {:ok, response_message} = packager.unpack(data) # Extract correlation key (STAN or RRN) correlation_key = extract_correlation_key(response_message, state_data.correlation_field) # Lookup original request in ETS table case :ets.lookup(state_data.correlation_table, correlation_key) do [{^correlation_key, request_info}] -> # Cancel timeout timer Process.cancel_timer(request_info.timer_ref) # Invoke callback function spawn(fn -> request_info.callback.(response_message) end) end end ``` #### **3. Response Transformation Pipeline** ```elixir def process_upstream_response(%ISOMsg{} = upstream_response, channel_context) do # Apply response transformation for originating channel transformed_response = transform_for_channel(upstream_response, channel_context) # Validate response before sending to device case validate_outgoing_message(transformed_response) do {:ok, validated_response} -> {:ok, validated_response} {:error, reason} -> create_error_response(upstream_response, reason, channel_context) end end ``` #### **4. Channel Response Formatting** ```elixir defp transform_for_channel(%ISOMsg{} = response_message, channel_context) do response_message |> remove_processing_metadata() # Remove internal fields |> apply_channel_transformations(channel_context) # Channel-specific transforms |> set_channel_packager(channel_context) # Use correct packager end ``` #### **5. Response Transmission to Device** ```elixir defp send_response(socket, transport, response_data) do # Add length prefix for framing total_length = byte_size(response_data) message = <> <> response_data case transport.send(socket, message) do :ok -> Logger.debug("Response sent successfully") {:error, reason} -> Logger.error("Failed to send response") end end ``` ### **📊 Response Processing Components** #### **AsyncCorrelator Response Handling** - **Purpose**: Correlates responses with original requests using STAN/RRN - **ETS Tables**: In-memory correlation tracking with timeout management - **Callback Mechanism**: Asynchronous response delivery to waiting processes - **Telemetry**: Response time tracking and success/failure metrics #### **UpstreamRouter Response Processing** - **Unpacking**: Network-specific packager selection for response parsing - **Transformation**: Apply reverse transformations from upstream format - **Error Handling**: Convert network errors to ISO8583 response codes #### **Channel Response Management** - **Packager Selection**: Use originating channel's packager for response - **Header Processing**: Add/remove TPDU headers based on channel config - **Framing**: Apply length prefixes and terminators per channel protocol #### **Database Updates** - **Transaction Status**: Update pos_temp_transaction with final response - **Audit Trail**: Complete transaction logging with response codes - **State Management**: Transaction lifecycle completion ### **🔄 Response Flow Examples** #### **Successful Authorization Response (0210)** ``` Visa Network → TCP Response → AsyncCorrelator → Correlation Match → Callback Execution → IncomingMessageProcessor → Channel Transform → Pack with ISO87BPackager → Add TPDU Header → Send to Device → Update pos_temp_transaction status=completed ``` #### **Declined Transaction Response (0210 with RC=51)** ``` MasterCard Network → Response RC=51 → AsyncCorrelator → Callback → Response Processing → Channel Transform → Device Response → Database Update status=declined ``` #### **Network Error Response (0210 with RC=91)** ``` Upstream Timeout → UpstreamRouter Error → Create Error Response MTI=0210 RC=91 → Channel Processing → Device Response → Database Update status=error ``` --- ## **📋 Complete Transaction Lifecycle Summary** ✅ **Complete Sales Flow**: Full MTI 0200 → 0210 processing pipeline ✅ **Complete Reversal Flow**: Full MTI 0400 → 0410 processing pipeline ✅ **Complete Response Flow**: Upstream response handling and device delivery ✅ **YSP Integration**: Native YSP message transformations with field mappings ✅ **Database Integration**: Complete pos_temp_transaction lifecycle management ✅ **Error Handling**: Comprehensive validation and error response generation ✅ **Async Processing**: High-throughput async correlation for production networks ✅ **Network Routing**: Intelligent routing based on card BIN and processor selection ### **🚀 Production Readiness** - **Validation**: Multi-level validation (syntax, business rules, YSP-specific) - **Error Recovery**: Automatic error response generation with proper MTI conversion - **Performance**: Async correlation for high-volume networks (Visa/MasterCard) - **Monitoring**: Complete logging and telemetry throughout the pipeline - **Scalability**: Load balancing and instance management across network types - **Response Handling**: Complete upstream response correlation and device delivery