15 KiB
Modern payment API
Project overview | Configuration | Operations
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:
{"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:
{"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:
{"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.
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/takepreauthretain 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 useNOTIFICATION, retained asCARD_STATUSon 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 atTransactionFinished; finalization never waits for card removal. CardRemovalRequestedandCardRemovalEnforcedfollow 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.Removedremains omitted even with a reference, and the existingInsertedmapping 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
Clientlifetime across SALE and PREAUTH. New transactions, elapsed time, callbacks and automatic reconnect do not reset the guard. Payments remain enabled. - Only the exact synchronous
ClientNotConnectedToServererror safely clears an unsuppressed window and releases its unused reference: SDK 3.17StartCommandreturns it beforeSendRequest. 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.
OnlineAuthCompletedmeans waiting;Removedand 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.