refactor(hardlink): migrate Go module to v2
This commit is contained in:
@@ -0,0 +1,184 @@
|
||||
# Modern payment API
|
||||
|
||||
[Project overview](../README.md) | [Configuration](configuration.md) | [Operations](operations.md)
|
||||
|
||||
Hardlink owns CMS provider selection and all provider-specific processing. Operafyne and checkinfyne use only `POST /api/payment/sale` and `POST /api/payment/preauth`. Deploy matching versions together; older modern-endpoint request/result formats are no longer supported. The deprecated `/takepayment` and `/takepreauth` contracts and execution cores are unchanged.
|
||||
|
||||
| Endpoint | Request | Purpose |
|
||||
| --- | --- | --- |
|
||||
| `POST /api/payment/sale` | JSON integer minor units | Provider-independent Sale |
|
||||
| `POST /api/payment/preauth` | JSON integer minor units | CreditCall PREAUTH/account verification or Trust positive PREAUTH |
|
||||
| `POST /takepayment` | `text/xml` | Retained legacy CreditCall Sale; not used by Fyne |
|
||||
| `POST /takepreauth` | `text/xml` | Retained legacy CreditCall PREAUTH/account verification; not used by Fyne |
|
||||
|
||||
## Request
|
||||
|
||||
Both endpoints accept JSON with integer minor units:
|
||||
|
||||
```json
|
||||
{"reference":"SYNTH-BOOK","amount":2500,"currency":"GBP","checkoutDate":"2026-11-04 00:00:00 +0000"}
|
||||
```
|
||||
|
||||
`reference` and `checkoutDate` are optional. Currency comes from the existing CMS hotel response. Startup supplies CMS currency to the selected service; no dedicated local currency setting exists. The currency is bookkeeping data, not evidence of terminal settlement currency. Trust does not transmit or validate provider currency.
|
||||
|
||||
A Sale that requires a later mandatory hold includes its prerequisite:
|
||||
|
||||
```json
|
||||
{"reference":"SYNTH-BOOK","amount":10000,"currency":"GBP","requiredPreauth":{"amount":2500,"checkoutDate":"2026-11-04 00:00:00 +0000"}}
|
||||
```
|
||||
|
||||
Hardlink validates that the selected provider supports that hold before dispatching the Sale. This field does not start PREAUTH. CreditCall supports positive PREAUTH and zero-amount account verification. Trust supports positive Sale/PREAUTH. The current Dojo and PayBridge implementations support Sale only and reject PREAUTH without dispatching a transaction.
|
||||
|
||||
## Stream
|
||||
|
||||
The response is `application/x-ndjson`. Progress is observational:
|
||||
|
||||
```json
|
||||
{"type":"status","code":"PAYMENT_PROCESSING"}
|
||||
{"type":"result","result":{"outcome":"approved","httpStatus":200,"retryable":false,"provider":"creditcall","amountMinor":2500,"currencyCode":"GBP","transactionReference":"SYNTH-REFERENCE","cardType":"Visa","maskedCardNumber":"************1133"}}
|
||||
```
|
||||
|
||||
Every provider uses `result`; there is no redirect URL or `response` variant. Outcomes are `approved`, `declined`, `cancelled`, `timeout`, `error` and `unknown`. Definitive declines/cancellations, confirmed signature rejection and known pre-dispatch terminal-session unavailability retain their existing guest retry eligibility. A timeout, malformed result, connection loss, Dojo `Expired` or other unresolved post-dispatch result is `unknown` and requires reception review. Progress codes never establish approval or retry eligibility.
|
||||
|
||||
Hardlink returns real normalized card metadata: masked card number, card type, expiry, transaction reference, card hash and card reference, where available. Receipt number, sequence, authorization code and last four remain separate optional metadata. Authorization codes are not card hashes; card type plus last four is not a card reference. Unmasked PAN is omitted rather than encoded or sent to the kiosk.
|
||||
|
||||
CreditCall reports a valid returned `TOTAL_AMOUNT` as the actual terminal amount. If the field is absent, its existing approved-request amount contract is retained. A malformed, negative or out-of-range returned amount produces non-retryable uncertainty. Fyne's existing exact-amount guard sends a request/result mismatch to reception rather than treating the requested amount as the actual hold. CreditCall's legacy transaction and SQL-persistence code is unchanged.
|
||||
|
||||
Hardlink prints terminal receipts within provider execution. Fyne constructs complete PMS payment descriptions locally; Hardlink does not return PMS descriptions or add kiosk/Pay/Pre prefixes.
|
||||
|
||||
## Transaction ownership
|
||||
|
||||
The existing `paymentsvc` busy guard admits one modern Sale or PREAUTH at a time. There is no queue, durable terminal journal or recovery API. A detached transaction worker executes independently of HTTP disconnects and progress backpressure. The bounded progress queue may drop hints; final outcome has its own channel. Only the handler writes NDJSON.
|
||||
|
||||
The shared worker budget is configured `timeoutSeconds` (default 300) plus a 15-second status/delivery margin. Trust retains one financial POST bounded to 300 seconds and at most one same-reference `/status` lookup bounded to 15 seconds. CreditCall retains its separate 300-second start and confirmation call bounds; its existing confirmation and asynchronous PREAUTH persistence are not shortened by the shared response budget. Dojo and PayBridge retain their existing protocol exchanges and internal connection timeouts.
|
||||
|
||||
Printing/finalization continues after kiosk disconnect. A restart or disconnected process can nevertheless lose approval before kiosk capture. Reception must reconcile those transactions. No cross-restart terminal deduplication or automatic guest Check-In resumption is claimed. Existing Fyne approved-payment capture and ten-minute PMS fallback remain independent and unchanged.
|
||||
|
||||
## Reconciliation diagnostics
|
||||
|
||||
Dojo and PayBridge record provider-boundary warnings when transport fails or a result remains uncertain, including when no result object is returned. The structured fields include `provider`, `operation`, `stage`, `request_id`, the existing `transaction_reference` mapping, and a safe `error_category`. Known payment-intent, terminal-session, provider-transaction and provider-reference identifiers are included separately. A locally generated request/reference is not proof of provider receipt or approval.
|
||||
|
||||
Categories distinguish timeout, cancellation, connection failure, response loss, invalid response and unresolved/provider errors. HTTP status and WebSocket close codes are included where available. Raw error strings, response bodies, gateway query credentials, JWTs and card data are excluded. These diagnostics do not alter returned results/errors, retry eligibility, the NDJSON contract or financial dispatch.
|
||||
|
||||
Trust configuration/initialization failures use the existing fatal email-notification mechanism. The common provider-enabled startup message covers CreditCall, Trust, Dojo and PayBridge. No new configuration or notification system is required.
|
||||
|
||||
The shared client package is `gitea.futuresens.co.uk/futuresens/hardlink/v2/paymentapi`; progress codes are in `/v2/paymentstatus`. Deploy compatible Hardlink and Fyne revisions together. Publish the actual v2 tag before replacing the Fyne local-validation marker and regenerating module sums. The application build version alone is not a dependency pin. See [operations](operations.md#coordinated-application-releases).
|
||||
|
||||
## Offline validation
|
||||
|
||||
Provider tests use loopback/in-memory transports; handler tests block default network access and inject fake printing. `internal/mail/Test_SendMail` is a pre-existing live-email test and must be excluded from offline runs. CreditCall PREAUTH persistence uses the established 96-hour release offset after the stored departure midnight; its characterization test asserts that contract without changing the returned terminal amount. The dispenser caller-deadline regression counts complete AP observations rather than partial ACK reads. Neither regression is excluded from the relevant suites.
|
||||
|
||||
## Native HTTP clients
|
||||
|
||||
Modern Sale/PREAUTH routes do not provide browser CORS headers or OPTIONS preflight handling. POST and the unified NDJSON contract are unchanged; non-POST requests use the existing 405 structured rejection. This does not alter deprecated `/takepayment` or `/takepreauth`, provider execution after disconnect, or the ChipDNA `/logerror` integration.
|
||||
|
||||
## CreditCall streaming and PREAUTH
|
||||
|
||||
This section preserves the ChipDNA integration contract separately from the
|
||||
provider-independent Fyne wire format. Deploy compatible ChipDNAClientCLI,
|
||||
Hardlink and Fyne binaries in one maintenance window. The unified wire contract
|
||||
does not require a CreditCall SQL-schema migration.
|
||||
|
||||
### ChipDNAClientCLI contract
|
||||
|
||||
Both modern endpoints use the common request/result contract above. A positive CreditCall `/api/payment/preauth` amount maps internally to the existing unconfirmed `Sale`; zero maps to `AccountVerification`.
|
||||
|
||||
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 allowlisted SDK
|
||||
fields, or a sanitized `error`. `TRANSACTION_TYPE` and optional `TOTAL_AMOUNT`
|
||||
are included only when returned by the provider. They are never synthesized and
|
||||
are not forwarded as raw SDK fields to the kiosk. A valid `TOTAL_AMOUNT` is
|
||||
normalized into `amountMinor` as described above. AccountVerification normally omits
|
||||
`TOTAL_AMOUNT`. Receipt XML may be a JSON string field needed by
|
||||
hardlink's existing receipt handler; it is never a raw line in the stream.
|
||||
SALE confirmation continues through the existing, separate XML endpoint.
|
||||
|
||||
### Lifetime, confirmation and progress
|
||||
|
||||
- `/start-transaction/`, `/takepayment`, and `/takepreauth` retain their existing
|
||||
external contracts. Both SALE and PREAUTH stream to the native Fyne clients;
|
||||
existing SQL persistence/release behavior remains unchanged.
|
||||
- Both Fyne applications use the common private 330-second terminal client for SALE and PREAUTH.
|
||||
This is only the kiosk wait boundary for all providers.
|
||||
Timeout/cancellation is technical, not an authoritative decline or automatically
|
||||
retryable result. It never triggers a second start or legacy endpoint fallback.
|
||||
- Validation uses the inbound request. At financial dispatch handoff, hardlink
|
||||
detaches cancellation with `context.WithoutCancel`. Inbound cancellation and
|
||||
write failures control only delivery; result processing, SALE confirmation,
|
||||
receipts and PREAUTH persistence scheduling continue independently.
|
||||
- Start and each SALE 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, receipt handling, or PREAUTH persistence scheduling. 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.
|
||||
- `CardRemovalRequested` and `CardRemovalEnforced` follow the same active-window
|
||||
rule as other progress, including when no reference is supplied. Real Miura
|
||||
insertion-recovery sequences can repeat present-card and remove-card prompts
|
||||
within one transaction; these repeated prompts are not deduplicated. Outside
|
||||
the active window they are discarded. `Removed` remains omitted even with a
|
||||
reference, and the existing `Inserted` mapping is unchanged.
|
||||
- Ownership is best-effort UI observation. SDK 3.17 does not establish that every
|
||||
queued reference-less callback, including removal, 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 across SALE and PREAUTH. 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.
|
||||
|
||||
### Persistence and release
|
||||
|
||||
Approved monetary PREAUTH schedules the existing asynchronous SQL persistence,
|
||||
with spool handling on persistence failures. Account verification follows the
|
||||
existing `PreauthDecision` without inventing `TOTAL_AMOUNT`. The stored departure
|
||||
midnight plus 96 hours determines the release date. The separate
|
||||
`hardlink-preauth-release` executable releases due CreditCall holds; the HTTP
|
||||
service does not run that task automatically. Trust PREAUTH is not inserted into
|
||||
the CreditCall SQL release workflow.
|
||||
|
||||
### Verification and physical acceptance
|
||||
|
||||
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 both Fyne applications, use their guarded offline terminal, posting and
|
||||
fallback regression suites. Verify the shared `paymentapi` Sale/PREAUTH decoder,
|
||||
common 330-second terminal client, cancellation after dispatch, uncertain-result
|
||||
handling, retry limits and normal/fallback description parity. There is no
|
||||
provider-specific Fyne parser or legacy `response` frame. Opera and Guestline
|
||||
retain their separate financial and PMS posting workflows; follow each
|
||||
application's current verification instructions.
|
||||
|
||||
Earlier integration notes recorded approved `ACCOUNT VERIFICATION` with no
|
||||
`TOTAL_AMOUNT`. An earlier monetary `/takepayment` test recorded returned minor
|
||||
units; positive PREAUTH through the modern transport still needs physical Miura
|
||||
validation. Automated tests do not replace that check. Receipt fields such as
|
||||
`NoChargeDeclaration` retain the existing provider-entry rendering behavior.
|
||||
|
||||
This documentation reorganization did not execute SDK, terminal or hardware tests.
|
||||
Reference in New Issue
Block a user