The developer
reference library.

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.

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.

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

[ ] 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.

[ ] 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.

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.

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.

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.

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.

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.

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.

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.

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.

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

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

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.