The changelog tracks material updates to the published Foxpay API documentation, reference contract, and integration guidance.
Open Bank Transfer docs now distinguish default provider-confirmation mode from the paid full-reconciliation add-on. Merchant integrations should not send reconciliation-mode fields in initialization requests; Foxpay admins configure the store setting. When the add-on is active, provider success remains processing until asynchronous settlement confirmation arrives, and merchant success handling waits for that settlement confirmation.
A dedicated Shopify integration page now explains the Foxpay setup path for Shopify merchants: Shopify does not provide a `whsec_` webhook secret, Foxpay verifies Shopify webhook HMAC using the Shopify app Client Secret, webhook subscriptions are created automatically after credentials are saved, and the Shopify checkout should use a manual Foxpay payment method that tells buyers to complete payment through the Foxpay email link.
The public docs and OpenAPI examples now document `endToEndId` for direct-provider Calytics OBT, clarify that provider outcomes `UNKNOWN` and `INDETERMINATE` are unresolved rather than successful, and explain that Instant OBT requests use a standard-SEPA fallback path when available. The rollout guidance also now calls out provider failure diagnostics (`failure_code`, `failure_message`) and slower settlement reconciliation expectations so merchants do not fulfil too early.
Merchant-facing invoice PDFs now present clearer payment instructions, EPC QR transfer data, recipient/company information, and reverse-charge VAT display. This is a document rendering improvement only; the public API contract and OpenAPI schema did not change.
Buyer-facing checkout and merchant-facing transaction status flows were hardened so confirmed QR Pay and POS payment updates surface more consistently. Existing integrations do not need to change request or webhook handling for this release.
POS QR payment journeys were stabilized across buyer handoff, payment status handling, and merchant transaction views. This improves the visible payment experience for merchants using in-person or QR-based payment flows without introducing a new public API field.
Calytics OBT integrations now document the global store-level control for SEPA Instant vs standard SEPA. Merchant/admin Foxpay settings should carry the default policy for a store; direct-provider API requests may send instantPayment only as a per-request override. The guidance keeps merchants such as Express Key on the shared integration path instead of requiring store-specific hardcoding.
Outbound transaction webhooks now run through a persistent retry queue per merchant: up to 12 attempts spread across ~7 days (hot phase 30s → 24h, then a long-tail to ~7 days) with ±20% jitter, replacing the legacy 3-attempt synchronous path. The first attempt still fires inline so the happy-path latency is unchanged; only failures persist a job that the worker drains. 4xx responses (400/401/403/404/410) remain terminal — no retry. Each delivery carries a new X-Foxpay-Attempt header (1-indexed) alongside X-Foxpay-Delivery; treat re-arrivals of the same X-Foxpay-Delivery as duplicates. The "webhook delivery failed" notification email now fires once when the job reaches the terminal state (exhausted / dead), not after every intermediate failure. Merchants can resend any delivery from the Technical Info tab of an expanded transaction row in the Foxpay panel; the same history is available via GET /api/transactions/{transaction_id}/webhook/history. The queue is being rolled out per merchant — older shops remain on the legacy 3-attempt path until they are flipped over. See /guides/webhook-reference and /guides/reliability.
Custom API direct-provider OBT can now omit senderName and senderIban. Foxpay creates a Calytics/finAPI hosted webform session where the buyer enters/selects their bank details; redirectUrl is canonical and sessionUrl/paymentUrl remain compatibility aliases. Terminal Calytics OBT outcomes also trigger Foxpay-signed custom merchant webhook delivery when the shop is configured for custom outbound webhooks.
The v3 buyer page now reflects merchant-side payment confirmations within ~1 second via Supabase Realtime (the prior broadcast was sent on an unsubscribed channel and silently dropped — fixed). Pressing "I have paid - check now" now starts a 9-minute follow-up burst (5s × 5 → 10s × 10 → 20s × 20) so confirmations arriving a few seconds after the click surface without a re-press. The success screen runs a 5-second countdown before auto-redirecting to the merchant's returnUrl when one is configured, and falls back to a "you can close this window" hint when no returnUrl is set. Already-paid links now jump straight to the success view on mount instead of briefly rendering the QR — closes a small double-payment window.
POST /a2a/v1/checkout payloads now strip non-SEPA characters (umlauts folded to their two-letter equivalent, parentheses normalised, IBAN whitespace removed) before reaching Calytics. Merchants whose stored beneficiary contains characters outside the SEPA pain.001 character set (e.g. "FOXPAY UG (haftungsbeschränkt)") no longer hit silent provider rejections during payment initiation. The on-wire value to the bank is the SEPA-clean form; the merchant-stored beneficiary remains the human-readable original.
POST /payments/initialize with checkoutMode: direct_provider returns the buyer handoff URL on three fields: redirectUrl (canonical, recommended for new integrations), sessionUrl (documented compatibility alias), and paymentUrl (alias kept for plugins that read the same field name as in foxpay_checkout mode). All three carry an identical value. This restores the contract published on docs.foxpay.it for legacy integrators after a brief regression where only redirectUrl was emitted.
Custom REST integrations that initialise an OBT payment session now receive a clear contract: paymentMethod: open_bank_transfer routes through Calytics A2A (sandbox or production based on the API key environment). Earlier provider adapters (Xentum, Yapily) were already removed from the runtime; the documented surface is now aligned.
When the Foxpay app rejects an incoming Calytics webhook for an invalid signature, container logs now include property-named diagnostics (computed-vs-received digest length, first 4 hex chars on each side — never the secret or full digest) so a future signing-secret rotation mismatch is visible in logs within minutes instead of surfacing only as stuck transactions. No public contract change.
docs.foxpay.it/openapi/foxpay-openapi.json was re-published from the canonical foxpay-webapp export. The direct_provider response schema documents paymentUrl, redirectUrl, and sessionUrl with their roles; the example response carries all three field names so live integrators see the actual on-wire shape.
The docs site now ships with a pinned Server Action encryption key, so framework-internal action IDs (used by <Link> prefetch, form revalidation, etc.) survive a redeploy. Previously, every redeploy generated a new key and any open browser tab from a prior build started logging "Failed to find Server Action <hash>". This was a docs-site reliability fix, not a public-API change.
paymentMethod: open_bank_transfer + checkoutMode: foxpay_checkout (or omitted) is now accepted: the buyer lands on the Foxpay hosted page with the OBT tile preselected and can still switch to another enabled method. Country, account holder name, and IBAN are collected on the buyer page — merchant servers do not send senderName / senderIban / customerCountry for hosted-mode OBT. Direct-provider OBT is unchanged.
The docs site now ships with a refined visual language: surfaced design tokens, a compact sticky topbar, mobile drawer navigation, dedicated footer, right-rail TOC on long pages, and Shiki-highlighted code blocks with copy buttons. Top-level content panels stack vertically for predictable rhythm; layout bugs in the home step grid and public endpoint surface are fixed.
The /payment-methods/obt and /payment-methods/open-bank-transfer slugs were rendering the same flow as two separate nav entries. The OBT slug now redirects to /payment-methods/open-bank-transfer and the Payment Methods section adds /payment-methods/qr-pay covering the default hosted-checkout method (with the qr_pay / manual_transfer / bank_transfer / manual_pay / manual alias normalization).
New /guides/webhook-reference documents the field-level webhook contract: delivery headers, transaction.status_changed payload, status enum, signature verification, retry and timeout semantics, and the verification handshake. New /guides/reliability covers idempotency for payment initialization, polling, and webhook handling, including the duplicate-pending reuse rule and webhook deduplication via X-Foxpay-Delivery.
The /authentication page now ships the canonical Bearer header examples for initialization and polling, the panel flow for issuing and rotating API keys, the test vs live separation, key prefix conventions, and the precise authentication failure modes returned by /payments/initialize.
The documented custom REST contract is now live in the Foxpay application: hosted checkout remains the default, direct Calytics OBT can be requested with paymentMethod open_bank_transfer and checkoutMode direct_provider, and remittanceInfo is accepted for merchant-controlled SEPA remittance references.
The public docs now describe the default hosted Foxpay checkout mode, direct Calytics OBT sessions through paymentMethod open_bank_transfer with checkoutMode direct_provider, and the new remittanceInfo field for merchant-controlled SEPA remittance references.
Docs changes are not considered complete after local build or merge alone. Every material docs update must be deployed through the production workflow and verified live on docs.foxpay.it, including the published OpenAPI spec when the API reference changes.
The docs now state that custom API webhooks are merchant-hosted callbacks and are separate from the WooCommerce plugin webhook. The webhook guide also documents signature verification, delivery headers, and the verification handshake.
The main docs page now prioritizes the custom REST integration sequence, contract rules, public endpoint surface, and the distinction between custom REST and WooCommerce plugin flows.
The docs site now publishes favicon assets, page descriptions, OpenGraph and Twitter link-preview metadata, and a Foxpay Docs preview image for shared links.
The quickstart and payment-flow guide now distinguish successful payment initialization from payment completion and document the current generated SEPA remittance reference behavior.
The webhook guide now explains where custom webhook URLs are configured, which signature header custom deliveries use, and why the custom endpoint remains separate from WooCommerce plugin callbacks.
The Foxpay docs service now provides a dedicated public portal for custom REST integrations, operational guidance, and the OpenAPI reference.
The public reference is now generated from the canonical route-annotation export and published as the source of truth for public routes.
Quickstart, payment-flow, testing, authentication, samples, and support guidance now align around the custom REST integration path.