feat: stream CreditCall payment progress and results
This commit is contained in:
@@ -0,0 +1,93 @@
|
||||
# CreditCall payment streaming
|
||||
|
||||
Deploy ChipDNAClientCLI, then hardlink, then Operafyne. No database or configuration
|
||||
migration is needed. The existing CreditCall provider selection enables the new
|
||||
sale route; CreditCall does not implement the generic payment provider interface.
|
||||
|
||||
## Contracts
|
||||
|
||||
`POST /api/payment/sale` accepts the existing JSON sale request, for example
|
||||
`{"amount":1234,"confirmNo":"BOOKING-123","currency":"GBP"}`. Amount remains in
|
||||
minor units. CreditCall uses its existing SDK transaction reference generation.
|
||||
|
||||
For CreditCall, responses contain newline-delimited JSON:
|
||||
|
||||
```json
|
||||
{"type":"status","code":"PAYMENT_PRESENT_CARD"}
|
||||
{"type":"result","result":{"outcome":"approved","message":"Payment approved","httpStatus":200,"status":{"code":200,"message":"Approved"},"transactionReference":"native-reference","cardType":"Visa","maskedCardNumber":"************1234","expiryDate":"1228","cardHash":"existing-hash","cardReference":"existing-card-reference"}}
|
||||
```
|
||||
|
||||
`outcome` is `approved`, `declined`, `cancelled`, `timeout`, or `error`. Approval
|
||||
is produced only by the shared CreditCall transaction/finalization core, including
|
||||
the existing confirmation behavior. `httpStatus` preserves the equivalent legacy
|
||||
operation status even after streaming commits HTTP 200. `status` preserves the
|
||||
existing processor `StatusRec`. Failure `message` preserves the plain description
|
||||
used by the legacy flow, including its existing interpretation quirks.
|
||||
|
||||
Card fields are emitted only on success. Unmasked or unexpected card-number data
|
||||
is omitted; encoding is not masking. Receipts and raw SDK parameter bags are not
|
||||
sent to Operafyne. The new adapter never builds a redirect URL. Dojo and PayBridge
|
||||
continue using their existing `{"type":"result","response":...}` contract.
|
||||
|
||||
Hardlink calls `POST /start-transaction-stream/` on ChipDNAClientCLI with
|
||||
`{"amount":"1234","transactionType":"Sale"}`. Its NDJSON consists of allowlisted
|
||||
`status` frames (`source`, `value`), a single `result` containing the required SDK
|
||||
fields, or a sanitized `error`. Receipt XML may be a JSON string field needed by
|
||||
hardlink's existing receipt handler; it is never a raw line in the stream.
|
||||
Confirmation continues through the existing, separate XML endpoint.
|
||||
|
||||
## Lifetime and compatibility
|
||||
|
||||
- `/start-transaction/`, `/takepayment`, and `/takepreauth` retain their existing
|
||||
external contracts. Preauthorization and SQL persistence/release remain legacy.
|
||||
- Start and each confirmation call retain their independent 300-second timeout.
|
||||
Confirmation still uses two attempts, retrying transport/read errors with the
|
||||
existing two-second delay. The generic whole-operation timeout is not used.
|
||||
- Kiosk cancellation or failed/blocked kiosk delivery does not cancel upstream reading,
|
||||
confirmation, or receipt handling. Progress queues may drop hints when full;
|
||||
final results have a separate slot and are delivered at most once.
|
||||
- Only the response writer writes frames. Transaction execution never waits
|
||||
for progress delivery. No additional delivery timer or whole-operation deadline
|
||||
shortens the existing HTTP call bounds.
|
||||
- Native SDK 3.17 updates use `UPDATE`; card notifications use `NOTIFICATION`,
|
||||
retained as `CARD_STATUS` on the internal wire. Normal progress does not require
|
||||
a reference: it is accepted only inside the existing serial transaction's active
|
||||
observational window. A supplied nonempty reference must match. The window opens
|
||||
immediately before the SDK start call and closes immediately at
|
||||
`TransactionFinished`; finalization never waits for card removal.
|
||||
- Unidentified `CardRemovalRequested` and `CardRemovalEnforced` updates are omitted
|
||||
because they can arrive after financial completion. They require a matching
|
||||
explicit reference. `Removed` remains omitted even with a reference.
|
||||
- Ownership is best-effort UI observation. SDK 3.17 does not establish that every
|
||||
queued reference-less non-removal callback has drained before another transaction
|
||||
starts. Such a callback may briefly display stale progress in a later active
|
||||
window. This accepted limitation must never affect success, decline, cancellation,
|
||||
timeout outcomes, confirmation, retry, receipts, PMS posting, or business state.
|
||||
- After timeout, an ambiguous start error, an asynchronous SDK error during an
|
||||
active window, or reference reuse/overlap, progress remains suppressed for that
|
||||
`Client` lifetime. New transactions, elapsed time, callbacks and automatic
|
||||
reconnect do not reset the guard. Payments remain enabled.
|
||||
- Only the exact synchronous `ClientNotConnectedToServer` error safely clears an
|
||||
unsuppressed window and releases its unused reference: SDK 3.17 `StartCommand`
|
||||
returns it before `SendRequest`. Validation errors, mixed errors and all other
|
||||
unproven errors suppress observation. Safe pre-dispatch rejection never clears
|
||||
an existing suppression latch.
|
||||
- Progress cannot approve, decline, confirm, cancel, or retry a transaction.
|
||||
`OnlineAuthCompleted` means waiting; `Removed` and unknown events are omitted.
|
||||
|
||||
## Automated verification
|
||||
|
||||
In hardlink, use `go test -count=1 -skip '^Test_SendMail$' ./...` to exclude the
|
||||
existing test that sends real email. Focused tests cover legacy parity, malformed
|
||||
XML/NDJSON, retained confirmation fields and receipts, retries, disconnects,
|
||||
backpressure, field filtering, and conservative status mapping. Race checks cover
|
||||
the changed handler and mapper packages. No test proves absence of orphan holds.
|
||||
|
||||
In ChipDNAClientCLI, build `ChipDnaClient.sln` and `Tests/StreamingTests.csproj`
|
||||
with MSBuild, then run `Tests/bin/Debug/ChipDNAClient.StreamingTests.exe`. The
|
||||
test executable links the production streaming code and needs no terminal.
|
||||
|
||||
In Operafyne, run `go test -count=1 ./...`; the service tests cover structured
|
||||
CreditCall sales, unchanged preauth requests, failure/retry parity, and existing
|
||||
Dojo/PayBridge response handling. Run `go vet ./...`, `go build ./...`, and
|
||||
`git diff --check` in both Go repositories.
|
||||
Reference in New Issue
Block a user