# Management Transaction Flow

Covers: **Key Exchange (MTI 0800)**

Entry point: `jpos/src/dist/cfg/serversimulator.bsh`

## Key Exchange Sub-Types

DE-3 (processing code) determines the variant:

| DE-3 | Sub-type | Bank Call? |
|------|----------|-----------|
| empty / absent | Echo | No — response returned immediately |
| `810000` | TMK (Terminal Master Key) exchange | Yes |
| `811000` | PIN / IPEK exchange | Yes |

```mermaid
sequenceDiagram
    autonumber
    participant DEV as POS Device
    participant QS as QServer<br/>(11_bshserver.xml)
    participant CH as NCCChannel /<br/>NACChannel
    participant BSH as BSHRequestListener
    participant SIM as serversimulator.bsh
    participant TR as TransactionRouter
    participant TPI as TransactionProcessorImpl
    participant YLAT as JposYspTranslator
    participant YC as YspChannel
    participant BANK as Acquirer Bank

    %% ── 1. Request Ingestion ──────────────────────────────────────────────────
    DEV->>QS: TCP connect (port 19000 / 19001)
    QS->>CH: createSession()
    CH->>BSH: onRequest(source, ISOMsg 0800)
    BSH->>SIM: execute(source, message)<br/>cfg/serversimulator.bsh

    note over SIM: MTI = 0800 → routed to TransactionRouter

    SIM->>TR: handleRequest(ISOMsg 0800)

    %% ── 2. Validation ─────────────────────────────────────────────────────────
    TR->>TR: validateAndStoreRequest()<br/>extract DE-41 (TID), DE-42 (MID)
    TR->>TPI: processTransaction(txnBeanContainer)

    %% ── 3. Translator Routing (toMessage) ─────────────────────────────────────
    TPI->>YLAT: toMessage(jposRequest, acquirerTerminal, metadata)

    alt DE-3 empty / absent — Echo
        YLAT-->>TPI: echo ISOMsg (no bank call)
        note over YLAT: Copies DE-3, DE-11, DE-41, DE-42<br/>back as response immediately
    else DE-3 = "810000" — TMK Exchange
        YLAT->>YC: transceive(tmkKeyExchangeMsg, acquirerConnection)
        YC->>BANK: ISO-8583 0800 (TCP/SSL)<br/>TPDU + length + TMK request
        BANK-->>YC: key exchange response
        YC-->>TPI: ISOMsg bankResponse
    else DE-3 = "811000" — PIN / IPEK Exchange
        YLAT->>YC: transceive(pinKeyMsg, acquirerConnection)
        YC->>BANK: ISO-8583 0800 (TCP/SSL)<br/>TPDU + length + PIN key request
        BANK-->>YC: key exchange response
        YC-->>TPI: ISOMsg bankResponse
    end

    %% ── 4. Response Translation (fromMessage) ──────────────────────────────────
    TPI->>YLAT: fromMessage(bankResp, jposReq, acqReq, metadata)
    note over YLAT: Copies DE-3, DE-11, DE-41, DE-42<br/>DE-63 is explicitly cleared — NO receipt for 0800
    YLAT-->>TPI: ISOMsg jposResponse (MTI 0810)

    %% ── 5. Response Delivery ──────────────────────────────────────────────────
    TPI-->>TR: ISOMsg jposResponse
    TR-->>SIM: ISOMsg jposResponse
    SIM->>CH: source.send(jposResponse)
    CH->>DEV: ISO-8583 0810 response
```

## Differences from Financial Flow

| Aspect | Financial | Key Exchange (0800) |
|--------|-----------|---------------------|
| Rules evaluation | Yes (EvaluateRules REST call) | No |
| DB onboarding | Yes (pos_temp_transaction) | No |
| Receipt generation | Yes (DE-63 JSON) | Never — DE-63 cleared |
| Bank call | Always | Only for TMK / PIN variants |
| Translator | Ysp or Fiserv (based on acquirer) | Always JposYspTranslator |
| Response MTI | request MTI + 10 (e.g. 0210) | 0810 |

## Key Source Files

| File | Role |
|------|------|
| `jpos/src/dist/cfg/serversimulator.bsh` | Entry point — MTI dispatch |
| `jpos/src/dist/deploy/11_bshserver.xml` | QServer (port 19000, NCCChannel) |
| `jpos/src/dist/deploy/12_bshserver_nac.xml` | QServer (port 19001, NACChannel) |
| `jpos/src/main/java/org/jpos/tcpay/TransactionRouter.java` | Routes 0800 to processor |
| `jpos/src/main/java/org/jpos/tcpay/processor/TransactionProcessorImpl.java` | Lifecycle orchestration |
| `jpos/src/main/java/org/jpos/tcpay/acquirer/ysp/JposYspTranslator.java` | Key exchange sub-type routing in `toMessage()` / `fromMessage()` |
| `jpos/src/main/java/org/jpos/tcpay/connection/YspChannel.java` | YSP SSL socket — TPDU packet send/receive |