Files
hardlink/docs/payment-api.md
T

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 /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.