# PayOptimum / PayFlow — Complete Developer and AI Builder Reference Canonical manual: https://payoptimum.org/developer-docs Concise AI index: https://payoptimum.org/llms.txt Machine manifest: https://payoptimum.org/.well-known/payoptimum-ai-builder.json Go-live handbook: https://payoptimum.org/developer-docs#going-live-with-payflow > SOURCE TRUST: UI routes and code patterns are not evidence of LIVE payment operation. Some examples are illustrative or source-reported. Native PayFlow and Stripe Adapter V4 are separate products. Do not guess API endpoints or activate LIVE from examples. # TABLE OF CONTENTS 01. GETTING STARTED (13 chapters) - Quick Start : https://payoptimum.org/developer-docs#catalog-quick-start - Builder Install : https://payoptimum.org/developer-docs#catalog-builder-install - Dashboard Signature v5 · Verification : https://payoptimum.org/developer-docs#catalog-dashboard-signature-v5-verification - Checkout LIVE : https://payoptimum.org/developer-docs#catalog-checkout-live - Complete Integration Guide : https://payoptimum.org/developer-docs#catalog-complete-integration-guide - API Reference : https://payoptimum.org/developer-docs#catalog-api-reference - Exhaustive Error Catalog : https://payoptimum.org/developer-docs#catalog-exhaustive-error-catalog - Sandbox Testing Scenarios : https://payoptimum.org/developer-docs#catalog-sandbox-testing-scenarios - PayFlow API Reference : https://payoptimum.org/developer-docs#catalog-payflow-api-reference - PaymentHub API Checkout Flow : https://payoptimum.org/developer-docs#catalog-paymenthub-api-checkout-flow - Billing Service API : https://payoptimum.org/developer-docs#catalog-billing-service-api - Angel 2.0 / PaymentHub : https://payoptimum.org/developer-docs#catalog-angel-paymenthub - Authentication : https://payoptimum.org/developer-docs#catalog-authentication 02. CORE FEATURES (7 chapters) - Payment API Integration : https://payoptimum.org/developer-docs#catalog-payment-api-integration - Webhooks : https://payoptimum.org/developer-docs#catalog-webhooks - Subscriptions : https://payoptimum.org/developer-docs#catalog-subscriptions - Global Payment Methods : https://payoptimum.org/developer-docs#catalog-global-payment-methods - Xero Partner 2.0 Activation : https://payoptimum.org/developer-docs#catalog-xero-partner-activation - Payments Management API : https://payoptimum.org/developer-docs#catalog-payments-management-api - Advanced and Reference Guide : https://payoptimum.org/developer-docs#catalog-advanced-reference-guide 03. ADVANCED FEATURES (4 chapters) - AI Payment Processing : https://payoptimum.org/developer-docs#catalog-ai-payment-processing - Marketplace Integration : https://payoptimum.org/developer-docs#catalog-marketplace-integration - Mobile Integration : https://payoptimum.org/developer-docs#catalog-mobile-integration - Performance Optimization : https://payoptimum.org/developer-docs#catalog-performance-optimization 04. SECURITY & COMPLIANCE (2 chapters) - PCI DSS Compliance : https://payoptimum.org/developer-docs#catalog-pci-dss-compliance - Security Best Practices : https://payoptimum.org/developer-docs#catalog-security-best-practices 05. DEVELOPMENT (6 chapters) - Testing Guide : https://payoptimum.org/developer-docs#catalog-testing-guide - Error Handling : https://payoptimum.org/developer-docs#catalog-error-handling - Developer Tools : https://payoptimum.org/developer-docs#catalog-developer-tools - Node.js SDK : https://payoptimum.org/developer-docs#catalog-nodejs-sdk - Python SDK : https://payoptimum.org/developer-docs#catalog-python-sdk - Migration Guide : https://payoptimum.org/developer-docs#catalog-migration-guide 06. PRODUCTION (3 chapters) - Production Deployment : https://payoptimum.org/developer-docs#catalog-production-deployment - Monitoring & Analytics : https://payoptimum.org/developer-docs#catalog-monitoring-analytics - Documentation Routing : https://payoptimum.org/developer-docs#catalog-documentation-routing 07. QUICK LINKS (4 chapters) - Dashboard : https://payoptimum.org/developer-docs#catalog-dashboard-link - Support Center : https://payoptimum.org/developer-docs#catalog-support-center - System Status : https://payoptimum.org/developer-docs#catalog-system-status - Developer Tools : https://payoptimum.org/developer-docs#catalog-developer-tools-links 08. AI Builder Handbook (6 chapters) - AI site builders — integration start here : https://payoptimum.org/developer-docs#ai-builder-entry - AI discovery manifest — meaning and trust boundaries : https://payoptimum.org/developer-docs#ai-builder-manifest - AI website builder playbook — end-to-end workflow : https://payoptimum.org/developer-docs#ai-builder-implementation - Copyable master prompt for AI site builders : https://payoptimum.org/developer-docs#ai-prompt-template - Builder recipe — Base44 / managed app platforms : https://payoptimum.org/developer-docs#ai-builder-base44 - AI-generated integration acceptance criteria (must pass) : https://payoptimum.org/developer-docs#ai-builder-acceptance 09. Products and Commercial Operations (15 chapters) - Start here — PayOptimum products and roles : https://payoptimum.org/developer-docs#start-here - Verified deployment vs. unverified operation : https://payoptimum.org/developer-docs#deployment-status - Native PayFlow vs. Stripe Adapter V4 — strict separation : https://payoptimum.org/developer-docs#products-boundary - Stripe V4 Full Pipeline Studio — original HTML and five screens : https://payoptimum.org/developer-docs#stripe-v4-source - Stripe Adapter V4 merchant integration workflow : https://payoptimum.org/developer-docs#stripe-v4-backend - Aurora Classic and Aurora Pro V7 — installation and limitations : https://payoptimum.org/developer-docs#aurora-builders - Product subscription pricing, confirmation and billing : https://payoptimum.org/developer-docs#subscriptions-billing - PayFlow Sandbox, PaymentHub LIVE and client activation : https://payoptimum.org/developer-docs#sandbox-live-paymenthub - Merchant isolation and identity — enforcement contract : https://payoptimum.org/developer-docs#merchant-isolation - Invoices, receipts, retries and accounting boundaries : https://payoptimum.org/developer-docs#billing-invoices - Install PayFlow on merchant sites — server-first handoff : https://payoptimum.org/developer-docs#integration-flow - Dashboard operations — modules and access : https://payoptimum.org/developer-docs#dashboard-operations - Troubleshooting — empty pages, routing, sessions and 503 : https://payoptimum.org/developer-docs#troubleshooting-new - Release checklist, rollback and acceptance tests : https://payoptimum.org/developer-docs#release-no-go - FAQ — concise answers for merchants : https://payoptimum.org/developer-docs#faq-new 10. Engineering and Security (12 chapters) - API reference policy — how to identify a real endpoint : https://payoptimum.org/developer-docs#api-contract - TypeScript SDK starter — resilient, server-only client : https://payoptimum.org/developer-docs#typescript-sdk - Secure merchant checkout implementation — reference blueprint : https://payoptimum.org/developer-docs#backend-checkout-example - Webhooks — verification, replay protection and delivery semantics : https://payoptimum.org/developer-docs#webhook-deep-dive - Recurring billing — activation, renewals, cancellation and entitlement : https://payoptimum.org/developer-docs#subscription-server - Environment and secrets matrix — no cross-wiring : https://payoptimum.org/developer-docs#environment-matrix - Observability — logs, correlation, dashboards and incidents : https://payoptimum.org/developer-docs#observability - Local development and reproducible staging : https://payoptimum.org/developer-docs#local-dev - Merchant migration, onboarding and version upgrades : https://payoptimum.org/developer-docs#client-migration - Frontend integration — React, vanilla JS and safe redirects : https://payoptimum.org/developer-docs#frontend-integration - Privacy, compliance and accessibility checklist : https://payoptimum.org/developer-docs#privacy-legal - Developer FAQ — edge cases and implementation decisions : https://payoptimum.org/developer-docs#faq-integration 11. Going Live with PayFlow (9 chapters) - Going Live with PayFlow : https://payoptimum.org/developer-docs#going-live-with-payflow - Overview : https://payoptimum.org/developer-docs#going-live-overview - Pre-Deployment Checklist : https://payoptimum.org/developer-docs#pre-deployment-checklist - Environment Setup : https://payoptimum.org/developer-docs#environment-setup - Security Configuration : https://payoptimum.org/developer-docs#security-configuration - Performance Optimization : https://payoptimum.org/developer-docs#performance-optimization - Monitoring Setup : https://payoptimum.org/developer-docs#monitoring-setup - Deployment Strategies : https://payoptimum.org/developer-docs#deployment-strategies - Post-Deployment : https://payoptimum.org/developer-docs#post-deployment 12. API Reference and Source Notes (19 chapters) - Overview : https://payoptimum.org/developer-docs#overview - Environment & configuration : https://payoptimum.org/developer-docs#configuration - Health & readiness : https://payoptimum.org/developer-docs#health - Checkout integration : https://payoptimum.org/developer-docs#checkout - Payment status : https://payoptimum.org/developer-docs#payment-status - Webhooks & signatures : https://payoptimum.org/developer-docs#webhooks - Seven-stage payment pipeline : https://payoptimum.org/developer-docs#pipeline - Sandbox & production : https://payoptimum.org/developer-docs#sandbox - Angel 2.0 CFO — finance and reconciliation node : https://payoptimum.org/developer-docs#angel-cfo - Stripe Adapter V4 — test-only API contract (Angel 2.0 review) : https://payoptimum.org/developer-docs#stripe-adapter-verified - Angel 2.0 CFO — verified scope and publication constraints : https://payoptimum.org/developer-docs#angel-cfo-findings - Xero Partner 2.0 — integration status and accounting scope : https://payoptimum.org/developer-docs#xero-partner-review - Delegated merchant analytics — observed assertion contract : https://payoptimum.org/developer-docs#delegated-analytics-contract - Accounting controls — deployment and documentation prerequisites : https://payoptimum.org/developer-docs#accounting-control-readiness - AI Builder installation — original integration contract (19 October 2026) : https://payoptimum.org/developer-docs#builder-install-source-contract - Seven-stage checkout, card fields and verification — source requirements : https://payoptimum.org/developer-docs#builder-install-secure-state - Builder source files, deployment boundaries and release caveats : https://payoptimum.org/developer-docs#builder-deployment-inventory - Published product navigation — Stripe Adapter V4 and Aurora V7 : https://payoptimum.org/developer-docs#published-product-navigation - PayFlow documentation directory : https://payoptimum.org/developer-docs#integration-resources # VOLUME 01 — GETTING STARTED ## Quick Start Link: https://payoptimum.org/developer-docs#catalog-quick-start The shortest supported route from product selection to a safe first test. A published builder preview is not evidence of a processor-ready checkout. ### First integration in ten steps ~~~~text 1. Choose native PayFlow Aurora OR Stripe Adapter V4. 2. Open /docs and the AI-builder manifest. 3. Confirm authenticated merchant identity and account ownership. 4. Confirm trusted product, price and currency from server records. 5. Obtain the actual deployed service contract; do not invent endpoints. 6. Keep credentials and payment tokens on the backend. 7. Design the checkout, then connect only approved hosted payment fields. 8. Test an idempotent TEST transaction and signed status/webhook handling. 9. Verify 401/403, duplicate/replay, timeout and merchant A/B isolation. 10. Schedule separate LIVE review only after all gates pass. Known health route: GET https://api.payflow.buzz/v1/health Health is not proof of LIVE settlement. ~~~~ ## Builder Install Link: https://payoptimum.org/developer-docs#catalog-builder-install Integrate Aurora or Stripe V4 into a website builder via authenticated, server-first installation. The legacy installation manifest and named asset files are source-reported and must be checked against their actual deployed URL and hashes before production use. ### Installer requirements ~~~~text AI builders: read https://payoptimum.org/llms.txt first. 1. Identify the selected product and version, never substitute another. 2. Authenticate the merchant server-side before issuing configuration. 3. Download only approved immutable installer assets. 4. Verify expected hashes, supported versions and signing requirements. 5. Bind each merchant-specific checkout to its own trusted orders. 6. Validate hosted fields / tokenization and sandbox merchant isolation. 7. Test callbacks, failure states, double clicks and rollback. 8. Provide a deployment report and clear operational status. A static HTML checkout alone does not process real payments. Earlier guides mention client-checkout.html, merchant-bridge.mjs and a .well-known/payflow-installation.json manifest; availability is unverified. ~~~~ ## Dashboard Signature v5 · Verification Link: https://payoptimum.org/developer-docs#catalog-dashboard-signature-v5-verification Signature v5 is a historical PayFlow Worker routing/security contract, separate from the PayOptimum Base44 merchant dashboard. The previous health and delegated analytics routes were reported in earlier deployments; do not presume they still route through the same Worker after later domain redirects. ### Historical v5 checks — verify before relying on them ~~~~bash # Architecture inventory, NOT guaranteed current routing. curl -i 'https://payflow.buzz/dashboard/_v5-health' curl -i 'https://payflow.buzz/dashboard/api/analytics/live' # Expected in the historical v5 route design: # health 200 with X-PayFlow-Dashboard: signature-v5-extended # analytics without signed-in session: 401 PAYFLOW_SESSION_REQUIRED # Compare host, Cloudflare route, deployment signature and auth layer. # A 302 to PayOptimum is not evidence the old v5 Worker handled the call. ~~~~ ### Delegated analytics security gates ~~~~text [ ] Verify Base44 user to PayFlow merchant mapping on server. [ ] Validate iss, aud, sub, scope, iat, exp and anti-replay jti. [ ] Do not accept merchant_client or userId from browser query as identity. [ ] Verify Worker → proxy internal signature and SQL tenant filters. [ ] Test two merchants against distinct transactions. [ ] Rollback tested; no LIVE payments enabled by analytics. ~~~~ ## Checkout LIVE Link: https://payoptimum.org/developer-docs#catalog-checkout-live Production checkout must be enabled only after independent processor and client authorization. PaymentHub is designated for PayFlow LIVE processing, not PayFlow Sandbox. An explicit LIVE_CLIENT_ENABLED check for the identified client is necessary but never sufficient. ### LIVE checkout gates ~~~~text [ ] Server-verified user and merchant (no 'default'). [ ] Client-specific LIVE_CLIENT_ENABLED true in trusted backend. [ ] Approved processor/account and exact published endpoint contract. [ ] Authorized product, amount, currency, tax and order. [ ] PCI/hosted-field provider and permitted data collection confirmed. [ ] Signed callback, anti-replay and idempotency verified. [ ] Two-merchant data-isolation and wrong-merchant rejections pass. [ ] Refund/cancellation, failure recovery, audit logs and kill switch. [ ] Explicit production operator approval and reconciliation plan. Any unchecked critical gate => NO-GO. Do not infer LIVE from a button. ~~~~ ## Complete Integration Guide Link: https://payoptimum.org/developer-docs#catalog-complete-integration-guide Full merchant-facing integration sequence linking a visual builder, backend order/merchant mapping, an authorized processor, webhooks and a verifiable paid state. Native PayFlow and Stripe Adapter V4 always remain distinct. ### Reference deployment pipeline ~~~~text Merchant chooses product → authenticated account → server-resolved merchant → server order lookup and minor-unit amount → stable idempotency key → VERIFIED provider checkout contract (server-side only) → approved hosted checkout handoff → signed event / provider status → merchant-scoped ledger reconciliation → invoicing (verified state only) → reporting, alerts, cancellation and dispute workflows. For native Aurora: use PayFlow authorized native processor contract. For Stripe Adapter V4: merchant's own Stripe handles their customer charge. For PayFlow's 39 EUR/month V4 add-on: separate PayFlow subscription sale. Never combine processor credentials or customer-payment ledgers. ~~~~ ## API Reference Link: https://payoptimum.org/developer-docs#catalog-api-reference API references below distinguish confirmed public routes from backend contracts reported by the app. Full LIVE schema, rate limits, authentication and signing must be checked against the deployed source before generating clients. ### Known reference surface ~~~~text GET https://api.payflow.buzz/v1/health Health signal only; does not prove LIVE card configuration. PayOptimum Base44 function: productSubscriptionIntent Authenticated request with action=request, fixed product_id and explicit confirm_monthly_subscription=true; result pending_billing (no charge). Stripe staging paths reported by Angel 2.0: GET /v1/health POST /v1/connect/oauth/start GET /v1/connect/status POST /v1/connect/disconnect POST /v1/checkout/sessions GET /v1/payments GET /v1/transactions Report status: source-reported TEST contract; verify deployment and signatures. No complete native payment OpenAPI contract has been validated here. ~~~~ ## Exhaustive Error Catalog Link: https://payoptimum.org/developer-docs#catalog-exhaustive-error-catalog Unified developer error-handling index for the known UI/backend states and ordinary HTTP failures. This is an exhaustive *application-handling taxonomy*, not an assertion that the entire external PayFlow processor error catalogue has been recovered. Provider-specific codes must be reconciled with the deployed API. ### Error states and safe action ~~~~text HTTP 400 / bad_request Invalid fields; correct schema, do not retry unchanged. HTTP 401 / unauthorized Sign-in required; do not create records. HTTP 403 / forbidden Tenant/role/environment blocked; fail closed. HTTP 404 / not_found Missing resource or hidden tenant-owned record. HTTP 409 / conflict Duplicate idempotency/state; fetch canonical status. HTTP 429 / rate_limited Retry only as provider contract permits, with backoff. HTTP 5xx / unavailable Log request ID; do not imply a successful payment. pending_billing Subscription requested, not charged. not_activated Backend/test credentials or gates missing. not_connected Merchant Stripe connection not active. invalid_state OAuth/state mismatch or expired single-use token. live_blocked LIVE request refused; never bypass via TEST secret. contract_mismatch Adapter/worker schema mismatch; halt release. webhook_invalid Signature/replay failed; reject with audit record. merchant_mismatch Deny cross-tenant access, do not retry as default. PAYFLOW_SESSION_REQUIRED Historical delegated Worker needs authenticated session. LIVE_PAYMENTS_DISABLED_IN_SANDBOX Error from a tested billing gateway, NOT proof that PaymentHub LIVE is a sandbox processor. Use exact code and response from the deployed provider as the final authority. ~~~~ ### Client-side error mapping pattern ~~~~typescript function classifyFailure(status: number) { if (status === 401) return 'SIGN_IN_REQUIRED'; if (status === 403) return 'ACCESS_DENIED'; if (status === 409) return 'VERIFY_EXISTING_OPERATION'; if (status === 429 || status >= 500) return 'RETRY_STATUS_LOOKUP_SAFELY'; return 'VALIDATE_REQUEST'; } // Never auto-retry a financial POST with a NEW idempotency key. ~~~~ ## Sandbox Testing Scenarios Link: https://payoptimum.org/developer-docs#catalog-sandbox-testing-scenarios Payment tests should cover successful simulated paths and negative failures without touching real money. A test session, mock success_url or screenshot never proves that a LIVE transaction settled. ### Sandbox test matrix ~~~~text S01 Valid merchant, order and expected minor-unit currency. S02 Unknown merchant, merchant B data, forged merchant ID → denied. S03 Invalid amount, currency, product ID → 400, no side effect. S04 Duplicate submit (same idempotency key) → at most one checkout. S05 Success redirect without webhook → order remains pending. S06 Valid signed webhook + verified provider status → update TEST only. S07 Invalid signature or stale timestamp → rejected. S08 Replay / duplicate event → idempotent acknowledgement. S09 Out-of-order failed/paid events → no invalid status regression. S10 Processor timeout/disconnect → safe pending, no false paid. S11 Refund, cancel, async method and settlement mismatch. S12 Merchant A and B same email → strict independent ledger. S13 Disabled LIVE eligibility → LIVE request refused, even if UI toggled. S14 Failed webhook destination/retry/dead-letter test and audit trace. Record the actual endpoint, revision, merchant and environment for each. ~~~~ ## PayFlow API Reference Link: https://payoptimum.org/developer-docs#catalog-payflow-api-reference PayFlow's native API is distinct from Stripe Adapter and Base44. The known public health route can be inspected safely, but exact payment API methods, field names, signing contract and idempotency behavior are deliberately not invented. ### Public PayFlow API health check ~~~~bash curl --fail-with-body --silent --show-error \ -H 'Accept: application/json' \ 'https://api.payflow.buzz/v1/health' # Verify readiness flags separately: # payment_processing, database_ready, checkout_route_available, # card_processing, card_live_enabled, processor readiness. # Health HTTP 200 does NOT establish LIVE payment eligibility. ~~~~ ### Before documenting a payment endpoint ~~~~text Require deployed endpoint (host/method/path), request/response JSON schema, authenticated server secrets, merchant derivation, error identifiers, webhook signature, idempotency, pagination, rate limits and version. Record the source revision, last test and safe example response. Do not publish inferred paths under /v1/checkout or /v1/payments. ~~~~ ## PaymentHub API Checkout Flow Link: https://payoptimum.org/developer-docs#catalog-paymenthub-api-checkout-flow PaymentHub is reserved for PayFlow-controlled LIVE production processing (payflowbuzz-canada in project configuration). This section describes the approved operational sequence, not a verified public PaymentHub API endpoint. Never expose PaymentHub directly to browsers or to a merchant's independent Stripe account. ### LIVE PaymentHub handoff sequence (architecture) ~~~~text Verified PayFlow merchant identity + order record → check exact client's LIVE_CLIENT_ENABLED server-side → confirm approved PayFlow LIVE processor access → backend creates an authorized, idempotent payment request → processor returns trusted handoff identifier / session → customer completes provider-hosted interaction → PayFlow verifies signed provider event and authoritative status → merchant-scoped ledger update and reconciliation → invoice/receipt only after verified charge → monitoring, retries, refunds and alerts per accepted contract Absent processor API specification, merchant authorization or LIVE evidence: BLOCK the handoff. Do not call a guessed PaymentHub endpoint. ~~~~ ## Billing Service API Link: https://payoptimum.org/developer-docs#catalog-billing-service-api PayFlow billing includes subscriptions and invoices; the PayOptimum offer flow currently stores an authenticated pending_billing intent. This is not yet a live recurring payment endpoint, and a pending intent is not a paid invoice. ### Current PayOptimum subscription function ~~~~javascript // Run inside authenticated Base44 merchant application. const response = await base44.functions.invoke('productSubscriptionIntent', { action: 'request', product_id: 'stripe-adapter-v4', confirm_monthly_subscription: true }); if (response.data?.state === 'pending_billing') { showMessage('Subscription requested; no payment collected yet.'); } // Fixed EUR monthly catalog: Stripe V4 39, Classic 29, // Aurora V7 Starter 19, Pro 49, Enterprise 99. // Do not issue an invoice paid or active entitlement from this response. ~~~~ ### API extension requirements (not deployed) ~~~~text Before real PayFlow billing: - approve recurring subscription contract, tax and cancellation terms; - create provider checkout using server-set immutable price; - verify client and processor LIVE authorization, not browser flags; - consume provider-signed payment confirmation, deduplicate and reconcile; - issue invoice/receipt only for verified ledger event; - schedule renewals, failure retries and period-end cancellations. Exact LIVE checkout endpoint is not verified in this app. ~~~~ ## Angel 2.0 / PaymentHub Link: https://payoptimum.org/developer-docs#catalog-angel-paymenthub Angel 2.0 CFO is an advisory/reconciliation layer, not the processor of funds. The PayFlow LIVE processor remains under authorized server-side PaymentHub controls. Never grant the assistant autonomous charge/refund or bank-disbursement permissions merely by enabling the UI. ### Advisory finance safeguards ~~~~text Angel 2.0 may analyze authorized merchant-scoped payments and suggest invoice matching, settlement exceptions or tax categorization. It must NEVER: - receive raw card data, secret keys or another merchant's financial records; - authorize PaymentHub LIVE for a merchant; - mark transfer settled without verified processor/bank evidence; - approve refunds, bank movements or issue paid receipts by inference. Where manual UBS approval is required, an authorized human signs off. All changes need merchant-scoped audit references and explicit permissions. ~~~~ ## Authentication Link: https://payoptimum.org/developer-docs#catalog-authentication Public docs and product previews require no merchant session. Dashboard and backend functions require a verified PayOptimum user; separate authorization is needed for each PayFlow merchant and the related Stripe account. Never infer merchant ID or entitlements from a browser form. ### Authentication and authorization contract ~~~~text Public: /docs, /developer-docs, /stripe/v4 (visual preview only). Authenticated: /dashboard, /product-billing, /stripe-adapter/overview, /stripe-adapter/connection. Backend productSubscriptionIntent: unauthenticated POST → HTTP 401. Merchant ID comes from server-side identity mapping (NOT browser input). Stripe OAuth state is short-lived, signed/single-use and tied to merchant. LIVE_CLIENT_ENABLED is read server-side for specific authorized client. Cross-merchant sessions, expired tokens, missing roles → fail closed. Allowlist returnTo same-origin paths to prevent open redirects. ~~~~ # VOLUME 02 — CORE FEATURES ## Payment API Integration Link: https://payoptimum.org/developer-docs#catalog-payment-api-integration Connect merchant checkout to an authorized payment processor through a server-owned order reference. Use separate native and Stripe pipelines, provider-specific status and immutable idempotency references. ### Safe integration contract ~~~~text Browser → POST /your-site/api/checkout/start with order ID only. Merchant site backend: auth() → resolveMerchant(user) → loadOrder(orderId, merchant) → validate stored amount/currency/version → idempotency key → call VERIFIED provider checkout endpoint → return approved session URL. Signed provider callback → verify provider state → update merchant order once. Paths under /your-site are YOUR implementation, not published PayFlow APIs. Never accept 'paid', amount_minor, merchant_id or live_enabled from browser. ~~~~ ## Webhooks Link: https://payoptimum.org/developer-docs#catalog-webhooks Both PayFlow native and merchant Stripe transactions need signed event processing, atomic replay prevention, ordered/idempotent ledger updates and observability. Signing mechanisms differ by provider and cannot be reused interchangeably. ### Webhook verification runbook ~~~~text 1. Receive raw unmodified bytes; enforce size and type limits. 2. Verify the actual provider signature, timestamp and account. 3. Map the event to authenticated merchant and trusted order. 4. Insert unique (provider, merchant, event_id) in durable storage. 5. Verify authoritative payment status when the contract requires it. 6. Apply at most one allowed ledger transition in a transaction. 7. Acknowledge duplicates safely; use backoff for transient failures. 8. Retain masked audit logs, retries and dead-letter queue. Negative-test invalid signature, stale time, wrong merchant, replay, out-of-order events and network failure. Frontend redirects prove nothing. ~~~~ ## Subscriptions Link: https://payoptimum.org/developer-docs#catalog-subscriptions Distinguish a merchant's customer subscriptions from PayFlow's own product subscriptions. PayFlow's 39 EUR/month Stripe V4 charge is billed separately from the merchant's Stripe subscriptions. PayOptimum's Subscribe button currently records a pending_billing request only. ### Subscription lifecycle ~~~~text offered → explicitly confirmed → pending_billing → authorized PayFlow LIVE checkout (not verified in PayOptimum) → signed processor event + verified payment status → active entitlement + invoice/receipt, if appropriate → next renewal / past_due / cancel_at_period_end / canceled Current PayOptimum backend stops at pending_billing. For the merchant's own Stripe subscribers, event statuses belong to that merchant's own Stripe account, never to PayFlow native ledger. No invoice may be marked paid before authoritative evidence. ~~~~ ## Global Payment Methods Link: https://payoptimum.org/developer-docs#catalog-global-payment-methods Availability of currencies or payment methods in a UI selector is not proof a merchant can collect them in LIVE. Processor agreements, region, merchant KYC, settlement account, 3DS/SCA and method-specific webhook status must be verified. ### Payment method readiness matrix ~~~~text Currency UI: CHF, EUR, USD and GBP appear in preview/builder contexts. Actual processing: verify enabled provider capability per merchant/method. Cards: approved hosted fields and 3DS/SCA where mandated. Bank transfer: pending until verified bank/provider evidence; human approval where policy requires. Alternative / local methods: add only when processor contract confirms region, currency, refund, async settlement and webhook semantics. Do not promise worldwide card acceptance because a currency switch exists. ~~~~ ## Xero Partner 2.0 Activation Link: https://payoptimum.org/developer-docs#catalog-xero-partner-activation Xero Partner 2.0 represents the accounting connection and review workflow. The previous workspace review did not establish active Xero OAuth, invoice creation or journal synchronization; activation requires verified tenant-specific OAuth and accounting data mapping. ### Activation checks ~~~~text [ ] Verify Xero organization/tenant and granted scopes. [ ] Complete server-side OAuth callback and token rotation. [ ] Map PayFlow legal seller, tax rates, currencies and chart of accounts. [ ] Create TEST invoice/contact and verify response and journal mapping. [ ] Prove merchant-specific tenant isolation and accounting audit trail. [ ] Reconcile processor payment to invoice once, then test credit notes. [ ] Test token expiry, disconnection, failed sync and retry. [ ] Obtain accounting-owner approval before production data mutation. PayOptimum /xero-partner UI presence alone does not prove OAuth active. ~~~~ ## Payments Management API Link: https://payoptimum.org/developer-docs#catalog-payments-management-api Define payment listing, status, refunds and disputes using the verified provider/backend contract. Do not invent refund endpoints or allow a merchant's browser to set final statuses. Provide server-scoped filters and cursor-based pagination. ### Management API acceptance contract ~~~~text List payments: authenticated merchant, owner filter, cursor, limit and sort. Get payment: ID resolves to merchant-owned row only (403/404 otherwise). Refund: explicit authorized role, remaining refundable amount, reason, processor confirmation and idempotency; never an AI auto-approval. Dispute: provider evidence, deadline, event reference and audit trail. Payment status: verify with authoritative provider and signed events. Never expose full card numbers, credential secrets or other tenant IDs. Exact deployed paths and schemas must be verified before building an SDK. ~~~~ ## Advanced and Reference Guide Link: https://payoptimum.org/developer-docs#catalog-advanced-reference-guide Use the larger engineering volumes for server-side patterns, cryptographic webhook verification, merchant isolation, financial reconciliation, operational monitoring and rollback. The source-reported sections are preserved and labeled by evidence level. ### Deep reference map ~~~~text /developer-docs#api-contract Endpoint verification policy /developer-docs#typescript-sdk Server-side TypeScript client pattern /developer-docs#webhook-deep-dive Signing, replay and event handling /developer-docs#subscription-server Subscription state machine /developer-docs#merchant-isolation Two-merchant authorization testing /developer-docs#environment-matrix TEST vs LIVE separation /developer-docs#release-no-go Readiness acceptance /developer-docs#going-live-with-payflow Complete production sequence /llms-full.txt Full machine-readable reference ~~~~ # VOLUME 03 — ADVANCED FEATURES ## AI Payment Processing Link: https://payoptimum.org/developer-docs#catalog-ai-payment-processing AI assistants may design checkout UI, classify exceptions and recommend accounting matches, but they must not be considered payment processors or bypass server-side authorizations. Live actions require deterministic backend policy and independent provider evidence. ### Approved AI responsibility boundaries ~~~~text AI builder: generates preview UI, code, tests and integration proposals. PayFlow backend: authenticates merchant, enforces amount, auth and LIVE policy. Provider: performs real authorization, capture, settlement and refund. Webhook/ledger: verifies signed evidence and persists state. Human/finance: approves sensitive transfers or overrides where required. No raw PAN/CVV, account tokens, keys or cross-merchant data in prompts. No automatic LIVE switch or processor call based on natural-language intent. Use structured allowlisted actions with explicit authorization and audit. ~~~~ ## Marketplace Integration Link: https://payoptimum.org/developer-docs#catalog-marketplace-integration Multi-merchant platforms require per-merchant onboarding, account ownership, transaction isolation, fee rules and independent provider authorization. A platform's role is not permission to move funds between sub-merchants without an approved processor contract. ### Marketplace onboarding design ~~~~text Platform user → authenticated merchant organization → approved merchant ID → scoped checkout configuration and per-merchant integration credentials → seller's own orders, clients, settlement rules, tax and refunds → segregated signed events and reporting If Stripe Adapter V4: connect each merchant's own Stripe account; do not merge it with PayFlow native settlement or PayFlow's subscription income. No default/shared merchant. Verify two tenants with independent records. Payout distribution / Connect functionality requires separate legal, processor and technical authorization. ~~~~ ## Mobile Integration Link: https://payoptimum.org/developer-docs#catalog-mobile-integration Mobile applications should use approved hosted checkout and universal/deep links with tamper-resistant server-side session references. Avoid embedding processor secrets in app bundles and never treat a successful return URL as payment confirmation. ### Mobile checkout checklist ~~~~text [ ] Authenticated customer and merchant mapping on backend. [ ] Server-issued short-lived checkout session or hosted handoff. [ ] HTTPS universal link / app link allowlists and safe cancellation URL. [ ] No raw card storage or provider secret in mobile binary or WebView. [ ] App can resume after interruption, timeout or backgrounding. [ ] Server rechecks authoritative payment state after return. [ ] Signed webhook and idempotency control final order state. [ ] TEST on iOS Safari, Android Chrome, failed network and app reopen. Actual mobile SDK support must be verified against published vendor specs. ~~~~ ## Performance Optimization Link: https://payoptimum.org/developer-docs#catalog-performance-optimization Optimize hosted checkouts without compromising security or financial correctness. Separate static asset caching from authenticated sessions and payment statuses; profile backend queues, webhook delivery and rate limits. ### Operational optimization checklist ~~~~text CDN cache only public assets with verified cache headers. Use Cache-Control: no-store for merchant-scoped payment status. Limit checkout payload; defer unrelated analytics and heavyweight widgets. Track LCP/CLS/INP, API latency p50/p95/p99 and provider timeouts. Deduplicate retries, allow backoff only with stable idempotency keys. Use indexed owner/merchant filters in D1/SQL and avoid N+1 scans. Load-test with TEST merchants; never generate test traffic in LIVE. Measure webhook queue latency, failures and reconciliation age. ~~~~ # VOLUME 04 — SECURITY & COMPLIANCE ## PCI DSS Compliance Link: https://payoptimum.org/developer-docs#catalog-pci-dss-compliance PCI scope depends on the actual payment collection architecture, not branding, marketing or the presence of a hosted checkout. Card details must be handled only by approved tokenization/hosted-field providers in a verified PCI model. ### PCI scope evidence checklist ~~~~text [ ] Identify who hosts card inputs and where PAN/CVV is transmitted. [ ] Verify payment provider attestations and applicable SAQ/PCI scope. [ ] No PAN/CVV in PayOptimum, custom HTML, logs or AI prompt content. [ ] Use approved iframe/hosted fields with expected origin/CSP. [ ] Restrict scripts and monitor page integrity. [ ] Confirm 3DS/SCA, token lifetime and secure redirect handling. [ ] Document incident response, scanning, access control and retention. A design prototype that draws card fields is NOT proof of PCI L1 compliance, certification or an authorized card-processing integration. ~~~~ ## Security Best Practices Link: https://payoptimum.org/developer-docs#catalog-security-best-practices Zero-trust merchant identity, server-only secrets and signed financial events are baseline requirements. Every integration must fail closed on missing identity, missing LIVE gate, stale signature or unverified processor state. ### Security release checklist ~~~~text [ ] Verify authenticated identity, RBAC, session expiry and CSRF safeguards. [ ] Resolve merchant IDs server-side; no default merchant. [ ] Tenant-scope every query, file and background job. [ ] Strict CORS/CSP/origin allowlist, secure cookies and HTTPS. [ ] Secrets in server vault with rotation; never put in client JS. [ ] Provider-specific webhook signature over raw bytes + replay store. [ ] Atomic idempotency for payments, refunds and subscriptions. [ ] Verify LIVE_CLIENT_ENABLED for each client server-side. [ ] Conduct two-merchant negative tests, audit and least privilege. [ ] Instrument incident alerts, kill switch and safe rollback. [ ] Review Swiss FADP/GDPR, retention and legal/payment contracts. ~~~~ # VOLUME 05 — DEVELOPMENT ## Testing Guide Link: https://payoptimum.org/developer-docs#catalog-testing-guide Use deterministic TEST accounts, per-merchant fixtures, signed webhook simulations and integration reports. Distinguish unit tests of UI state from successful provider-backed sandbox confirmations. ### Test pyramid for payment systems ~~~~text UNIT: amounts in minor units, fixed prices, state machine, formatting. CONTRACT: auth, schema, signing, idempotency, pagination and errors. INTEGRATION: trusted order -> provider TEST session -> signed webhook. ISOLATION: merchant A cannot fetch/modify merchant B, even same email. RESILIENCE: duplicate webhook, late event, retries, timeout, queue crash. BROWSER: mobile Safari, Chrome, accessible confirmation and cancellation. LIVE READINESS: signed processor confirmation, eligibility, rollback and audit. No TEST transaction, demo invoice or green banner proves LIVE availability. ~~~~ ## Error Handling Link: https://payoptimum.org/developer-docs#catalog-error-handling Errors must be explicit, recoverable where appropriate and financially safe. Never silently issue a new charge after a timeout; first inspect the previous idempotent operation and provider status. ### Error-handling flow ~~~~text 401: request authenticated login, preserve safe return path. 403: deny access; do not fallback to a shared merchant. 400: show validated, field-specific error; do not retry unchanged. 409: query existing idempotent operation, do not duplicate charge. 429: respect backoff or Retry-After if provider contract says so. 5xx/timeout: show pending/unknown; reconcile on server before retry. invalid signature: reject and alert; do not process event. LIVE blocked: block financial action until authorized environment verified. Display a request ID, never raw API keys, bank details or card data. ~~~~ ## Developer Tools Link: https://payoptimum.org/developer-docs#catalog-developer-tools The current toolchain includes PayOptimum's developer docs, the AI builder manifest and full-text export, along with PayFlow API health and hosted builder entry points. An HTML preview is a design tool, not a processor API or a verified SDK. ### Developer toolbox (verified/routed and known endpoints) ~~~~text Documentation: https://payoptimum.org/developer-docs Docs index: https://payoptimum.org/docs AI manifest: https://payoptimum.org/.well-known/payoptimum-ai-builder.json Concise AI docs: https://payoptimum.org/llms.txt Full docs: https://payoptimum.org/llms-full.txt AI quickstart: https://payoptimum.org/ai-builder-integration.txt Public Stripe V4 studio: https://payoptimum.org/stripe/v4 Merchant Stripe connection: https://payoptimum.org/stripe-adapter/connection Public API health: https://api.payflow.buzz/v1/health Obtain provider secrets and true API schemas through approved server configuration, never through these public documentation files. ~~~~ ## Node.js SDK Link: https://payoptimum.org/developer-docs#catalog-nodejs-sdk The code below is a reusable server-side Node.js SDK skeleton, NOT a published npm PayFlow SDK. Methods remain abstract until the actual PayFlow API contract and signer have been verified. Never bundle this module into frontend React/Vite code. ### Node.js server client skeleton ~~~~javascript export class PayFlowServer { constructor({baseUrl,authHeader}) { if (!baseUrl?.startsWith('https://') || !authHeader) { throw new Error('SERVER_CONFIG_REQUIRED'); } this.baseUrl=baseUrl; this.authHeader=authHeader; // supplied by approved secret store } async request(verifiedPath, {method='GET',body,idempotencyKey}={}) { if (!verifiedPath.startsWith('/') || verifiedPath.startsWith('//')) throw new Error('INVALID_VERIFIED_PATH'); const response=await fetch(new URL(verifiedPath,this.baseUrl), { method,signal:AbortSignal.timeout(10000), headers:{'Accept':'application/json','Content-Type':'application/json', 'Authorization':this.authHeader, ...(idempotencyKey?{'Idempotency-Key':idempotencyKey}:{})}, ...(body?{body:JSON.stringify(body)}:{}) }); const result=await response.json().catch(()=>({})); if(!response.ok) throw Object.assign(new Error('PROVIDER_REQUEST_FAILED'), {status:response.status,requestId:response.headers.get('x-request-id')}); return result; } } // For a real payment, replace sample auth with the VERIFIED service contract. // GET /v1/health is known; checkout paths must never be guessed. ~~~~ ## Python SDK Link: https://payoptimum.org/developer-docs#catalog-python-sdk A small, explicit Python backend client pattern. It is not an official released Python package or verified PayFlow processor SDK. Keep keys in server secrets; provide exact endpoint details and any provider signatures only after inspecting deployed specifications. ### Python server client pattern ~~~~python import os import requests class PayFlowServer: def __init__(self, base_url: str, secret: str): if not base_url.startswith('https://') or not secret: raise ValueError('SERVER_CONFIG_REQUIRED') self.base_url = base_url.rstrip('/') self.secret = secret def request(self, path: str, *, method='GET', payload=None, idempotency_key=None): if not path.startswith('/') or path.startswith('//'): raise ValueError('INVALID_VERIFIED_PATH') headers = {'Accept':'application/json', 'Authorization':f'Bearer {self.secret}'} if idempotency_key: headers['Idempotency-Key'] = idempotency_key response = requests.request( method, self.base_url + path, json=payload, headers=headers, timeout=10, allow_redirects=False) response.raise_for_status() return response.json() # Illustrative auth format only. Use contract-verified endpoints and signer. # Example safe health call (if contract allows anonymous): # requests.get('https://api.payflow.buzz/v1/health', timeout=10).json() ~~~~ ## Migration Guide Link: https://payoptimum.org/developer-docs#catalog-migration-guide Plan migrations with processor ownership, immutable order references and rollback. Never migrate Stripe Adapter merchant processing into native PayFlow, or vice versa, without explicit merchant and processor authorization. ### Safe migration steps ~~~~text 1. Inventory existing URLs, processor, merchants, paid status and webhooks. 2. Confirm choice of native Aurora vs independent Stripe Adapter V4. 3. Export only authorized merchant-owned metadata and order references. 4. Snapshot frontend version, SQL/D1 schema, routes and binding names. 5. Develop server integration from true deployed contract; stage first. 6. Run A/B isolation, webhook duplicate, refund and rollback tests. 7. Do a controlled cutover for eligible merchants, monitor provider state. 8. Reconcile old and new periods without double-charging or losing history. 9. Keep old invoices/receipts immutable and preserve audit evidence. No implied account migration, LIVE switch or vault/key copying. ~~~~ # VOLUME 06 — PRODUCTION ## Production Deployment Link: https://payoptimum.org/developer-docs#catalog-production-deployment Deployment readiness is a security and financial release gate, not simply an HTTP 200 response or successful build. Use the dedicated Going Live runbook, and verify PaymentHub LIVE and client-specific LIVE eligibility before any real processing. ### Production rollout summary ~~~~text Build and test → immutable release → route and secret inventory → TEST payment and webhook validation → two-merchant isolation → processor contract verification → operator approval → LIVE_CLIENT_ENABLED (specific client, trusted server) → canary release → signed verified payment status → monitor and reconcile. Go-live handbook: https://payoptimum.org/developer-docs#going-live-with-payflow Source-provided eight headings are reproduced in that handbook. If any financial control is unverified, keep NO-GO. ~~~~ ## Monitoring & Analytics Link: https://payoptimum.org/developer-docs#catalog-monitoring-analytics Monitor requests, merchant-level payment outcomes, provider health, webhook delivery, queue aging and audit changes. The Base44 dashboard may contain workspace entity data; it must not be equated to verified real-time PayFlow ledger data until delegated analytics integration and tenant isolation pass tests. ### Production monitoring signals ~~~~text latency_p95, error_4xx/5xx, merchant_auth_rejects payment_created/pending/confirmed/refunded/failed (by verified environment) webhook_invalid_signature, replay_rejected, retry_queue_age idempotency_conflict, provider_connection_status, settlement_mismatch LIVE_CLIENT_ENABLED changes, unexpected_live_request tenant_access_denied, SQL filtering violations, data reconciliation_age release_id, rollback_id, incident alert and redacted trace IDs Never send secrets, card data, other tenants' identities or raw bank details to a public analytics product or logs. ~~~~ ## Documentation Routing Link: https://payoptimum.org/developer-docs#catalog-documentation-routing Documentation lives on payoptimum.org and should stay publicly readable without merchant login. Maintain stable canonical URLs, shareable chapter anchors and simple AI discovery endpoints, without redirect loops from legacy payflow.buzz routes. ### Canonical route inventory and acceptance ~~~~text https://payoptimum.org/docs Public docs homepage https://payoptimum.org/developer-docs Full chapter manual https://payoptimum.org/llms.txt Concise AI index https://payoptimum.org/llms-full.txt Complete machine text https://payoptimum.org/ai-builder-integration.txt AI quickstart https://payoptimum.org/.well-known/payoptimum-ai-builder.json Machine-readable manifest Every canonical URL should respond 200 with correct content type. Docs must not depend on merchant-session auth settings. Maintain correct SEO metadata, social OG/Twitter tags, and same-origin section links. Retest Chrome/Safari/mobile and external shares. Do not map two different products onto the same conflicting route. ~~~~ # VOLUME 07 — QUICK LINKS ## Dashboard Link: https://payoptimum.org/developer-docs#catalog-dashboard-link The authenticated PayOptimum merchant dashboard is the entry point for clients, subscriptions, reports and integrations. A signed-in merchant should see only records authorized for their merchant context. ### Dashboard entry ~~~~text https://payoptimum.org/dashboard Requires merchant sign-in. Stripe Adapter connection: https://payoptimum.org/stripe-adapter/connection Stripe V4 visual studio inside dashboard: https://payoptimum.org/dashboard/stripe/v4 Aurora Classic: https://payoptimum.org/dashboard/aurora/classic Aurora Pro: https://payoptimum.org/dashboard/aurora/pro Do not expose merchant data through public docs. ~~~~ ## Support Center Link: https://payoptimum.org/developer-docs#catalog-support-center PayOptimum support is available inside the authenticated merchant workspace. Include environment, route, request ID and non-secret diagnostic evidence when requesting help. ### Support routing and safe ticket fields ~~~~text https://payoptimum.org/support (merchant sign-in required) Include: product, TEST/LIVE, timestamp, browser, route and request ID. Redact: keys, authorization tokens, full card/bank data and third-party merchant information. Never paste secret values into public tickets. ~~~~ ## System Status Link: https://payoptimum.org/developer-docs#catalog-system-status The public PayFlow health endpoint reports service readiness signals; it is not a complete incident dashboard nor proof that card processing or PaymentHub LIVE client approval is active. ### Known public service health ~~~~bash curl -i 'https://api.payflow.buzz/v1/health' # Verify HTTP code and JSON readiness flags. # For card processing, verify card_processing and card_live_enabled # with authorized backend checks and actual processor evidence. # LIVE_CLIENT_ENABLED must be resolved for the specific client server-side. # No verified separate public status dashboard URL is supplied here. ~~~~ ## Developer Tools Link: https://payoptimum.org/developer-docs#catalog-developer-tools-links Jump directly to the current developer manual, AI builder assets and environment reference. These are public read-only references; authenticated developer operations and processor secrets stay server-side. ### Developer quick links ~~~~text Docs: https://payoptimum.org/docs Manual: https://payoptimum.org/developer-docs AI index: https://payoptimum.org/llms.txt AI guide: https://payoptimum.org/ai-builder-integration.txt AI manifest: https://payoptimum.org/.well-known/payoptimum-ai-builder.json Full reference: https://payoptimum.org/llms-full.txt API health: https://api.payflow.buzz/v1/health Studio: https://payoptimum.org/stripe/v4 API/SDK and developer tools do not create LIVE processing rights. ~~~~ # VOLUME 08 — AI Builder Handbook ## AI site builders — integration start here Link: https://payoptimum.org/developer-docs#ai-builder-entry This chapter is the authoritative starting point for assistants and AI-generated website integrations. Read the machine-readable manifest and the full technical guide BEFORE generating checkout code. Choose exactly one product path: PayFlow native Aurora or Stripe Adapter V4. The documentation is an integration reference, not permission to perform LIVE transactions. ### Machine-readable entry points ~~~~text Human documentation: https://payoptimum.org/developer-docs Documentation index: https://payoptimum.org/docs AI discovery: https://payoptimum.org/llms.txt AI complete context: https://payoptimum.org/llms-full.txt AI integration manifest: https://payoptimum.org/.well-known/payoptimum-ai-builder.json AI builder integration guide: https://payoptimum.org/ai-builder-integration.md Builders: fetch these references as READ-ONLY context. Do not imply PayFlow authorization, LIVE payment approval or a completed connection by discovering the files. ~~~~ ### Integration choice — decision table ~~~~text SITE ALREADY HAS STRIPE + MERCHANT WANTS PAYFLOW ADD-ON: Product: Stripe Adapter V4 Processor: merchant's own Stripe PayFlow charge: separate 39 EUR/month product subscription Merchant keys: server-side only, no browser processing Start: /stripe/v4 (visual studio), /stripe-adapter/connection (auth UI) SITE WANTS NATIVE PAYFLOW CHECKOUT: Product: Aurora Classic or Pro V7 Processor: PayFlow-native authorized payment infrastructure PayFlow Sandbox is for testing; PaymentHub is LIVE-only. Start: /dashboard/aurora/classic or /dashboard/aurora/pro (auth UI) Merchant merchant_id resolved server-side; never hard-code 'default'. SITE NEEDS NEITHER OR PRODUCT UNKNOWN: Ask which product and merchant environment before generating code. ~~~~ ## AI discovery manifest — meaning and trust boundaries Link: https://payoptimum.org/developer-docs#ai-builder-manifest The manifest is a machine-readable directory with product identifiers, published UI paths, environment separation, known verification gaps and explicit prohibitions. It is NOT an OpenAPI schema, an SDK authorization token or permission for an AI agent to create charges. Use it to choose documentation, not to invent network calls. ### How an assistant should use this documentation ~~~~text 1. Read /llms.txt for scope and canonical locations. 2. Read /.well-known/payoptimum-ai-builder.json for product separation. 3. Read /ai-builder-integration.md for the site integration workflow. 4. Identify PayFlow-native vs Stripe Adapter V4 BEFORE generating code. 5. Determine merchant session, environment, authorized backend, order source. 6. Verify exact API method/path/body/signatures from the DEPLOYED contract. 7. Generate frontend + server adapter + tests, with secrets kept server-only. 8. Run sandbox and negative security tests; never process LIVE by default. 9. Ask an authorized operator for LIVE activation after independent evidence. 10. Record which claims are VERIFIED, REPORTED, PROPOSED, or UNVERIFIED. ~~~~ ### Example manifest fetch (READ ONLY) ~~~~javascript const url = 'https://payoptimum.org/.well-known/payoptimum-ai-builder.json'; const response = await fetch(url, { method: 'GET', cache: 'no-store' }); if (!response.ok) throw new Error('MANIFEST_UNAVAILABLE'); const manifest = await response.json(); if (manifest.schema_version !== '1.0') { throw new Error('UNSUPPORTED_MANIFEST_VERSION'); } console.log(manifest.documentation.canonical); // Do not fetch or invoke charge/create endpoints from manifest discovery. // Keep secret credentials entirely outside the browser and the AI prompt. ~~~~ ## AI website builder playbook — end-to-end workflow Link: https://payoptimum.org/developer-docs#ai-builder-implementation This is a reusable integration playbook for tools such as Lovable, Base44 and coding agents. The model should output a small, auditable site adapter whose contracts are checked against PayFlow sources; never a disconnected mock checkout branded LIVE. ### Implementation plan to follow ~~~~text INPUTS NEEDED - Merchant product choice: native PayFlow checkout OR Stripe Adapter V4. - Merchant's server environment and deployment host. - Test vs LIVE intent (default TEST). - Verified merchant identity mapping service. - Product / order database and price source. - Exact PayFlow or Stripe adapter deployed contract. - Webhook routing, verified secrets provisioned server-side. - Subscription terms and consent, for the PayFlow product subscription only. GENERATE A. Public merchant-facing checkout UI from approved Aurora templates. B. Authenticated merchant administration page. C. Server-only order lookup + idempotent checkout-create endpoint. D. Provider-specific signed webhook receiver with replay store. E. Server status reconciliation + merchant-scoped ledger update. F. Subscription terms/confirm flow if a PayFlow add-on is purchased. G. Integration README, required env names, tests and rollback steps. REQUIRE - No card PAN/CVV in developer HTML, generated forms or analytics. - Zero LIVE configuration as default. - No guessed API endpoint names, signatures, or provider entitlements. - Screenshots and mock data labelled TEST/ILLUSTRATIVE. - Account A/B isolation and negative webhook tests. - Explicit 'not verified' status for untested functionality. ~~~~ ## Copyable master prompt for AI site builders Link: https://payoptimum.org/developer-docs#ai-prompt-template Paste this structured prompt into your AI web builder. Supply only non-secret configuration and links; approved credentials belong in the builder's trusted server-side secret store. The generated integration must distinguish real API evidence from placeholders. ### AI builder master instruction (copy and customize) ~~~~text You are integrating PayFlow into a merchant website. Before coding, read: https://payoptimum.org/llms.txt https://payoptimum.org/.well-known/payoptimum-ai-builder.json https://payoptimum.org/ai-builder-integration.md https://payoptimum.org/developer-docs Product choice: [PAYFLOW_NATIVE_AURORA | STRIPE_ADAPTER_V4] Merchant website stack: [e.g. Next.js + Node, Base44, Lovable] Environment: TEST by default. Merchant identity: derive on the SERVER from authenticated records. Never trust merchant_id, amount, currency or is_live from browser input. Implement exactly: 1. Brand-consistent responsive checkout/user flow. 2. Server-only order lookup and validated amount in minor currency units. 3. Server-to-server integration using VERIFIED published API contract. 4. Signature-verified, replay-protected, idempotent webhook handling. 5. Merchant-isolated payments, customers and events. 6. Status state machine: pending / processing / paid / failed / refunded. 7. Tests for wrong merchant, replay, double click, timeout and cancellation. 8. Security and deployment README, no secrets in browser/repository. 9. Show TEST/UNVERIFIED prominently until end-to-end tests pass. 10. Do NOT activate LIVE, invoice a customer, or claim paid without explicit authorized approval and independent processor evidence. Stripe Adapter V4: Merchant Stripe processes merchant customers' Stripe payments. PayFlow bills merchant separately for its 39 EUR/month add-on. Never merge PayFlow native and the Stripe Adapter implementation. PayFlow native: PayFlow Sandbox is testing; PaymentHub is LIVE-only. LIVE_CLIENT_ENABLED is checked server-side for a specific client. Do not use a default merchant account. Output implementation files, tests, deployment plan and a list of unverified assumptions requiring the operator's confirmation. ~~~~ ## Builder recipe — Base44 / managed app platforms Link: https://payoptimum.org/developer-docs#ai-builder-base44 When the merchant site runs on Base44 or another managed app platform, keep sensitive checkout operations in a backend function with a verified authenticated user and merchant mapping. Base44 entity collections for subscriptions are not payment-provider confirmations. Demonstrate safe failure states and never let a browser set a paid flag. ### Base44 merchant function — design pseudocode ~~~~typescript // Illustration of a server-side Base44-style function only. // Replace placeholders with the actual app SDK, merchant mapping, // authorized PayFlow contract and enforced entity permissions. export default async function(req: Request) { const user = await authenticateRequest(req); if (!user) return Response.json({error:'UNAUTHORIZED'}, {status:401}); const { orderId } = await req.json(); const merchant = await resolveMerchantServerSide(user.id); if (!merchant || !merchant.authorized) { return Response.json({error:'MERCHANT_FORBIDDEN'}, {status:403}); } const order = await getOrderForMerchant(orderId, merchant.id); if (!order) return Response.json({error:'NOT_FOUND'}, {status:404}); const checkout = await verifiedPayFlowApiCreateCheckout( merchant, order, idempotencyKeyFor(order) ); return Response.json({checkout_url:checkout.authorizedUrl}, {status:201}); } // Naming and endpoints here are NOT a deployable vendor API. // Adapt only after reading the provider's actual server code/spec. ~~~~ ## AI-generated integration acceptance criteria (must pass) Link: https://payoptimum.org/developer-docs#ai-builder-acceptance Use the following as a release gate for code produced by an AI website builder. A pretty checkout or a success banner does not count as a passed payment test. ### Machine-readable test plan checklist ~~~~text CONFIGURATION [ ] Correct product path: native vs adapter independent. [ ] Exact verified API contract and signing method. [ ] Server-only secrets; no values embedded in public HTML. [ ] Merchant maps exactly to the signed-in account. [ ] Default is TEST with explicit LIVE gate. SECURITY [ ] Wrong merchant's client/order ID rejected with no disclosure. [ ] Replay and duplicate webhook events do not double-apply. [ ] Invalid signature, expired request and missing scope denied. [ ] Race conditions and retries are idempotent. [ ] LIVE_CLIENT_ENABLED is checked by authorized backend. PAYMENTS [ ] User cannot set amount or mark order paid from browser. [ ] Processor event and status independently match order. [ ] Failed, canceled and pending states are never called paid. [ ] Invoice is issued only with legally/technically correct evidence. [ ] Product subscription and merchant charges have separate ledgers. EXPERIENCE [ ] Dashboard and public preview routes resolve. [ ] Light and dark mode, mobile Safari, keyboard and focus work. [ ] Docs/meta social previews work without JavaScript where possible. [ ] Rollback and alerting have been verified. GO / NO-GO Any failed critical item: NO-GO for LIVE. ~~~~ # VOLUME 09 — Products and Commercial Operations ## Start here — PayOptimum products and roles Link: https://payoptimum.org/developer-docs#start-here PayOptimum is the merchant workspace. PayFlow offers its own native checkout systems. Stripe Adapter V4 is a separate PayFlow add-on for a merchant's existing Stripe account. These two processing architectures must never be merged or silently substituted. This guide describes the currently linked application screens; accessibility does not imply card processing is live. ### Product directory — current published routes ~~~~text PayOptimum documentation: https://payoptimum.org/docs Technical documentation: https://payoptimum.org/developer-docs Dashboard: https://payoptimum.org/dashboard (requires sign-in) Product subscriptions: https://payoptimum.org/product-billing (requires sign-in) Stripe Adapter V4 studio: https://payoptimum.org/stripe/v4 (public design preview) Stripe V4 inside merchant dashboard: https://payoptimum.org/dashboard/stripe/v4 Stripe backend overview: https://payoptimum.org/stripe-adapter/overview (authenticated) Stripe connection: https://payoptimum.org/stripe-adapter/connection (authenticated) Aurora Classic product: https://payoptimum.org/dashboard/aurora/classic Aurora Pro V7 product: https://payoptimum.org/dashboard/aurora/pro Public design studios ≠ merchant access ≠ LIVE payment processing. ~~~~ ## Verified deployment vs. unverified operation Link: https://payoptimum.org/developer-docs#deployment-status Documentation status as of 14 November 2026. 'Deployed' is a code/route observation, not proof of production readiness. No claim of a successful live card transaction, a subscribed customer or paid invoice is made. Review these checks again whenever the deployment or provider configuration changes. ### Operational status matrix ~~~~text AREA OBSERVED / CURRENT NOT YET VERIFIED PayOptimum web routes Published; HTTP 200 for key paths Browser auth and all user flows Stripe V4 uploaded studio Original HTML embedded Real Stripe charge by this file Stripe Adapter backend UI Authenticated screens and actions OAuth + payment + webhook E2E Aurora Pro V7 studio Existing studio URL responds Card LIVE, publishing and receipts Aurora Classic link Entry redirects to V7 preview Distinct Classic build/location Offer / confirmation UI Visible; prices in EUR Recurring LIVE checkout Subscription intent function Deployed; unsigned visitor 401 Authenticated save to entity E2E PayFlow Sandbox Separate testing environment Specific end-to-end transactions PaymentHub LIVE User designates payflowbuzz-canada Verified PayOptimum integration LIVE_CLIENT_ENABLED Required client-level gate Activation for any given client Xero, UBS, Angel finance Workspace modules and guides Verified external sync/settlement Do not turn unverified items into marketing promises or paid statuses. ~~~~ ## Native PayFlow vs. Stripe Adapter V4 — strict separation Link: https://payoptimum.org/developer-docs#products-boundary PayFlow native and Stripe Adapter V4 are independent offerings, with distinct processor ownership, configuration, merchant authorizations, data access, APIs and operational workflows. Stripe merchant transactions run on that merchant's Stripe account; PayFlow's €39 monthly subscription fee is a separate PayFlow sale. No payment credentials or transaction ledgers should be shared across these two pipelines. ### Separate payment paths ~~~~text A. PayFlow native checkout — Aurora Classic / Aurora Pro Customer → merchant's checkout → verified PayFlow merchant identity → PayFlow native payment flow → authorized PayFlow processor → signed status/webhook → merchant order reconciliation → PayFlow Billing / merchant reporting, according to deployed contract B. Stripe Adapter V4 add-on Merchant → subscribes to PayFlow add-on (39 EUR/month) → PayFlow billing Merchant → connects their OWN Stripe account securely Customer → merchant's Stripe checkout → merchant's Stripe processor → Stripe payment and Stripe webhook → adapter's merchant-scoped status NO mixing of Stripe merchant payments with PayFlow native charges. NO substitution of merchant Stripe credentials for PayFlow billing credentials. ~~~~ ## Stripe V4 Full Pipeline Studio — original HTML and five screens Link: https://payoptimum.org/developer-docs#stripe-v4-source The /stripe/v4 page embeds the owner's 46,951-byte index-9.html design file (Aurora Builder v7 — Stripe Full Pipeline) via srcDoc to avoid the host's iframe restrictions. It contains interactive visual controls and five stages, but its own text explicitly labels the output PREVIEW and NO LIVE CHARGES. The studio is not a substitute for the authenticated Stripe Adapter backend screens. ### Five design stages — what they actually do ~~~~text 01 CHECKOUT Edit merchant name, products, quantities and amount preview. 02 BILLING PORTAL Preview the subscription/portal look; no actual Stripe portal. 03 INVOICE Preview invoice layout; no invoice is issued. 04 RECEIPT Preview a sample receipt; no payment is confirmed. 05 EMAIL Preview a message template; no email is sent. Studio functions: 5 templates; independent light/dark studio & checkout themes; palette/colour editor; CHF/EUR/USD/GBP display; device preview; export JSON and preview HTML. Demo product prices are illustrations, not Stripe price IDs. Original page: /stripe/v4 In merchant dashboard: /dashboard/stripe/v4 The Studio's 'Pay securely' button is preview-only. ~~~~ ## Stripe Adapter V4 merchant integration workflow Link: https://payoptimum.org/developer-docs#stripe-v4-backend The adapter backend offers authenticated Overview, Connection, Checkout, Payments, Transactions and Activity screens. Connection state may be missing or pending. Never describe Stripe as a PayFlow processor, and never claim a Stripe endorsement. A merchant retains ownership of their Stripe account and transactions. ### Merchant setup checklist ~~~~text 1. Sign in to PayOptimum and open /stripe-adapter/connection. 2. Confirm the logged-in merchant maps to their own merchant_id server-side. 3. Connect the merchant's own Stripe account (OAuth or supported secure server path). 4. Keep secrets encrypted on the server; do not put sk_test_, sk_live_, CVV, merchant signing secrets or webhook secrets into local HTML or browser input. 5. Confirm connection status server-side and scope the merchant account. 6. Create a TEST checkout session against the verified adapter endpoint. 7. Verify signed webhook, idempotency, status, and transaction visibility. 8. Require explicit separate LIVE readiness approval before any live charge. 9. Do not mark an order paid from a success_url or browser redirect. Backend UI: /stripe-adapter/overview, /connection, /checkout-sessions, /payments, /transactions and /activity; all merchant-authenticated. ~~~~ ## Aurora Classic and Aurora Pro V7 — installation and limitations Link: https://payoptimum.org/developer-docs#aurora-builders Aurora Classic and Aurora Pro are PayFlow native product offerings. The PayOptimum dashboard has dedicated product pages for both. The currently published Classic entry has been observed redirecting into a V7 studio; a distinct Classic deployment has not been proven. The Pro V7 studio is hosted externally and currently disallows iframe embedding (frame-ancestors none), so PayOptimum opens it in a new tab. ### Builder access and installation sequence ~~~~text Product page (requires merchant session) Classic: /dashboard/aurora/classic Pro V7: /dashboard/aurora/pro Studio endpoints as observed: Classic entry: https://payflow.buzz/dashboard/checkout-aurora-builder Pro V7: https://payflow-aurora-builder-v7.nagle-b42.workers.dev/ Before a merchant installs either checkout: [ ] Confirm the actual version (Classic vs Pro). [ ] Authenticate the merchant and derive merchant ID on server. [ ] Bind the correct price catalogue and environment. [ ] Keep card capture only in provider-approved hosted elements. [ ] Create order server-side; use a stable idempotency key. [ ] Verify signed status and webhook before fulfillment. [ ] Test sandbox, cancellation, timeout, refunds and duplicate events. [ ] Approve LIVE processor and per-client enablement explicitly. Do not embed external studio in iframe while frame-ancestors denies it. ~~~~ ## Product subscription pricing, confirmation and billing Link: https://payoptimum.org/developer-docs#subscriptions-billing The catalogue is for PayFlow product access and is distinct from a merchant charging their own clients. Each Subscribe button opens a price-specific confirmation panel. The current backend function records pending_billing intent only; it does not process a payment, start recurring collection, issue an invoice, or activate the product. A client session is required. ### Monthly catalogue — EUR, no assumed tax treatment ~~~~text Stripe Adapter V4 39 EUR / month PayFlow Aurora Classic 29 EUR / month Aurora Pro V7 Starter 19 EUR / month Aurora Pro V7 Pro 49 EUR / month Aurora Pro V7 Enterprise 99 EUR / month 14-day Pro trial: planned only; not enabled. Taxes: calculated only once a jurisdiction and verified billing contract are configured. Do not imply tax-inclusive or tax-exclusive terms. Current checkout intent: Select offer → view and confirm amount → authenticate user → server validates fixed product/price → pending_billing record → wait for authorized PayFlow checkout → independent payment confirmation → verified webhook → invoice/receipt + service activation (NOT IMPLEMENTED E2E). A 'request received' message must not say 'payment successful'. ~~~~ ### Current Base44 subscription-intent invocation ~~~~javascript // Authenticated PayOptimum app only. // Product and amount are revalidated on the server from a fixed catalogue. const response = await base44.functions.invoke('productSubscriptionIntent', { action: 'request', product_id: 'stripe-adapter-v4', confirm_monthly_subscription: true }); const result = response.data; if (result?.state === 'pending_billing') { // This is NOT a successful payment or an active subscription. displayPendingRequest(result.request_id); } // Other states can include unauthorized, confirmation_required, // invalid_product, or unavailable. Handle them without guessing. ~~~~ ## PayFlow Sandbox, PaymentHub LIVE and client activation Link: https://payoptimum.org/developer-docs#sandbox-live-paymenthub Architecture clarified by the project owner: PayFlow Sandbox supports testing. PaymentHub is the LIVE-only processor integration, registered as payflowbuzz-canada, and is accessible through the PayFlow-controlled production flow. LIVE_CLIENT_ENABLED denotes a client-specific authorization gate. The existence of this architecture does not prove that PayOptimum's subscription checkout is connected to the authorized LIVE endpoint or that any client is enabled. ### Required LIVE activation gates ~~~~text ENVIRONMENT ROLE PayFlow Sandbox TEST only; no real settlement PaymentHub LIVE PayFlow-controlled production processor (payflowbuzz-canada) LIVE_CLIENT_ENABLED server-verified eligibility for the specific client NO-GO unless all verified in trusted backend: [ ] Authorized session, verified client and merchant ID (no 'default'). [ ] LIVE_CLIENT_ENABLED is evaluated server-side and currently true. [ ] Approved LIVE processor connection and contractual merchant authorization. [ ] Currency, price, taxes and recurring schedule fixed server-side. [ ] Risk, reconciliation, cancellation and failure paths tested. [ ] Real processor checkout session created once per idempotency key. [ ] Signed webhook evidence verifies payment / subscription state. [ ] Invoice issued from verified ledger facts and sent through approved flow. [ ] Separate merchant test proves data isolation; rollback is available. Never infer LIVE permission from a browser switch, query parameter or banner. ~~~~ ## Merchant isolation and identity — enforcement contract Link: https://payoptimum.org/developer-docs#merchant-isolation Browser-supplied merchant IDs, user emails and amounts are untrusted. The Base44 account must be resolved server-side into exactly one authorized merchant context, and the downstream PayFlow/Stripe endpoints must independently enforce the same identity. Use dedicated TEST and LIVE credentials and keys. Admin access is not a substitute for merchant isolation. ### Two-merchant negative testing ~~~~text Tenant A (authenticated as merchant A) Can read A's customers, subscriptions, invoices, payments and events. CANNOT read, mutate or infer tenant B records. Tenant B (authenticated as merchant B) Can read B's own records only. CANNOT use a forged merchant_id=A or Stripe account A. Test cases: [ ] A tries B's record ID → 403 or 404; no side effects. [ ] B tries to reuse A's signed assertion or OAuth state → rejected. [ ] Same email for two merchants is NOT used as merchant identity. [ ] Signed webhook for A cannot update B. [ ] Expired JWT, nonce/jti replay, missing scope → fail closed. [ ] No merchant mapping, duplicate mappings, deleted user → fail closed. [ ] LIVE_CLIENT_ENABLED false/missing → no LIVE processing. [ ] Secrets never appear in browser bundles, logs or public docs. ~~~~ ## Invoices, receipts, retries and accounting boundaries Link: https://payoptimum.org/developer-docs#billing-invoices An invoice and a paid receipt are different objects. Pending billing requests are neither an issued invoice nor revenue. Revenue recognition, tax application, refunds, Xero/UBS sync and finance approvals must reflect verified backend records. Angel 2.0 can support review but must not independently approve financial disbursements. ### Lifecycle and evidence requirements ~~~~text REQUESTED User confirms product and monthly fee → pending_billing CHECKOUT_PENDING Authorized processor checkout created server-side PROCESSING Payment provider says pending; no fulfillment yet PAID Verified signed event + authoritative provider status ACTIVE Subscription terms and period stored after PAID PAST_DUE Renewal failed; retry/notifications by approved policy CANCELED Future billing stopped; retention and access rules applied For invoicing: - Identifier, merchant legal entity, tax rate, currency, paid/unpaid status. - Reference to actual processor payment and period, if paid. - Never issue a paid invoice from an unverified URL return. - Xero or UBS synchronization is independent and requires authorization. - No raw payment card details in invoice, logs or assistant context. ~~~~ ## Install PayFlow on merchant sites — server-first handoff Link: https://payoptimum.org/developer-docs#integration-flow The site may use Checkout Pro Aurora as a visual checkout and frontend, but orders, merchant identity and payment confirmation belong to a trusted backend. Generated HTML/JS are visual assets, not processor credentials. Keep the integration independent from the Stripe add-on. ### Site-to-processor integration checklist (contract outline) ~~~~text Merchant site 1. User selects product in hosted/embedded Aurora checkout. 2. Site backend authenticates user and loads its own trusted order. 3. Site backend resolves merchant authorization; amount in minor units. 4. Backend requests a payment session against VERIFIED PayFlow API. 5. Browser receives only an authorized URL/token (never API secrets). 6. PayFlow verifies payment status server-side. 7. Webhook signature + timestamp + replay + idempotency checked. 8. Site order transitions to paid only after verified evidence. 9. Errors, cancellations and retries do not double-charge. The precise POST path, headers, body fields and signature specification must be taken from the deployed PayFlow API and a tested installation manifest. Do not use an invented endpoint copied from illustrative documentation. ~~~~ ## Dashboard operations — modules and access Link: https://payoptimum.org/developer-docs#dashboard-operations The merchant workspace shows Dashboard, Clients, Subscriptions, Transactions, Reports, Tax settings, Analytics, Support, Angel 2.0 and Xero Partner. Displayed records are not necessarily PayFlow's live ledger: a Base44 entity and a processor payment are distinct, and connection health must be verified before claiming real-time integration. ### Merchant and administrator routes ~~~~text /dashboard Merchant overview; sign-in required /dashboard/stripe/v4 Original V4 visual studio inside dashboard /dashboard/aurora/classic Classic product and price confirmation /dashboard/aurora/pro Pro V7 product and tier selection /product-billing Offer selection, explicit confirmation /subscriptions Workspace records, NOT payment receipts /transactions Workspace transaction records /clients Merchant client directory /reports Reporting views /analytics Analytics module /assistant Billing assistant /angel Angel 2.0 CFO assistant /xero-partner Xero integration module /settings Business settings /support Help and tickets All merchant data must be scoped and checked server-side. An administrator overview must not leak another merchant's information. ~~~~ ## Troubleshooting — empty pages, routing, sessions and 503 Link: https://payoptimum.org/developer-docs#troubleshooting-new Use the failing URL, session state and server response to diagnose before redeploying. A healthy HTML response (HTTP 200) can still contain a client-side exception. Avoid creating redirect loops by sending users between /dashboard and /login without preserving a same-origin return path. ### Diagnostic decision tree ~~~~text Black iframe on /stripe/v4: Original source is embedded via srcDoc because the hosting site denies cross-origin iframe display. If still black, inspect browser console and JS. Unauthenticated dashboard: 302 or client redirect to /login?returnTo=. After successful sign-in, return to the originally requested screen. Classic opens V7: Known deployment mismatch. Do NOT describe as distinct Classic published. Subscription confirmation says unavailable: Backend storage/invocation failed. No charge. Check function errors, entity permissions, deployed schema, service role and session. 401: Login required; no write should be made. 403: Authorization or merchant mapping mismatch; reject, do not retry with default. 503: Backend or provider unavailable; no payment or request should be assumed. PaymentHub reports a sandbox error: Check which endpoint was called. The billing-gateway sandbox response is NOT evidence that the LIVE-only PaymentHub processor is itself sandbox. Payment status pending: Wait for verified processor status; do not mark paid from redirect. For every incident capture date, route, request ID, deployment and environment. Do not paste secrets or complete bank details into tickets. ~~~~ ## Release checklist, rollback and acceptance tests Link: https://payoptimum.org/developer-docs#release-no-go A clear go/no-go decision must be supported by production evidence. No LIVE switch, subscription invoicing or merchant activation is authorized merely by publishing these docs. Preserve native PayFlow and Stripe Adapter V4 as independent systems throughout testing and release. ### Final QA matrix ~~~~text PRODUCT EXPERIENCE [ ] /docs and /developer-docs load; search and copy work. [ ] All product links open the intended screen, including mobile Safari. [ ] V4 studio five stages, export and theme controls work. [ ] Aurora Classic has a verified distinct deployment or is disclosed. [ ] Aurora Pro V7 route and sandbox controls respond. SUBSCRIPTIONS [ ] Every Subscribe button shows correct amount in EUR and recurring term. [ ] Decline/cancel causes no backend write. [ ] Confirm requires explicit selection and a real authenticated session. [ ] Server rejects unknown plan IDs and browser-supplied amounts. [ ] Duplicate submission cannot create duplicate charges or subscriptions. [ ] PaymentHub LIVE connection tested with LIVE_CLIENT_ENABLED gating. [ ] Processor checkout and signed event independently confirmed. [ ] Invoice, receipt, retry/cancellation behaviour verified. SECURITY / OPERATIONS [ ] Two-merchant read/write isolation and replay tests pass. [ ] Signed webhook, time window, replays and ledger reconciliation pass. [ ] Failure is safe (no false paid status); logging redacts secrets. [ ] Rollback version saved, previous routes intact. [ ] Data retention, privacy policy, terms and support contact approved. NO-GO for real payments until all relevant LIVE checks are signed off. ~~~~ ## FAQ — concise answers for merchants Link: https://payoptimum.org/developer-docs#faq-new Answers apply to the current PayOptimum integration, not an unverified external processor contract. ### Frequently asked questions ~~~~text Q: Can I inspect Stripe V4 without subscribing? A: Yes, /stripe/v4 displays the original five-stage visual builder. Q: Does the HTML builder charge a customer? A: No. Checkout, portal, invoice, receipt and email are previews. Q: Will PayFlow collect my customers' Stripe payments? A: No. With Stripe Adapter V4, your Stripe account processes them. Q: What does 39 EUR/month buy? A: Access to the Stripe Adapter V4 add-on from PayFlow, once activated. Q: Does pressing Subscribe immediately debit my card? A: No. It currently requests a subscription; LIVE billing is not linked E2E. Q: Is PaymentHub a sandbox payment provider? A: No. Per the project architecture it is PayFlow LIVE-only. PayFlow Sandbox is a separate testing environment. Q: Is LIVE_CLIENT_ENABLED enough by itself? A: No. Server-side account, processor, pricing and payment checks must pass. Q: Can I use Aurora Classic and Pro without connecting Stripe? A: They are native PayFlow products, separate from Stripe Adapter. Q: Where do I get API keys and put them? A: Only from approved server-side configuration/secrets; never in the page. Q: Why does the Classic button open V7? A: The available Classic entry currently redirects; separate deployment is pending. Q: Who can view my client/payment records? A: Only authorized merchant/account contexts; cross-merchant isolation must be enforced and proven server-side before LIVE deployment. ~~~~ # VOLUME 10 — Engineering and Security ## API reference policy — how to identify a real endpoint Link: https://payoptimum.org/developer-docs#api-contract A documented URL must be tied to the deployed service and an authenticated integration test. The examples here are patterns, not a substitute for the actual OpenAPI definition or source deployment inventory. PayFlow, PayOptimum Base44 and the merchant's Stripe API are different systems; do not copy a route between them. ### Endpoint inventory — what is actually known ~~~~text https://api.payflow.buzz/v1/health GET public health (does not prove LIVE) https://payoptimum.org/stripe/v4 Public, read-only design preview https://payoptimum.org/dashboard/stripe/v4 Authenticated dashboard studio https://payoptimum.org/stripe-adapter/connection Merchant connection UI https://payoptimum.org/product-billing Product offers + confirmation UI Base44 function available in current source: productSubscriptionIntent POST via authenticated Base44 function invocation action: request, product_id: fixed catalogue ID, confirm_monthly_subscription: boolean Illustrative source routes MUST NOT be presented as deployed without tests. Obtain the PayFlow API specification, source commit and route policy for the exact environment before publishing SDK instructions. ~~~~ ### Portable endpoint acceptance checklist ~~~~text For each public endpoint, record: - Host + method + path + environment - Authentication mechanism, permissions, tenant resolution - JSON schema with required and optional fields - HTTP errors and stable error identifiers - Idempotency, retry behaviour and rate limits - API versioning and deprecation policy - Sample test using a non-production account and a redacted response - Source commit + date last verified Never infer an endpoint from a mock, redirect, or path in older documentation. ~~~~ ## TypeScript SDK starter — resilient, server-only client Link: https://payoptimum.org/developer-docs#typescript-sdk This complete Node/TypeScript pattern demonstrates timeout, correlation IDs, error mapping, request idempotency and redaction. The request path and authentication mode remain parameters: instantiate it only after checking the verified PayFlow API specification. Never bundle this code with a frontend or put bearer secrets in a web application. ### payflow-client.ts — reference pattern (adapt to verified API contract) ~~~~typescript type Json = Record; type ApiResult = { status: number; data: T; requestId: string | null }; class PayFlowRequestError extends Error { constructor(public status: number, public code: string) { super(`PayFlow request failed: ${code}`); } } export class PayFlowServerClient { constructor( private readonly origin: string, private readonly secret: string, ) { if (!origin.startsWith('https://') || !secret) { throw new Error('Secure server-side configuration required'); } } async request( method: 'GET' | 'POST', verifiedPath: string, body?: Json, idempotencyKey?: string ): Promise> { if (!verifiedPath.startsWith('/') || verifiedPath.startsWith('//')) { throw new Error('Use a relative path from the verified API specification'); } const controller = new AbortController(); const timeout = setTimeout(() => controller.abort(), 10000); try { const response = await fetch(this.origin + verifiedPath, { method, signal: controller.signal, headers: { 'Accept': 'application/json', 'Content-Type': 'application/json', // Example only: replace with verified auth/signing contract. 'Authorization': 'Bearer ' + this.secret, ...(idempotencyKey ? { 'Idempotency-Key': idempotencyKey } : {}) }, ...(body ? { body: JSON.stringify(body) } : {}) }); const payload = await response.json().catch(() => ({})); if (!response.ok) { throw new PayFlowRequestError( response.status, String(payload?.error || 'UPSTREAM_ERROR') ); } return { status: response.status, data: payload as T, requestId: response.headers.get('x-request-id') }; } finally { clearTimeout(timeout); } } } // SERVER-ONLY. Path and signing headers above are illustrative. // Do not use for LIVE charges until the real PayFlow contract is verified. ~~~~ ## Secure merchant checkout implementation — reference blueprint Link: https://payoptimum.org/developer-docs#backend-checkout-example Treat product IDs and amounts from the browser as hints only; server-side order data determines the charge. The browser must never choose a merchant ID, secret or final payment status. Examples below are a design blueprint until aligned with a verified endpoint. ### Node/Express order-to-checkout handoff ~~~~javascript import express from 'express'; import crypto from 'node:crypto'; const app = express(); app.use(express.json({ limit: '32kb' })); app.post('/api/checkout/start', async (req, res) => { const session = await requireMerchantSession(req); // implement const order = await loadMerchantOrder(session, req.body.order_id); if (!order || order.ownerMerchantId !== session.merchantId) { return res.status(404).json({ error: 'ORDER_NOT_FOUND' }); } if (order.status !== 'pending') { return res.status(409).json({ error: 'ORDER_NOT_PENDING' }); } const key = crypto.createHash('sha256') .update(session.merchantId + ':' + order.id + ':' + order.version) .digest('hex'); // Only invoke a VERIFIED, contract-matched PayFlow endpoint. const result = await verifiedPayFlowCheckoutCreate({ merchantId: session.merchantId, amountMinor: order.amountMinor, currency: order.currency, orderId: order.id, idempotencyKey: key }); await markCheckoutPending(order.id, result.reference); return res.status(201).json({ checkout_url: result.authorizedUrl }); }); // Each named service function above MUST be implemented and tested. // Never use success_url, a frontend response or sample receipt as paid proof. ~~~~ ## Webhooks — verification, replay protection and delivery semantics Link: https://payoptimum.org/developer-docs#webhook-deep-dive Webhook endpoint signatures differ between native PayFlow and Stripe. Verify each using its own exact provider-specific contract over the raw body; do not substitute a generic HMAC example for a real signature verifier. A received event is not a trusted payment until verification, authorization and ledger reconciliation complete. ### Idempotent consumer — transaction boundary blueprint ~~~~typescript // Provider-specific: signatureVerify() MUST implement the actual contract. async function consumeVerifiedEvent(rawBody: Buffer, headers: Headers) { const envelope = await signatureVerify(rawBody, headers); const merchant = await resolveVerifiedMerchant(envelope.account); if (!merchant) throw new Error('MERCHANT_NOT_AUTHORIZED'); await database.transaction(async trx => { // Unique index on (provider, verifiedEventId, merchantId). const firstSeen = await trx.events.insertUnique({ provider: envelope.provider, verifiedEventId: envelope.id, merchantId: merchant.id, status: 'processing' }); if (!firstSeen) return; // duplicate acknowledged, never applied twice const order = await trx.orders.byReference(envelope.orderReference); if (!order || order.merchantId !== merchant.id) { throw new Error('ORDER_MERCHANT_MISMATCH'); } const verifiedStatus = await providerStatusLookup(envelope, merchant); if (verifiedStatus === 'paid') { await trx.orders.markPaidOnce(order.id, envelope.id); } await trx.events.markHandled(envelope.id); }); } // Return 2xx only once the event is safely stored/handled. // Transient backend failure: non-2xx, retry with backoff and dead-letter alerts. // Above functions are architecture hooks, not an installed PayFlow SDK. ~~~~ ### Replay and event ordering tests ~~~~text [ ] Invalid signature rejected; raw bytes unchanged prior to verification [ ] Expired timestamp, unknown key or mismatched account rejected [ ] Same event delivered 2x/10x → at most one state transition [ ] Out-of-order failed/paid event cannot regress a terminal paid state [ ] Simultaneous webhook and polling update → one authoritative ledger entry [ ] Wrong merchant/account/order → rejected and security logged [ ] Event verified but downstream unavailable → queued/retried, not lost [ ] Sensitive card or personal data redacted from operational logs [ ] Provider-specific endpoints and keys never swapped ~~~~ ## Recurring billing — activation, renewals, cancellation and entitlement Link: https://payoptimum.org/developer-docs#subscription-server Product subscriptions must be invoiced through PayFlow's authorized LIVE processor, separate from a merchant's Stripe checkout activity. The current PayOptimum 'Subscribe' request is a pending intent, not a recurring agreement. A fixed server catalogue, LIVE_CLIENT_ENABLED and verified processor webhook must guard every activation. ### State machine — proposed production contract ~~~~text offer_selected --customer consent--> pending_billing pending_billing --authorized PayFlow checkout created--> checkout_pending checkout_pending --provider confirms payment--> payment_verified payment_verified --idempotent entitlement write--> active active --renewal failed--> past_due past_due --verified retry success--> active past_due --grace/termination policy--> canceled active --merchant cancellation--> cancel_at_period_end / canceled BLOCKED transitions: pending_billing → active (without provider proof) frontend redirect → paid LIVE_CLIENT_ENABLED=false → checkout_pending unknown merchant/default identity → any LIVE processing duplicate webhook → duplicate invoice / duplicate subscription merchant Stripe API key → PayFlow product subscription billing Tax/legal terms, billing schedule and cancellation conditions must be presented and accepted before a charge (not invented by this guide). ~~~~ ### Price validation and request audit ~~~~typescript // Current source catalogue (EUR minor units). const catalog = { 'stripe-adapter-v4': 3900, 'payflow-classic': 2900, 'payflow-v7-starter': 1900, 'payflow-v7-pro': 4900, 'payflow-v7-enterprise': 9900 } as const; function validateSelection(productId: string, confirmed: boolean) { if (!confirmed || !(productId in catalog)) { throw new Error('SUBSCRIPTION_CONFIRMATION_OR_PLAN_REQUIRED'); } return { productId, amountMinor: catalog[productId as keyof typeof catalog], currency: 'EUR', interval: 'monthly' as const }; } // Current implementation records a pending_billing intent only. // LIVE processing must be implemented separately under explicit authorization. ~~~~ ## Environment and secrets matrix — no cross-wiring Link: https://payoptimum.org/developer-docs#environment-matrix Different products and processors require isolated credentials, domains, signed webhooks and audit events. PaymentHub LIVE belongs to PayFlow production (payflowbuzz-canada per project configuration); PayFlow Sandbox is a separate testing service. Client-level LIVE status is a server policy and cannot be trusted from JavaScript or a checkout switch. ### Integration partition matrix ~~~~text BOUNDARY TEST/SANDBOX LIVE/PRODUCTION PayFlow native PayFlow Sandbox PayFlow authorized LIVE + PaymentHub Merchant Stripe V4 Merchant Stripe TEST Merchant Stripe LIVE (separately approved) PayOptimum offer flow Pending request PayFlow LIVE billing (not yet wired) Bank-transfer approval Simulated records Human/authorized reconciled evidence Analytics Merchant test data Merchant-isolated verified production Server-side secrets: signed credentials, merchant mappings and webhook secrets. Public browser: product selection + price display + authorized handoff URL only. LIVE_CLIENT_ENABLED may gate a PayFlow client but is not proof of processor connected, KYC completed, payment authorized or webhook delivered. ~~~~ ## Observability — logs, correlation, dashboards and incidents Link: https://payoptimum.org/developer-docs#observability Correlate browser interaction, authenticated merchant intent, processor request, webhook and ledger state without logging secrets. Include environment and deployment revision on every server request. Alerts should be tied to payment failure and security anomalies rather than synthetic demo data. ### Minimal structured event envelope (redacted) ~~~~json { "timestamp": "ISO-8601", "service": "payflow-billing-integration", "environment": "sandbox-or-production", "request_id": "server-generated-correlation-id", "merchant_ref": "hashed-or-internal-scope-id", "subscription_ref": "opaque-record-reference", "event": "checkout_requested|webhook_verified|activation_rejected", "result": "pending|confirmed|failed", "error_code": "optional-machine-readable-identifier", "deployment": "commit-or-release-id" } ~~~~ ### Incident response and alerts ~~~~text Critical: unexpected LIVE activation; cross-merchant leak; missing signature check. High: duplicate charge suspicion; webhook backlog; payment/ledger mismatch. Medium: expired auth, pricing mismatch, unavailable checkout endpoint. Low: demo export failure, public docs 404 or broken link. For each incident: 1. Block unsafe financial actions if risk is unclear. 2. Capture server request ID and merchant-scoped evidence (redacted). 3. Review provider status independently of browser redirects. 4. Apply idempotent recovery, never blind resubmission of a charge. 5. Document cause, revision, rollback and retest outcomes. 6. Notify impacted parties as required by applicable policy/law. ~~~~ ## Local development and reproducible staging Link: https://payoptimum.org/developer-docs#local-dev Keep example secrets out of Git. Document exact source commit and test environment. Develop with isolated test merchants and clearly tagged transactions. Only deploy site files or builder visuals after the server, API and webhook contracts are defined. ### Local test checklist and safe variables ~~~~bash # Example names only. Never commit real values. PAYFLOW_API_BASE_URL=https://api.payflow.buzz PAYFLOW_ENVIRONMENT=sandbox PAYFLOW_MERCHANT_ID=TEST_MERCHANT_ID PAYFLOW_API_KEY=SET_IN_SERVER_SECRET_STORE PAYFLOW_WEBHOOK_SECRET=SET_IN_SERVER_SECRET_STORE # Static HTML previews may run locally WITHOUT any payment credentials. # Authenticate separate TEST merchants; verify no shared records. # Production secrets never enter .env.example, Vite env, localStorage, HTML, # screenshots, browser network panel, analytics events or support tickets. # Run the app's existing build and lint scripts before deploying. npm run build npm run lint # The original app may have pre-existing unrelated lint warnings/errors; # isolate changed-file checks and document them in the deployment report. ~~~~ ## Merchant migration, onboarding and version upgrades Link: https://payoptimum.org/developer-docs#client-migration Migrating an existing checkout must preserve order ownership, payment history and processor authority. Do not migrate a merchant's Stripe processing into PayFlow native, or vice versa, without a separate explicit authorization. Version product configuration, test with a controlled subset of merchants and support rollback. ### Rollout checklist ~~~~text BEFORE [ ] Identify product: PayFlow native vs Stripe Adapter V4 [ ] Inventory existing merchant checkout URLs, webhooks, subscriptions [ ] Snapshot installation sources and deployment versions [ ] Check merchant consent and processor ownership [ ] Define backfill vs no-backfill and retention policy STAGING [ ] Mock/check request contract, including 401/403/409/503 [ ] Verify account-scoped pricing and webhook mapping [ ] Validate duplicate checkout, retry and customer cancellation [ ] Test mobile, keyboard, Safari and network disruptions LIVE GO/NO-GO [ ] Confirm source of truth for verified paid state [ ] Confirm LIVE_CLIENT_ENABLED for the specific authorized client [ ] Confirm LIVE processor credentials + verified callback [ ] Approve rollback path and contact list [ ] Monitor errors, provider status and duplicate-charge signals AFTER [ ] Track activation and support tickets [ ] Reconcile first period and invoices [ ] Keep last good version available for rollback ~~~~ ## Frontend integration — React, vanilla JS and safe redirects Link: https://payoptimum.org/developer-docs#frontend-integration The browser can present the checkout and subscription choices but cannot assert merchant identity or payment success. Authenticated merchants should use internal dashboard routes, public visitors should see previews, and redirects must use an allowlist of same-origin paths. ### React — link directly to genuine product pages ~~~~jsx import { Link } from 'react-router-dom'; function Products() { return ( ); } // Auth required for /dashboard/*. // Keep the Stripe V4 visual preview open at /stripe/v4. ~~~~ ### Browser checkout redirect — defensive handling ~~~~javascript // The server returns a trusted checkout URL, never an arbitrary browser URL. const response = await fetch('/api/checkout/start', { method: 'POST', credentials: 'include', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ order_id: orderId }) }); if (!response.ok) throw new Error('CHECKOUT_NOT_AVAILABLE'); const { checkout_url } = await response.json(); const target = new URL(checkout_url); if (!['checkout.your-approved-provider.example'].includes(target.hostname) || target.protocol !== 'https:') { throw new Error('UNTRUSTED_CHECKOUT_REDIRECT'); } window.location.assign(target.toString()); // EXAMPLE ONLY: replace provider host with a verified allowlist. // Never treat the later success redirect as proof of payment. ~~~~ ## Privacy, compliance and accessibility checklist Link: https://payoptimum.org/developer-docs#privacy-legal Financial documentation should not leak merchant/customer data or secrets. All payment systems must have an approved data-processing, retention, incident-response and regulatory model consistent with the jurisdictions served. Accessibility is a release requirement, not a cosmetic addition. ### Risk and compliance release checklist ~~~~text SECURITY [ ] PCI scope assessed; hosted fields/tokenization verified by provider [ ] No raw PAN, CVV or full bank account in HTML, logs, analytics or assistant [ ] Key rotation, webhook signing key rollover and audit retention documented [ ] Strict merchant isolation, GDPR/Swiss FADP considerations reviewed [ ] KYC/AML responsibilities and processor contract assigned CUSTOMER TERMS [ ] Clear recurring price, billing period, tax treatment and seller name [ ] Refund, cancellation and chargeback terms reviewed [ ] Terms and privacy notices linked before explicit consent [ ] Receipt/invoice accuracy reviewed with accounting owner ACCESSIBILITY [ ] Semantic headings, labels and status announcements [ ] Keyboard-accessible docs navigation, modals, copy and search [ ] Visible focus; contrast in light and dark themes [ ] Mobile layouts, Safari compatibility and screen-reader tests [ ] Errors actionable without color alone This is a checklist, not a certification or legal opinion. ~~~~ ## Developer FAQ — edge cases and implementation decisions Link: https://payoptimum.org/developer-docs#faq-integration Short answers to common architecture questions. Review the exact source implementation for definitive endpoint fields or activation status. ### Engineering decision guide ~~~~text Should a merchant pick LIVE or SANDBOX in the browser? They may request a mode, but the backend must check authorization. Can PaymentHub be used for Stripe customers' charges? No. Merchant Stripe transactions remain on the merchant's own Stripe. Can the frontend mark a transaction paid? No. Only trusted backend payment status and signed events. Can a paid invoice be created after pressing Subscribe? No. Current action records pending_billing only. Does a HTTP 200 page prove the product is functional? No. It may still fail on auth, JS loading or provider API. Is a secret in a JS environment variable protected? No, if bundled to the browser. Use server-only secure storage. Can we use one merchant ID for every customer? No. Merchant identity must be server-resolved and authorized. What if a webhook arrives before the browser redirect? Verify and store it; status is authoritative independent of browser. What if the same webhook is delivered twice? Persist unique event key, process once, acknowledge duplicates safely. What if LIVE_CLIENT_ENABLED is true? Continue all other LIVE readiness checks. It is necessary, not sufficient. Should we paste sample API snippets into production? Only after matching the actual deployed OpenAPI contract and tests. ~~~~ # VOLUME 11 — Going Live with PayFlow ## Going Live with PayFlow Link: https://payoptimum.org/developer-docs#going-live-with-payflow Production deployment handbook. The eight section titles and order below come from the supplied PayFlow documentation table of contents; the implementation procedures and code examples in this volume are additional PayOptimum guidance, not a recovered copy of the original source text. Publication of this guide does not authorize a LIVE payment or bypass any processor control. ### Table of Contents — original sequence ~~~~text 1. Overview 2. Pre-Deployment Checklist 3. Environment Setup 4. Security Configuration 5. Performance Optimization 6. Monitoring Setup 7. Deployment Strategies 8. Post-Deployment This section is a release playbook, not an approval to enable LIVE. Use each chapter as an engineering acceptance gate. ~~~~ ### Production release policy ~~~~text Go-live has three separate dimensions: • UI deployed and accessible • Backend correct, isolated and secure • LIVE processor and client authorization independently verified All must pass. A deployed dashboard, health endpoint, TEST payment, key vault, or LIVE_CLIENT_ENABLED flag alone is NOT proof of a successful LIVE charge. Do not merge Stripe Adapter V4 merchant transactions with native PayFlow processing. No unknown/default merchant, no unsigned webhook, no blind retry. ~~~~ ## Overview Link: https://payoptimum.org/developer-docs#going-live-overview Define the product, merchant identity, payment processor, intended environment and expected outcome before deploying. PayFlow native checkout (Aurora Classic or Aurora Pro) and Stripe Adapter V4 are different offerings. The merchant's own Stripe account processes their customers' charges for V4, while PayFlow charges the separate monthly add-on fee through its authorized billing workflow. ### Release scope and ownership ~~~~text Document before any deployment: Product: PayFlow native Aurora Classic / Aurora Pro OR Stripe Adapter V4. Release version: exact commit, Pages/Worker release ID, tested rollback ID. Merchant: mapped from signed-in account by trusted backend; never 'default'. Processor: PayFlow-controlled LIVE PaymentHub OR merchant-owned Stripe. Environment: sandbox / TEST / production, with independent credentials. Billing: amount, currency, taxes, intervals, settlement and invoice ownership. Owner: developer + finance reviewer + authorized LIVE approver. Definition of done: signed payment evidence and merchant-isolation tests. No claims of 'operational LIVE' based only on the UI or successful build. ~~~~ ## Pre-Deployment Checklist Link: https://payoptimum.org/developer-docs#pre-deployment-checklist Run an explicit go/no-go review before promoting any payment-capable release. Verify endpoint contracts, order integrity, scope-based access, signed callbacks, safe rollback and the accounting workflow. Test at least two merchants with distinct records, even when the two merchants share an email or device. ### Mandatory production readiness checklist ~~~~text [ ] Verify exact source commit, manifest, deployed host and API inventory. [ ] Confirm independent architecture for native PayFlow vs Stripe V4. [ ] Confirm the applicable processor account and written authorization. [ ] Verify merchant server mapping, roles/scopes and deny-by-default RLS. [ ] Confirm product, amount_minor, currency and taxes from trusted order data. [ ] Test 401/403/409/429/5xx, no merchant default and no data crossover. [ ] Verify idempotency keys and double-click/retry deduplication. [ ] Verify webhook signature, timestamp, replay, delivery and reordering. [ ] Confirm processor status independently before marking paid. [ ] Test failure, cancellation, refund, partial/async payment scenarios. [ ] Prove client-specific LIVE_CLIENT_ENABLED and separate LIVE approval. [ ] Verify audit logs, monitoring, alerts and rollback scripts. [ ] Have a named operator sign off before any LIVE activation. Any critical unchecked item => NO-GO for LIVE. ~~~~ ### Example release gate response (illustrative) ~~~~json { "product": "payflow-native-aurora-pro", "environment": "production", "release_gate": "NO_GO", "checks": { "authenticated_merchant_mapping": "unverified", "live_client_enabled": "unverified", "processor_ready": "unverified", "signed_webhooks": "unverified", "two_merchant_isolation": "unverified", "rollback_ready": "unverified" }, "safe_to_capture_real_money": false } ~~~~ ## Environment Setup Link: https://payoptimum.org/developer-docs#environment-setup Separate the build, secrets, state, URLs and event handlers for TEST and LIVE. PayFlow Sandbox remains test-only. PaymentHub is the PayFlow LIVE-only processor in the project architecture (payflowbuzz-canada, project-owner reported). For Stripe Adapter V4, each merchant retains their own Stripe account and an independently verified connection. Never copy TEST keys or data into the LIVE environment. ### Environment variable names — no real values ~~~~env # Server-only configuration template — verify with the deployed contract. PAYFLOW_ENVIRONMENT=sandbox PAYFLOW_API_BASE_URL=https://api.payflow.buzz PAYFLOW_API_KEY=SERVER_SECRET_STORE_REFERENCE PAYFLOW_MERCHANT_ID=RESOLVED_ON_TRUSTED_SERVER PAYFLOW_WEBHOOK_SECRET=SERVER_SECRET_STORE_REFERENCE PAYFLOW_PROCESSOR_MODE=TEST # Production is a separate reviewed deployment and secret configuration. # Do NOT set LIVE_CLIENT_ENABLED from a frontend, .env.example or prompt. # The trusted backend must check the authorized client's LIVE status. # Do not expose provider credentials through Vite PUBLIC_/VITE_ variables. ~~~~ ### Environment parity and isolation tests ~~~~text TEST / SANDBOX - Use only test products and accounts. - Verify disabled LIVE APIs and TEST-only accounting records. - Ensure TEST webhooks cannot mark production orders paid. LIVE / PRODUCTION - Distinct, approved secrets and processor account. - Verified client authorization with LIVE_CLIENT_ENABLED check. - Explicit deployment, compliance and rollback approvals. - Signed production webhook, independent status check and ledger. Cross-environment requests must fail closed, not silently downgrade or upgrade. ~~~~ ## Security Configuration Link: https://payoptimum.org/developer-docs#security-configuration Treat payment and merchant identity as security-sensitive backend state. Enforce authenticated sessions, tenant-scoped authorization, provider-specific webhook signatures, replay protection, least privilege, key rotation, encryption and auditability. Avoid collecting raw card data in custom HTML, billing tools or AI builder prompts. ### Production security acceptance rules ~~~~text - Merchant identity always resolved server-side from verified session. - Reject client-supplied merchant_id, paid, live, amount and permissions. - Validate order ownership; never use an implicit 'default' merchant. - Scope every DB query and background job to verified merchant context. - Use approved hosted payment fields; never store PAN/CVV. - Server-only bearer/HMAC keys, rotated and audited. - Verify each provider's exact webhook signature over raw request bytes. - Persist event ID or nonce atomically, reject replays and cross-merchant events. - Set strict CORS and CSP; avoid wildcard origins for authenticated APIs. - Mask personal data and secrets in logs, alerts, screenshots and docs. - Use short-lived access tokens, role checks, CSRF and session protections. - Verify LIVE eligibility and kill switch server-side before real charges. ~~~~ ### Fail-closed payment eligibility guard (illustrative) ~~~~typescript function assertLiveCheckoutAllowed(ctx: { merchantVerified: boolean; liveClientEnabled: boolean; processorApproved: boolean; webhookVerified: boolean; releaseAuthorized: boolean; }) { if (!ctx.merchantVerified || !ctx.liveClientEnabled || !ctx.processorApproved || !ctx.webhookVerified || !ctx.releaseAuthorized) { throw new Error('LIVE_CHECKOUT_NOT_AUTHORIZED'); } } // This is a policy example, NOT an enabled PayFlow payment endpoint. // Check actual authorization in trusted backend for the specific merchant. ~~~~ ## Performance Optimization Link: https://payoptimum.org/developer-docs#performance-optimization Optimize payment pages without weakening correctness. Cache public assets, not credentials or dynamic payment decisions. Measure checkout loading, latency, provider timeouts and webhook queues. Retry idempotent operations with backoff, but never blindly duplicate a real payment request. ### Performance and reliability review ~~~~text [ ] Optimize assets, fonts, images and mobile network waterfalls. [ ] Serve static docs and design assets with controlled browser caching. [ ] Use no-store for authenticated sessions, payment status and secrets. [ ] Define provider request timeout and a bounded retry policy. [ ] Use stable idempotency keys for checkout, subscriptions and refunds. [ ] Handle webhook retry bursts with a durable queue and dedupe storage. [ ] Protect DB indexes for (merchant_id, order_id, status, event_id). [ ] Run load tests with TEST accounts only; no synthetic LIVE charges. [ ] Track p50/p95/p99 latency and browser Web Vitals separately. [ ] Test failure/recovery: delayed provider, duplicate event, network loss. Avoid cache poisoning: one tenant must never receive another tenant's response. ~~~~ ### Request cache hints (illustrative HTTP) ~~~~text GET /public-static-documentation Cache-Control: public, max-age=300 GET /authenticated/merchant-payment-status Cache-Control: no-store Vary: Authorization, Cookie POST /verified-provider-payment Idempotency-Key: server-generated-stable-value Cache-Control: no-store Above paths are conceptual examples, not deployed PayFlow routes. ~~~~ ## Monitoring Setup Link: https://payoptimum.org/developer-docs#monitoring-setup Build observability from browser to provider and ledger. Track normalized request IDs, endpoint errors, merchant-scoped payment state, webhook delivery/replay, processor connection, refunds and reconciliation. Separate TEST and LIVE dashboards and alerting. ### Production monitoring dashboard ~~~~text REQUESTS - API 2xx/4xx/5xx, request correlation, p95 duration, timeouts - Auth failures, merchant mapping rejection and scope misuse PAYMENTS - Created checkout sessions vs paid transactions - Pending/failed/refunded payments, duplicates and status divergence - Idempotency collisions, provider errors and webhook replay rejects INTEGRATIONS - Provider and webhook availability, signature verification, retry backlog - LIVE_CLIENT_ENABLED status changes, unexpected LIVE attempts - D1/DB availability, latency, usage and migration health OPERATIONS - Alert escalation owner, runbook links, rollback ID, release version - Redacted audit trails for production and separate TEST environment - Human approval and UBS/Xero matching status where applicable Alert critically on cross-merchant data leakage or unexpected LIVE charge. ~~~~ ### Minimal redacted alert example ~~~~json { "severity": "critical", "service": "payflow-checkout", "environment": "production", "event": "unexpected_live_processing_attempt", "merchant_ref": "server-side-scoped-or-hashed-id", "request_id": "opaque-trace-id", "processor_status": "not_authorized", "action": "block_and_escalate", "secret_values": "never logged" } ~~~~ ## Deployment Strategies Link: https://payoptimum.org/developer-docs#deployment-strategies Use an approved, reversible deployment sequence. Cloudflare Workers/Pages routing may coexist with PayOptimum Base44. Preserve the current live routing inventory, payment Workers and independent native/Stripe boundaries. Promote immutable code and configurations only after staging acceptance tests. ### Suggested deployment sequence ~~~~text 1. Snapshot current routes, Worker bindings, D1 schema and secret names. 2. Record immutable release IDs and verified rollback target. 3. Build docs and static UI; run lint, typecheck and route link tests. 4. Deploy to TEST with controlled merchant identities. 5. Validate checkout redirects, real API paths and signed webhook tests. 6. Run two-merchant isolation, replay, concurrency and failure tests. 7. Freeze build/version; obtain processor and production authorization. 8. Canary release to eligible client(s) only; verify LIVE_CLIENT_ENABLED. 9. Watch health, webhook lag, reconciliation and audit trail. 10. Expand only after metrics and real payment evidence are reviewed. Never overwrite Stripe Adapter configuration with native Aurora bindings. Never change a LIVE Worker simply because a docs page was deployed. ~~~~ ### Rollback checklist ~~~~text ROLLBACK TRIGGER: unexpected charge, wrong merchant, failed signature verification, broken checkout, ledger mismatch or unacceptable error rate ACTION: stop new LIVE sessions with server kill switch; preserve audit logs and idempotency/event state; restore previous verified deployment and routing; reconcile already-in-flight payment events; retest before re-enabling client eligibility. A frontend rollback does not undo a processor charge already captured. ~~~~ ## Post-Deployment Link: https://payoptimum.org/developer-docs#post-deployment Finish production verification after the release, not just at publish time. Confirm the deployed version, application routes, provider callback connectivity, merchant isolation, accounting outputs and operational escalation paths. Real settlements require trusted processor evidence and financial controls. ### Post-release acceptance ~~~~text [ ] Confirm new URLs (public docs, dashboard, checkout, support). [ ] Verify correct source hash and published release version. [ ] Retest logged-out, merchant A, merchant B and admin contexts. [ ] Verify approved LIVE eligible merchant without using defaults. [ ] Confirm signed provider callback and status reconciliation. [ ] Confirm exactly one invoice/receipt for each verified billing event. [ ] Confirm no TEST transactions appear in production reporting. [ ] Verify cancellations, refunds, subscription renewals and retries. [ ] Confirm support escalation, alerts, kill switch and rollback readiness. [ ] Archive approval, test evidence, incidents and change log. If live processor status is unknown, label the system pending/unverified. ~~~~ ### Final release report template ~~~~text Product: Environment: Release commit/version: Source and route inventory: Processor authorization evidence: LIVE_CLIENT_ENABLED check location and result: Merchant isolation A/B evidence: Webhook test and replay evidence: Verified payment status evidence: Billing/receipt reconciliation: Monitoring and alert owner: Rollback target: Go/No-go decision and reviewer: Open risks: Do not record a GO until proof exists for all critical gates. ~~~~ # VOLUME 12 — API Reference and Source Notes ## Overview Link: https://payoptimum.org/developer-docs#overview The PayFlow developer workflow is server-first. This preview documents the integration architecture and preserves links to existing guides. It is not a verified copy of the complete legacy developer manual. ## Environment & configuration Link: https://payoptimum.org/developer-docs#configuration Store credentials on a trusted server. Do not expose API keys, payment processor secrets, or internal assertions to the browser. ### .env.example — full template (nonfunctional placeholders) ~~~~env PAYFLOW_API_BASE_URL=https://api.payflow.buzz PAYFLOW_API_KEY=REPLACE_WITH_SERVER_SIDE_SECRET PAYFLOW_ENVIRONMENT=sandbox PAYFLOW_MERCHANT_ID=REPLACE_WITH_VERIFIED_MERCHANT_ID PAYFLOW_WEBHOOK_SECRET=REPLACE_WITH_SECRET PAYFLOW_REDIRECT_SUCCESS_URL=https://your-site.example/payments/success PAYFLOW_REDIRECT_CANCEL_URL=https://your-site.example/payments/cancel ~~~~ ## Health & readiness Link: https://payoptimum.org/developer-docs#health The public health endpoint is a reference for service readiness. Do not interpret a healthy API response as proof that live card processing is enabled. ### Check the public PayFlow health route ~~~~bash curl --fail-with-body --silent --show-error \ --request GET \ --header 'Accept: application/json' \ 'https://api.payflow.buzz/v1/health' ~~~~ ## Checkout integration Link: https://payoptimum.org/developer-docs#checkout Illustrative server-side flow. Exact checkout endpoint and request fields require confirmation against the deployed PayFlow API contract. Never consider a browser redirect sufficient proof of payment. ### Node.js — illustrative server endpoint (adapt endpoint to verified API) ~~~~javascript import express from 'express'; const app = express(); app.use(express.json()); // Demo integration: replace endpoint and JSON fields with the validated // PayFlow API contract before using it with a real merchant. app.post('/api/start-checkout', async (req, res) => { try { const { orderId } = req.body; if (typeof orderId !== 'string' || !orderId.trim()) { return res.status(400).json({ error: 'ORDER_ID_REQUIRED' }); } // Look up the order and merchant in your own trusted database. const order = await loadTrustedOrder(orderId); if (!order) return res.status(404).json({ error: 'ORDER_NOT_FOUND' }); const response = await fetch( process.env.PAYFLOW_API_BASE_URL + '/REPLACE_WITH_VERIFIED_CHECKOUT_ROUTE', { method: 'POST', headers: { 'Content-Type': 'application/json', Authorization: 'Bearer ' + process.env.PAYFLOW_API_KEY, 'Idempotency-Key': 'checkout-' + order.id, }, body: JSON.stringify({ order_id: order.id, merchant_id: order.verifiedMerchantId, amount_minor: order.amountMinor, currency: order.currency, }), } ); const payload = await response.json(); if (!response.ok) { return res.status(502).json({ error: 'PAYFLOW_CHECKOUT_FAILED' }); } return res.status(200).json(payload); } catch { return res.status(500).json({ error: 'CHECKOUT_START_FAILED' }); } }); // Supply this function from your own authenticated database layer. // Never accept amount or merchant identity directly from browser input. async function loadTrustedOrder(orderId) { throw new Error('Implement trusted order lookup for ' + orderId); } app.listen(3000); ~~~~ ## Payment status Link: https://payoptimum.org/developer-docs#payment-status Verify payment status on your backend using the documented, authenticated status endpoint. Only authoritative server evidence can mark an order paid. ### TypeScript — status handling (illustrative contract) ~~~~typescript type PaymentState = | 'pending' | 'processing' | 'paid' | 'failed' | 'refunded'; interface VerifiedPayment { orderId: string; merchantId: string; state: PaymentState; verifiedByServer: boolean; } export function mayFulfillOrder(payment: VerifiedPayment): boolean { return payment.state === 'paid' && payment.verifiedByServer; } export function assertMerchantIsolation( payment: VerifiedPayment, expectedMerchantId: string ): void { if (payment.merchantId !== expectedMerchantId) { throw new Error('MERCHANT_CONTEXT_MISMATCH'); } } // This models a policy only; it does not call the live PayFlow API. ~~~~ ## Webhooks & signatures Link: https://payoptimum.org/developer-docs#webhooks A webhook consumer must verify the signature using the actual deployed signing specification and reject replays before applying any state change. The example below deliberately does not pretend to implement an unverified signature contract. ### Webhook verification checklist — TypeScript guard ~~~~typescript import type { Request, Response } from 'express'; export async function receivePayflowWebhook( req: Request, res: Response ): Promise { const rawBody = req.body as Buffer; const signature = req.header('x-payflow-signature'); if (!Buffer.isBuffer(rawBody) || !signature) { res.status(400).send('INVALID_WEBHOOK_ENVELOPE'); return; } // Use the exact, published PayFlow signing contract. // Implement independently verified signature, timestamp window, // replay store, authenticated merchant mapping and idempotent update. // Fail closed until that contract has been verified. res.status(503).send('WEBHOOK_VERIFICATION_NOT_CONFIGURED'); } // Do not deploy this template as a live webhook consumer. ~~~~ ## Seven-stage payment pipeline Link: https://payoptimum.org/developer-docs#pipeline The seven-stage diagram is illustrative and must not be interpreted as evidence of a live payment. The phases shown on the current Platform preview are below. ### Seven-stage checklist ~~~~text 01 Validate request merchant / amount / currency 02 Risk & fraud review server-side controls 03 Authorization provider or bank authorization gate 04 Secure handoff hosted payment experience 05 Settlement review reconciliation and verification 06 Audit trail idempotency and event history 07 Verified confirmation signed server-side evidence SANDBOX CONCEPT ONLY — no transfer is triggered by this page. ~~~~ ## Sandbox & production Link: https://payoptimum.org/developer-docs#sandbox Keep sandbox credentials separate from production. Manual bank-transfer approval does not imply a payment has settled. Do not enable live card flow without processor confirmation. ### Environment separation (illustrative) ~~~~typescript export function resolveEnvironment(value: unknown) { if (value !== 'sandbox' && value !== 'production') { throw new Error('PAYFLOW_ENVIRONMENT_INVALID'); } return { mode: value, live: value === 'production', // Live enablement must be established by a trusted backend. cardProcessingEnabled: false, } as const; } ~~~~ ## Angel 2.0 CFO — finance and reconciliation node Link: https://payoptimum.org/developer-docs#angel-cfo Architecture and responsibilities (design brief, not a verified live connector): Angel 2.0 CFO is the finance-assistance node linking merchant-scoped checkout events, PayFlow Billing, invoice and Xero workflows, and UBS bank-transfer reconciliation. It may propose matches and flag anomalies; only trusted backend evidence and required human approval can mark a bank transfer as paid. The classic Aurora Builder and Checkout Pro Aurora Builder must both emit a server-verified merchant context and never submit raw card data to Angel. Sandbox results must never be booked as LIVE settlement. Collaboration with the actual Angel 2.0 service is not yet connected or confirmed. ### Angel 2.0 CFO — integration node (illustrative contract, not deployed) ~~~~typescript // DESIGN CONTRACT — not a published PayFlow endpoint. type FinanceReviewRequest = { merchantId: string; // derived from verified server identity environment: 'sandbox' | 'production'; paymentReference: string; invoiceReference?: string; processorStatus: 'pending' | 'confirmed' | 'failed'; }; type FinanceReviewResult = { recommendation: 'match' | 'investigate' | 'reject'; evidenceReferences: string[]; requiresHumanApproval: boolean; }; // Application server responsibilities: // 1. Authenticate merchant and enforce per-merchant data isolation. // 2. Validate signatures, idempotency and source event freshness. // 3. Pass references and minimal finance data, never card numbers/CVV. // 4. Keep bank transfers pending until independently verified. // 5. Require an authorized human to approve where policy requires. // 6. Record an immutable audit trail; no automatic LIVE activation. ~~~~ ## Stripe Adapter V4 — test-only API contract (Angel 2.0 review) Link: https://payoptimum.org/developer-docs#stripe-adapter-verified Source: Angel 2.0 CFO diagnostic reported 14 November 2026, 19:06 UTC. Scope is the staging Stripe Adapter, not the full PayFlow API. Staging base URL: https://stripe-staging.payflow.buzz. Available routes reported: GET /v1/health, POST /v1/connect/oauth/start, GET /v1/connect/status, POST /v1/connect/disconnect, POST /v1/checkout/sessions, GET /v1/payments, GET /v1/transactions. Request signing uses HMAC-SHA256 over a canonical body and timestamp with a five-minute skew limit, plus a server-held bearer token; never calculate a signature or expose the token in browser JavaScript. OAuth state is valid for 15 minutes and single-use. Pagination reports up to 50 rows with next_cursor and has_more. The contract is reported by Angel, not independently proven end-to-end. ### Checkout session input constraints — observed contract (not a successful payment example) ~~~~json { "amount": "integer minor units, 1..100000000", "currency": "usd | chf | eur | gbp", "description": "required, 1..120 characters", "idempotency_key": "required, 16..120 characters, characters A-Z a-z 0-9 _ -" } ~~~~ ### Response states and server-side confirmation ~~~~text ok — success not_activated — server credentials missing not_connected — merchant connection inactive bad_request — validation failed invalid_state — OAuth state invalid/expired conflict — HTTP 409 unavailable — adapter or upstream unavailable live_blocked — production-mode data refused error — internal failure Browser redirect to success_url is NOT proof of payment. Only server-side verified paymentStatus may confirm payment. Accepted terminal values reported: paid, succeeded, completed, complete. Webhook endpoint reported: /functions/stripeAdapterWebhook. Webhook end-to-end processing: NOT VERIFIED (zero stored events at review). ~~~~ ## Angel 2.0 CFO — verified scope and publication constraints Link: https://payoptimum.org/developer-docs#angel-cfo-findings Based on Angel 2.0 CFO's diagnostic of its accessible Base44 modules on 14 November 2026, not an independent audit of PayFlow core. Angel can read its merchant-scoped Transaction, Subscription, Expense, Client, BusinessSettings, StripeConnection and StripeAdapterEvent entities; it can create/update transactions and update subscriptions, but cannot delete records, approve refunds or submit tax filings. Values of secrets are not readable. The Stripe Adapter is activated for TEST only; LIVE is explicitly blocked, and the observed merchant connection was not yet active. Neither the OAuth-to-payment journey nor the webhook was verified end-to-end. An activation feature flag is not a security boundary. Invoice PDFs, receipts and automated retries are not proven by database fields alone. Angel cannot verify Checkout Pro V7, Aurora Builder Classic or Pro, card-field tokenization or PCI scope, UBS or Xero integrations. Do not describe these functions as operational without code and integration evidence. ### Documentation readiness checklist — Angel 2.0 CFO review ~~~~text [ ] Core PayFlow OpenAPI specification and route inventory verified [ ] Checkout Pro V7 specification and test results [ ] Aurora Builder Classic & Pro implementation inventory [ ] Card fields: hosted-field provider, tokenization contract, PCI DSS scope [ ] Merchant isolation and authorization tests across two merchants [ ] OAuth connection test and successful sandbox checkout [ ] Signed webhook delivery, retry/replay and event retention tested [ ] Billing: receipts/PDFs and retry automation actually demonstrated [ ] UBS human approval / dual-control audit trail confirmed [ ] Xero sync and reconciliation interface confirmed [ ] Currency defaults, conversions and rounding policy documented [ ] KYC, disputes, refund approvals and go-live controls approved Do not expose customer records, merchant identifiers, secrets or account balances in public documentation. No claim of '100% complete' or LIVE card payments until each item is supported by evidence. ~~~~ ## Xero Partner 2.0 — integration status and accounting scope Link: https://payoptimum.org/developer-docs#xero-partner-review Source: Xero Partner 2.0 technical/accounting review, 14 November 2026, 19:13 UTC, limited to its PayOptimum admin workspace. The Xero Partner assistant can inspect workspace records and propose accounting review, but reported NO ACTIVE Xero OAuth connector, token exchange, invoice/contact/journal synchronization, or Xero webhook in its accessible environment. UBS statement ingestion and three-way bank reconciliation were likewise not available to it. Billing records, invoice references, subscription schedules and configured tax rules exist; this does NOT prove PDF receipt generation, document delivery, posted journal entries, automated retries, tax calculations per invoice line, or bank settlement. Multi-currency flows were not observed in the reviewed CHF-only dataset. These are environment-scoped findings, not proof that every external PayFlow deployment lacks a connector. ### Published capability matrix — review scope, not a live uptime guarantee ~~~~text Xero OAuth / Xero synchronization: NOT CONNECTED in reviewed workspace Xero webhooks and OAuth code contract: NOT VERIFIED UBS statement feed / CAMT import: NOT CONNECTED in reviewed workspace Three-way bank reconciliation: NOT DEMONSTRATED Billing ledger & invoice references: OBSERVED Subscription schedules: OBSERVED; automatic collection not demonstrated Receipt/PDF generation and delivery: NOT VERIFIED VAT rules: CONFIGURED; per-invoice tax calculation NOT VERIFIED Automatic retries and collection workflow: NOT DEMONSTRATED Multi-currency processing: NOT TESTED in reviewed CHF dataset Checkout Pro V7 / Aurora Builder Classic / Pro: OUTSIDE reviewer access Stripe Adapter: STAGING / TEST ONLY; LIVE BLOCKED Webhook configuration present; end-to-end event delivery NOT VERIFIED Never equate an internal transaction status with settlement by a bank. ~~~~ ## Delegated merchant analytics — observed assertion contract Link: https://payoptimum.org/developer-docs#delegated-analytics-contract Xero Partner 2.0 reports an existing PayOptimum-to-PayFlow analytics assertion using RS256. The server signs short-lived assertions with issuer base44-payoptimum, audience payflow-analytics, scope analytics:read and key identifier payoptimum-v1; lifetime is no more than 60 seconds. Reported merchant analytics paths at https://api.payflow.buzz: GET /v1/analytics/merchant/summary, /payments, /subscriptions, /customers. This is a reported integration contract, not evidence that settlement is verified or that merchant isolation has passed a two-merchant security test. Do not generate JWTs or handle signing keys in the client. ### Delegated analytics JWT claim shape (illustrative only; server-signed) ~~~~json { "alg": "RS256", "kid": "payoptimum-v1", "iss": "base44-payoptimum", "aud": "payflow-analytics", "scope": "analytics:read", "exp": "server time + <=60 seconds", "note": "Signed and validated on trusted server only; merchant identity must be derived from authenticated context." } ~~~~ ## Accounting controls — deployment and documentation prerequisites Link: https://payoptimum.org/developer-docs#accounting-control-readiness Xero Partner 2.0 identifies outstanding controls that must be documented and evidenced before describing finance functions as fully reconciled: one authoritative transaction ledger; a database uniqueness constraint for merchant/provider/currency transaction identity; three-way reconciliation (UBS bank statement ↔ processor settlement batch ↔ invoice); VAT amounts stored per invoice line; a two-merchant isolation test including revoked access; human authorization with immutable audit trail; and strict TEST versus LIVE data labels. Recommended additional documentation includes currency conversion rates with dates and sources, refunds/chargebacks, versioned fee schedules, subscription retry history, daily completeness checks and legally compliant invoice retention. These are review recommendations, not claims of completed implementation. ### Finance documentation checklist (control requirements, not deployed features) ~~~~text [ ] Canonical transaction source and database idempotency constraint [ ] UBS statement ↔ processor batch ↔ invoice reconciled and evidenced [ ] Tax rate, taxable base, amount and tax regime saved per invoice line [ ] Merchant A / Merchant B data isolation and revoked access tested [ ] Human approval identity, signed journal entries and immutable audit history [ ] Production metrics separate from staging and sandbox records [ ] Currency, FX rate source, timestamp and rounding rules published [ ] Refund and chargeback life cycle traced to original transaction [ ] Merchant-specific versioned commission/fee contract [ ] Recurring due dates, failed charges, retries and alerts verified [ ] Daily API ↔ ledger ↔ settlement reconciliation monitoring [ ] Invoice retention, tamper evidence and applicable legal policy checked Status: prerequisites to evidence; NOT proof of any active payment or bank settlement. ~~~~ ## AI Builder installation — original integration contract (19 October 2026) Link: https://payoptimum.org/developer-docs#builder-install-source-contract Source: supplied PayFlow guide 'AI builder installation / Build Checkout API', dated 19 October 2026. This is a source-derived implementation guide, not a current LIVE certification. The guide describes an owner-authorized integration through a private application backend; it explicitly says the NEW Origin administration release was prepared but not deployed by its author and that independent merchant credentials were not issued in that release. A static frontend is insufficient. Installation manifest proposed by source: https://api.payflow.buzz/.well-known/payflow-installation.json; reference settings: https://api.payflow.buzz/docs/settings. Product/pricing administration is described at https://origin.payflow.buzz/. Treat availability and deployment of each URL as unverified until tested. ### Server-only PayFlow session and hosted checkout flow — source contract ~~~~text 1. Application backend authenticates a REAL existing customer. 2. Resolve catalogue product, authorized merchant and price on server. 3. POST https://api.payflow.buzz/api/auth/session Authorization: Bearer Content-Type: application/json Body: {} Save payflow_session from Set-Cookie privately on server. 4. POST https://api.payflow.buzz/checkout Cookie: payflow_session= Idempotency-Key: Body: {product_id, customer_name, customer_email} 5. Validate returned HTTPS checkout_url, transactionId, amount in minor units, currency and creation status. 6. Confirm processor capture with server verification and signed webhook before granting product/service access. A checkout URL or a success redirect is NOT payment confirmation. This guide states the owner credential is not scoped to independent merchants. Never put an owner-wide credential in browser, generated frontend code or logs. ~~~~ ### Client application bridge — source code excerpt (requires actual adapters) ~~~~javascript const handlePayflow = createMerchantBridge({ formHtml, authenticate: authenticateExistingCustomer, loadOrder: loadOrderFromDatabase, saveCheckout: mergeCheckoutIntoOrderAtomically }); const response = await handlePayflow(request, serverEnvironment); if (response) return response; return existingRouter(request); // These adapters are application requirements, not supplied mock implementations. ~~~~ ### Start checkout from authenticated application — source request ~~~~http POST /payflow/start Content-Type: application/json {"order_id":"persisted_order_id"} Expected server navigation: 303 to /payflow/checkout?order_id=... Validate that this order belongs to the authenticated customer. Browser never supplies the trusted price, merchant identity or amount. ~~~~ ## Seven-stage checkout, card fields and verification — source requirements Link: https://payoptimum.org/developer-docs#builder-install-secure-state The supplied guide requires preserving the original seven-step visual checkout and receipt design. Secure card fields must be processor-hosted iframes: application code must not collect or retain raw PAN or CVV. The merchant bridge must store sessions and idempotency keys durably, use CSRF defenses and rate limiting, serialize initialization per order, reject cross-customer access and refuse any transaction mismatching approved product, amount or currency. Licence delivery depends on verified capture and signed webhook evidence; the guide itself does not generate licence keys. Periodic price labels do not activate recurring payments. Bank transfer and SEPA Direct Debit are not enabled by this particular card bridge. ### Seven-step experience — evidence-backed state machine from source guide ~~~~text 01 Validation — catalogue, ownership, amount and idempotency checked. 02 Anti-Fraud (5 layers) — UNVERIFIED without a real evaluator. 03 Authorization (Angel 2.0) — policy, payer approval, verified capture. 04 Bank Transfer (UBS / SIC) — PENDING until verified bank execution. 05 Settlement — PENDING until independently reconciled. 06 Audit Trail — immutable, verified capture record. 07 Final Confirmation — verified capture AND signed webhook receipt. No fulfilment from browser callback or redirect alone. CardFields eligibility/currency failure must block the attempt. Do not claim UBS/SIC, Xero or LIVE settlement from a hosted-card capture. ~~~~ ### Source installation validation checks ~~~~text [ ] Missing server secret returns setup error. [ ] Missing authenticated user returns HTTP 401. [ ] Another customer's order cannot be accessed. [ ] Product / amount / currency mismatch is rejected. [ ] Double click and retry use the SAME idempotency key and transaction. [ ] Integration does not unlock Angel finance controls. [ ] Ineligible hosted CardFields or currency returns a real error. [ ] Capture without signed webhook stays pending. [ ] Invalid webhook signature never grants fulfilment. [ ] Unconnected banking/accounting steps remain pending. [ ] Desktop and mobile match reference checkout design. [ ] Distinguish local mock, deployed test and real processor evidence. No unattended LIVE charge during installation. ~~~~ ## Builder source files, deployment boundaries and release caveats Link: https://payoptimum.org/developer-docs#builder-deployment-inventory The original guide identifies client-checkout.html and merchant-bridge.mjs as source assets to obtain from the installation manifest, with SHA-256 hashes checked before installation. The bridge runs only server-side and relies on real, durable authenticate(), loadOrder() and saveCheckout() implementations. It also references INSTALLATION-ORIGIN.md, a separate payflow-proxy menu patch and prospective routes /docs/ai-builder, /docs/administration and /docs/client-checkout after deployment. These are release instructions, not proof that the release has actually shipped. It states PAYFLOW_SECRET_KEY may be an application-side variable name only when its secret value equals the deployed PAYMENT_API_INTERNAL_KEY. Other processor secrets remain in the PayFlow Worker; no actual values are shared. ### Manifest and server-adapter inventory — source reference ~~~~text Installation manifest (source-listed): https://api.payflow.buzz/.well-known/payflow-installation.json Assets referenced (download and SHA-256 verify): client-checkout.html merchant-bridge.mjs INSTALLATION-ORIGIN.md Required adapter interfaces: authenticate(request) — real authenticated customer, server-controlled ID loadOrder(id) — owner, product, minor-unit price, currency, customer fields, persisted idempotency key saveCheckout(id,patch) — atomic durable merge including session state Do not copy owner-wide credentials into independent-merchant projects. Separate merchants need distinct authorized processor and data scopes. Deployment and LIVE readiness were not proven by the supplied source. ~~~~ ## Published product navigation — Stripe Adapter V4 and Aurora V7 Link: https://payoptimum.org/developer-docs#published-product-navigation PayOptimum application source includes dedicated Stripe Adapter screens for connection, overview, checkout sessions, payments, transactions and activity. These routes are UI screens, NOT proof of enabled LIVE processing. The PayFlow service directory also links to a separately hosted Checkout Pro Aurora Builder V7 design studio; its own directory entry says payment processing is not enabled. A separate classic Aurora Builder route or implementation has not yet been located in the inspected PayOptimum app. Do not conflate a published user interface with a verified processor integration; the exact classic builder URL and V7 production contract require confirmation. ### Confirmed application routes and known design-studio URL ~~~~text PayOptimum Stripe Adapter V4 screens: https://payoptimum.org/stripe-adapter https://payoptimum.org/stripe-adapter/overview https://payoptimum.org/stripe-adapter/checkout-sessions https://payoptimum.org/stripe-adapter/payments https://payoptimum.org/stripe-adapter/transactions https://payoptimum.org/stripe-adapter/activity Checkout Pro Aurora Builder V7 design studio (linked in app directory): https://payflow-aurora-builder-v7.nagle-b42.workers.dev/ Status recorded in directory: SANDBOX / no enabled payment processing. Aurora Builder classic: separate published route not identified in inspected app. Hosting a design studio or dashboard is not evidence of LIVE card processing. ~~~~ ## PayFlow documentation directory Link: https://payoptimum.org/developer-docs#integration-resources Central directory of the existing PayFlow documentation pages. These links open their original guides until each complete source page has been migrated and checked in the PayOptimum design. --- END OF REFERENCE — Verify merchant/client eligibility and all provider contracts independently before LIVE.