# Financial Transaction Flow

Covers: **Sale**, **Sale-Tip**, **Refund**, **Void**, **Pre-Auth**, **Auth-Completion**

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

```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 DB as Database
    participant ER as EvaluateRules<br/>(REST)
    participant TPI as TransactionProcessorImpl
    participant XLAT as JposAcquirerTranslator<br/>(Ysp / Fiserv)
    participant AC as AcquirerChannel<br/>(YspChannel / FiservChannel)
    participant BANK as Acquirer Bank
    participant RG as ReceiptGenerator

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

    note over SIM: MTI dispatch:<br/>0100/0200/0220/0400 → router<br/>0500/0320 → inline response

    SIM->>TR: handleRequest(ISOMsg)

    %% ── 2. Validation & Onboarding ────────────────────────────────────────────
    TR->>TR: validateAndStoreRequest()<br/>extract DE-41 (TID), DE-42 (MID)<br/>map to PosTerminal + AcquirerTerminal
    TR->>DB: preprocess()<br/>check terminal not busy, check reversals
    TR->>DB: onboardRequest()<br/>INSERT pos_temp_transaction

    %% ── 3. Rules Evaluation ───────────────────────────────────────────────────
    TR->>ER: evaluateRulesCheck(metadata)
    ER-->>TR: RULES_* metadata<br/>(merchant name/address/logo,<br/>footer, RULES_MODEL_NAME_ENABLED)

    alt Rules decline
        TR->>TPI: generateFailedMsg(jposRequest, metadata)
        opt RULES_MODEL_NAME_ENABLED = true
            TPI->>RG: generateReceipt(req, declinedResp, metadata)
            RG-->>TPI: JSON receipt → DE-63
        end
        TPI-->>TR: ISOMsg declinedResponse (RC ≠ 00)
        note over TR,SIM: skip to response delivery
    end

    %% ── 4. Bank Communication ─────────────────────────────────────────────────
    TR->>TPI: processTransaction(txnBeanContainer)
    TPI->>XLAT: toMessage(jposRequest, acquirerTerminal, metadata)<br/>translate to acquirer format
    TPI->>AC: transceive(acquirerRequest, acquirerConnection)
    AC->>BANK: ISO-8583 (TCP/SSL)<br/>TPDU + length + message
    BANK-->>AC: ISO-8583 response
    AC-->>TPI: ISOMsg bankResponse

    %% ── 5. Response Translation & Receipt ─────────────────────────────────────
    TPI->>XLAT: fromMessage(bankResp, jposReq, acqReq, metadata)<br/>store BankTerminalId, BankMerchantId,<br/>BankStan, BankBatchNumber in metadata

    opt RULES_MODEL_NAME_ENABLED = true AND MTI ≠ 0400/0800
        XLAT->>RG: generateReceipt(jposRequest, jposResponse, metadata)
        RG-->>XLAT: JSON receipt string → DE-63
    end

    XLAT-->>TPI: ISOMsg jposResponse
    TPI->>DB: completeTransaction()<br/>approved → pos_transaction<br/>declined → pos_failed_transaction

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

## Transaction Types

| MTI | DE-3 (proc code) | Type | Account Message on Receipt |
|-----|------------------|------|---------------------------|
| `0100` | any | Pre-Auth | PLEASE DEBIT MY ACCOUNT |
| `0200` | `00xxxx` | Sale (Sale-Tip if DE-54 present) | PLEASE DEBIT MY ACCOUNT |
| `0200` | `20xxxx` | Refund | PLEASE CREDIT MY ACCOUNT |
| `0200` | `02xxxx` | Void-Sale / Void-Preauth / Void-Completion | PLEASE CREDIT MY ACCOUNT |
| `0220` | `20xxxx` | Refund | PLEASE CREDIT MY ACCOUNT |
| `0220` | other | Auth-Completion | PLEASE DEBIT MY ACCOUNT |
| `0400` / `0420` | any | Void — **no receipt generated** | — |

## Inline-Handled MTIs (bypass TransactionRouter)

| MTI | Action in serversimulator.bsh |
|-----|-------------------------------|
| `0500` | Clone + RC=`00`, clear DE-63, send |
| `0320` | Clone + RC=`00`, clear DE-2/14/35/55, send |
| other | Clone + random STAN/AuthCode + RC logic on DE-4 amount |

## 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` | Validates, onboards, orchestrates |
| `jpos/src/main/java/org/jpos/tcpay/processor/TransactionProcessorImpl.java` | Financial lifecycle |
| `jpos/src/main/java/org/jpos/transaction/participant/EvaluateRules.java` | Rules REST call |
| `jpos/src/main/java/org/jpos/tcpay/acquirer/JposAcquirerTranslator.java` | Translation interface |
| `jpos/src/main/java/org/jpos/tcpay/acquirer/ysp/JposYspTranslator.java` | YSP translator |
| `jpos/src/main/java/org/jpos/tcpay/acquirer/fiserv/JposFiservTranslator.java` | Fiserv translator |
| `jpos/src/main/java/org/jpos/tcpay/connection/YspChannel.java` | YSP SSL socket |
| `jpos/src/main/java/org/jpos/tcpay/connection/FiservChannel.java` | Fiserv SSL socket |
| `jpos/src/main/java/org/jpos/tcpay/service/ReceiptGenerator.java` | JSON receipt → DE-63 |