# QRMiddleLayer

- Adding /ysp-simulator

## YSP card API (14 active endpoints)

The middle layer forwards card calls to YSP (or the YSP simulator in `ysp-simulator/`) and returns YSP's response unchanged.

The 14 endpoints below are active, each reachable as `POST /api/card/<name>` with the JSON body YSP expects (the middle layer adds `msgHdr`, and a `txnRefNo` when you leave it out). Balance and block check their fields themselves; the others check the "Required fields" below and YSP's own validation answers the rest. Unknown name: 404. Missing field: 400, nothing sent. Critical endpoints are never retried, and a timeout or unreadable answer says the call "may or may not have been applied". Samples: the Postman collection, and `ysp-simulator/demo.sh`.

The other 26 YSP card endpoints (for example `amountrefund`) are switched off: `POST /api/card/<name>` answers 404 `{"error": "endpoint_not_enabled", ...}` and nothing is sent to YSP. They are still in `DaProductApp.YspCard.Endpoints` (`inactive/0`), so one is switched back on by removing its name from `@inactive` there.

`balance`: `{"proxyNumber": "..."}`. `block`: `{"proxyNumber": "...", "flag": "L|UL|BL|BS|BD", "reason": "..."}`. `carddetails` takes `proxyNumber` or `customerId`.

<!-- ysp-endpoints:start (generated by docs/postman/generate.exs) -->

**Sprint 1**

| Route | YSP call | apikey | Criticality | Required fields |
|---|---|---|---|---|
| `POST /api/card/balance` | GET `cardbalance` | `APACBL` | standard | see note |
| `POST /api/card/load` | POST `accountfunding` | `APLCRD` | critical | see note |
| `POST /api/card/block` | POST `cardlockunlock` | `ACDSTS` | critical | see note |

**A. Read-only**

| Route | YSP call | apikey | Criticality | Required fields |
|---|---|---|---|---|
| `POST /api/card/carddetails` | POST `carddetails` | `APCHDT` | standard | see note |
| `POST /api/card/transactiondetails` | GET `transactiondetails` | `APXTXN` | standard | `proxyNumber` |
| `POST /api/card/statusrequest` | GET `statusrequest` | `APSTRQ` | standard | `txnRefNo` |
| `POST /api/card/cardorderstatus` | GET `cardorderstatus` | `APCOST` | standard | `invoiceNo` |

**B. Card setup and settings**

| Route | YSP call | apikey | Criticality | Required fields |
|---|---|---|---|---|
| `POST /api/card/customerregistration` | POST `customerregistration` | `APNCRD` | critical | `customerInfo`, `loadDetails` |
| `POST /api/card/customerupdate` | POST `customerupdate` | `APUPCR` | standard | `customerInfo` |
| `POST /api/card/cardactivation` | POST `cardactivation` | `APCDAC` | critical | `proxyNumber` |
| `POST /api/card/cardreplacement` | GET `cardreplacement` | `APCDRP` | critical | `proxyNumber`, `type` |
| `POST /api/card/cardorder` | POST `cardorder` | `APCROR` | standard | `order` |

**C. Money movement**

| Route | YSP call | apikey | Criticality | Required fields |
|---|---|---|---|---|
| `POST /api/card/debitcreditaccount` | POST `debitcreditaccount` | `APCRDR` | critical | `proxyNumber`, `productCode`, `type`, `flag`, `amount`, `currency`, `remarks` |
| `POST /api/card/fundtransfer` | POST `fundtransfer` | `APFDTR` | critical | `sourceAccount`, `destAccount` |

<!-- ysp-endpoints:end -->

Run it locally (these routes have no authentication yet, so use the simulator only):

```bash
cd ysp-simulator && mix run --no-halt                                  # simulator on 4180
YSP_CARD_BASE_URL=http://localhost:4180 mix phx.server                 # middle layer on 4006
```

Then import `docs/postman/bank-bridge-ysp-card.postman_collection.json` into Postman (Import) or Bruno (Import Collection > Postman Collection) and run it top to bottom against a freshly reset simulator (the first request resets it). The collection is generated: run `mix run --no-start docs/postman/generate.exs` after changing `docs/postman/builder.exs` or the endpoint table. Variables: `baseUrl` (middle layer), `simUrl` (simulator, used only by the reset step), `proxyNumber` (seed card `000000012845`).

Settings: `YSP_CARD_BASE_URL` (default `http://localhost:4180`), `YSP_CARD_CLIENT_ID`, `YSP_CARD_NET_ID`, `YSP_CARD_TIMEOUT_MS` (default 5000). Tests: the integration tests (`mix test --include integration`) call all 40 endpoints, so they need your own simulator with the gate off, on its own port; the commands are in the `@moduledoc` of `test/da_product_app/ysp_card_integration_test.exs`.