cabloy 5.1.134 → 5.1.136

package/cabloy-docs/fullstack/a-pay-payment-suite.md

@@ -0,0 +1,333 @@
+# A-Pay Payment Suite
+
+This guide explains the current payment architecture in Cabloy Basic across Vona, Zova, and the Commerce domain.
+
+It is a source-oriented architecture guide for:
+
+- application authors integrating a payment scene;
+- provider-module authors implementing a payment adapter;
+- Zova developers consuming payment-session state and next actions;
+- maintainers tracing callbacks, webhooks, settlement, and SSR return flows.
+
+This is **not** a production rollout manual or payment-provider compliance guide. It does not include real credentials, account identifiers, domains, tunnel commands, or internal operational diagnostics. For sanitized PayPal and Stripe Sandbox setup, trusted public-origin configuration, webhook registration templates, and validation guidance, see [Payment Provider Sandbox Configuration](/fullstack/payment-sandbox-configuration).
+
+## The short version
+
+A-Pay is a provider-neutral payment infrastructure layer. Commerce owns the business result; A-Pay owns the payment-session and provider-operation result; provider modules translate external provider facts into A-Pay facts; Zova presents and observes those facts.
+
+```text
+Commerce trade
+    -> Commerce payment boundary
+    -> A-Pay payment-session boundary
+    <- pay-mock / pay-paypal / pay-stripe provider adapters
+```
+
+The most important rule is:
+
+> A browser redirect, callback, or rendered success state is not proof of payment. Verified provider facts, persisted payment state, durable outcome delivery, and the business aggregate owner determine settlement.
+
+## Suite and module topology
+
+The payment feature is a vendor suite named `a-pay`, mirrored in both framework halves:
+
+```text
+vona/src/suite-vendor/a-pay/
+├── modules/
+│   ├── a-pay/
+│   ├── pay-mock/
+│   ├── pay-paypal/
+│   └── pay-stripe/
+└── package.json
+
+zova/src/suite-vendor/a-pay/
+├── modules/
+│   ├── a-pay/
+│   ├── pay-mock/
+│   ├── pay-paypal/
+│   └── pay-stripe/
+└── package.json
+```
+
+The general suite/module organization is described in [Suites and Modules](/fullstack/suites-and-modules). The payment suite follows the vendor-suite layout rather than being a complete user-facing page package.
+
+| Module       | Vona responsibility                                                                                       | Zova responsibility                                                                         |
+| ------------ | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
+| `a-pay`      | Payment sessions, provider operations, callbacks, webhooks, normalized contracts, audit/outbox boundaries | Payment-session API/model, generated contracts, next-action component, redirect coordinator |
+| `pay-mock`   | Deterministic development/test provider and simulator webhook path                                        | Mock completion mutation used by the Commerce test surface                                  |
+| `pay-paypal` | PayPal API, capture, query, refund, and webhook translation                                               | Provider identity and metadata surface; no PayPal SDK execution in the browser              |
+| `pay-stripe` | Stripe Checkout, query, refund, and webhook translation                                                   | Provider identity and metadata surface; no Stripe SDK execution in the browser              |
+
+The actual Web payment page is owned by the Commerce consumer, not by `zova-module-a-pay`:
+
+```text
+zova/src/suite/a-commerce/modules/commerce-trade/src/page/payment/controller.tsx
+```
+
+This separation lets A-Pay stay reusable while Commerce owns order-specific presentation, polling, and navigation.
+
+## Ownership and authority
+
+The ownership chain in the current implementation is:
+
+```text
+commerce-trade -> commerce-payment -> a-pay <- pay-mock / pay-paypal / pay-stripe
+```
+
+| Layer            | Owns                                                                                                                                          | Must not own                                           |
+| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| Commerce trade   | Order transitions, inventory and coupon effects, shipment eligibility, and order/refund business rules                                        | Provider SDK calls or webhook parsing                  |
+| Commerce payment | Commerce `PaymentAttempt`, refund records, audit rules, and the Commerce payment scene                                                        | Direct provider integration                            |
+| A-Pay            | Provider-neutral `PaymentSession`, provider/refund operations, verified webhook receipts, payment audit records, and durable outcome delivery | Commerce aggregate settlement rules                    |
+| Provider modules | Translation between provider API/webhook facts and normalized A-Pay snapshots                                                                 | Direct mutation of Commerce orders or payment attempts |
+| Zova consumers   | Payment-session observation, user actions, next-action presentation, and post-hydration refresh                                               | Declaring payment success or settling an order         |
+
+A Commerce payment attempt initially has one A-Pay payment session. A future retry or provider switch can create another session without changing the Commerce aggregate identity. The payment session is the provider-execution boundary; the order remains the business boundary.
+
+## Payment session and state model
+
+A `PaymentSession` records the facts needed to execute and reconcile one provider payment attempt. Among other fields, the current entity stores:
+
+- the owning user and payment scene;
+- the business reference and correlation identifiers;
+- amount in minor units and currency;
+- the selected provider, client, and environment snapshot;
+- provider invoice/order/payment/capture identifiers as they become known;
+- the current state, next action, expiration, and finalization time.
+
+The amount and currency are established by the business domain before provider execution. Provider selection is resolved by the server from the payment scene; the browser does not choose arbitrary provider configuration.
+
+The session state is a discriminated union:
+
+```text
+created
+  -> starting
+  -> requires_action | processing | succeeded | failed | cancelled
+  -> expired
+```
+
+| State             | Meaning                                                                                             |
+| ----------------- | --------------------------------------------------------------------------------------------------- |
+| `created`         | The business domain created the session, but provider execution has not started.                    |
+| `starting`        | A provider start operation is being prepared or executed.                                           |
+| `requires_action` | The customer must follow a provider-directed action, usually a redirect in the current providers.   |
+| `processing`      | The provider has accepted or is processing the operation, but a terminal fact is not available yet. |
+| `succeeded`       | A verified terminal provider fact reports success.                                                  |
+| `failed`          | A verified terminal provider fact reports failure.                                                  |
+| `cancelled`       | The payment was cancelled or the provider reported cancellation.                                    |
+| `expired`         | The session passed its allowed lifetime without completing.                                         |
+
+The payment session and Commerce order are separate state machines. A terminal payment session can become visible before the outbox consumer settles the order, so the frontend must represent **pending confirmation** rather than assuming that a terminal provider state immediately means a paid order.
+
+### The `nextAction` contract
+
+The backend exposes a normalized action union. Zova consumers branch on `nextAction.kind`, not on PayPal- or Stripe-specific SDK objects.
+
+| Action kind | Consumer behavior                                                                                                                                  |
+| ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `redirect`  | In the browser, send the customer to the supplied provider URL through the shared payment coordinator.                                             |
+| `embedded`  | Pass the client-facing token/configuration to the selected provider UI adapter. The current shared coordinator does not execute embedded checkout. |
+| `pending`   | Show preparation or status messaging and offer a safe refresh/reconcile action when appropriate.                                                   |
+| `completed` | Show completion messaging, while still waiting for the business aggregate to expose its settled state.                                             |
+
+The normalized contract is defined in the backend payment types and view DTO, then carried to Zova through generated OpenAPI types and schemas. Do not hand-edit generated API output; change the backend contract source and follow the [contract loop playbook](/fullstack/contract-loop-playbook).
+
+## End-to-end payment lifecycle
+
+The following flow is source-confirmed by the current Commerce and A-Pay implementation.
+
+1. The authenticated customer opens Commerce checkout.
+2. Commerce asks its payment scene for the currently available provider candidates through `GET /api/commerce/trade/checkout/payment-methods`.
+3. Checkout submits order data and, at most, a scene-local `providerCandidateKey` through `POST /api/commerce/trade/checkout`.
+4. Commerce creates the order in `awaiting_payment`, creates a `PaymentAttempt`, and creates the associated A-Pay `PaymentSession` in `created` state.
+5. A-Pay re-evaluates provider availability and the submitted candidate on the server. It resolves a declared provider/client pair, snapshots its execution context and expiry, and rejects stale or ineligible choices.
+6. Commerce navigates to an authenticated Commerce payment route with the payment-session and order identifiers. Callback continuation remains server-selected and allowlisted; do not derive it from provider or browser input.
+7. The customer starts the session. Zova calls `POST /api/pay/payment-session/{id}/start`; A-Pay claims a provider operation with a stable idempotency key before making the external provider call.
+8. The provider adapter returns a normalized snapshot and optional `nextAction`. Redirect-capable providers normally return `requires_action` with a redirect action.
+9. Zova renders the generic next-action component. On the client, the redirect coordinator uses `window.location.assign(...)`; it does not call a provider SDK or decide whether the order is paid.
+10. The provider returns through the server callback route, or sends a webhook to the public webhook route. A return callback can request confirmation or reconciliation, but cannot assert success.
+11. A-Pay verifies provider webhook input using the selected server-side client and the raw request body, then correlates provider, client, environment, amount, currency, and identifiers with the persisted session.
+12. Verified facts are deduplicated and applied to payment state. The state transition, audit entry, and `payment.outcome.v1` outbox record are written durably.
+13. An outbox worker dispatches the outcome. The persisted payment scene resolves its outcome handler, which delegates to the Commerce order owner.
+14. Commerce validates the payment-session and business references, amount, currency, provider event identity, and current order/attempt state before applying the idempotent paid, cancelled, or refund transition.
+15. Zova reconciles and polls the payment session and order. It navigates to the order page only when the two durable views agree. If delivery is delayed, the page remains in a pending-confirmation state and offers refresh/reconcile controls.
+
+The provider call is intentionally outside the short database transaction. The durable phases are committed before and after that external call, so crash recovery and duplicate delivery are expected parts of the design. Consumers must therefore be idempotent.
+
+## Payment scenes and provider selection
+
+A payment scene is the business-domain policy boundary. It declares and coordinates:
+
+- the allowlist of named provider/client candidates;
+- supported currency and amount policy;
+- capture, refund, and partial-refund policy;
+- session expiry;
+- current availability and default selection;
+- the outcome handler for the owning business aggregate;
+- the trusted continuation behavior for customer returns.
+
+The checkout projection contains only safe presentation data such as a candidate key, label, description, display order, and interaction kind. The browser submits only the candidate key. It must never submit:
+
+- an arbitrary provider or client name;
+- environment or merchant account information;
+- credentials or webhook secrets;
+- provider callback URLs;
+- raw provider SDK options.
+
+A candidate appearing in the scene allowlist does not guarantee present-time availability. A-Pay recomputes availability when creating the session. An omitted choice uses the server-selected default; an invalid, stale, or disabled choice is rejected rather than silently replaced.
+
+### Current provider modules
+
+- **`pay-mock`** is a deterministic development and test provider. Its simulator sends a signed mock webhook through the normal webhook path, so tests exercise verification, state transitions, durable outcome delivery, and Commerce settlement instead of directly mutating a session.
+- **`pay-paypal`** owns the server-side PayPal hosted-approval, capture, query, refund, and webhook translation boundary. The browser receives normalized actions and never receives PayPal credentials or SDK authority.
+- **`pay-stripe`** owns the server-side Stripe hosted Checkout, query, refund, and webhook translation boundary. The browser receives normalized actions and never receives Stripe credentials or SDK authority.
+
+The frontend PayPal and Stripe modules are currently identity/metadata surfaces. Provider execution, credentials, callbacks, webhook verification, and reconciliation remain backend responsibilities.
+
+## Provider-module authoring contract
+
+A provider adapter implements the neutral A-Pay execution boundary rather than writing Commerce-specific logic. Depending on its capabilities, the adapter supplies operations conceptually equivalent to:
+
+- start payment;
+- confirm payment;
+- query or reconcile payment;
+- create and query refunds;
+- verify webhooks.
+
+An adapter should:
+
+1. use only the selected, server-resolved client options;
+2. translate provider responses into A-Pay payment/refund snapshots;
+3. preserve provider identifiers needed for correlation and idempotency;
+4. verify webhook input before returning a trusted event identity and payload;
+5. validate provider facts against the persisted session context;
+6. return only safe summary and next-action data through outward-facing contracts;
+7. leave Commerce `PaymentAttempt` and `Order` mutations to the Commerce owner.
+
+The adapter must not derive authoritative payment identity, amount, currency, environment, or continuation targets from untrusted browser or webhook fields. Webhook verification receives the raw request body because reserialized JSON is not an equivalent signature input.
+
+## Zova consumption model
+
+Read the frontend in Zova’s own roles first:
+
+| Zova role                        | Current A-Pay responsibility                                                                                      |
+| -------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
+| `ModelPaymentSession`            | Model-owned query and mutation state for `view`, `start`, and `reconcile`, including invalidation after mutations |
+| `ControllerPaymentNextAction`    | Component-controller behavior for redirect, pending, completed, and embedded action rendering                     |
+| `ServicePaymentCoordinator`      | Client-only execution of a normalized redirect action                                                             |
+| `ZPaymentNextAction`             | Metadata-backed public component wrapper for the action controller                                                |
+| Commerce payment page controller | Route state, start/reconcile decisions, settlement polling, and order navigation                                  |
+
+This is not page-local Vue fetching rewritten with classes. The model bean owns remote query/mutation state; the controller owns interaction and lifecycle decisions; the service bean owns reusable browser-side behavior; the render/component wrapper exposes the controller to consumers.
+
+The core frontend reading path is:
+
+1. `zova/src/suite-vendor/a-pay/modules/a-pay/src/types/payment.ts`
+2. `zova/src/suite-vendor/a-pay/modules/a-pay/src/model/paymentSession.ts`
+3. `zova/src/suite-vendor/a-pay/modules/a-pay/src/api/paymentSession.ts`
+4. `zova/src/suite-vendor/a-pay/modules/a-pay/src/apiSchema/paymentSession.ts`
+5. `zova/src/suite-vendor/a-pay/modules/a-pay/src/service/paymentCoordinator.ts`
+6. `zova/src/suite-vendor/a-pay/modules/a-pay/src/component/paymentNextAction/controller.tsx`
+7. `zova/src/suite/a-commerce/modules/commerce-trade/src/page/payment/controller.tsx`
+
+When a consumer uses `controllerRef` on `ZPaymentNextAction`, it receives the Zova component controller instance. It is not a generic DOM or Vue component reference.
+
+### Frontend consumer rules
+
+- Keep payment-session query/mutation state in `ModelPaymentSession`.
+- Consume generated API types and schemas; do not hand-patch generated files.
+- Pass the normalized `nextAction` to the generic action component instead of adding provider-specific branches to Commerce pages.
+- Execute redirects only in the browser.
+- Keep mock simulator controls limited to mock sessions and development/test surfaces.
+- Treat payment-session terminal state and Commerce order settlement as separate observations.
+- Keep customer-visible success behind authenticated, server-authorized reads.
+
+## Callback, SSR, and hydration
+
+A provider return crosses two boundaries:
+
+1. **Settlement authority:** the server callback confirms or reconciles provider state; it does not trust a browser assertion.
+2. **Browser route recovery:** after an external provider navigation, the browser may need to restore the Passport projection before accessing customer-owned payment and order data.
+
+The current return path is conceptually:
+
+```text
+provider return or cancel
+  -> public A-Pay callback with opaque state
+  -> server confirm or reconcile
+  -> allowlisted Commerce continuation
+  -> SSR-compatible payment route
+  -> browser hydration and Passport admission
+  -> authenticated payment-session reconciliation
+  -> durable order settlement observation
+```
+
+The Commerce payment route requires authentication and uses the session SSR profile. Its controller defers client initialization through `$ssr.handleDirectOrOnHydrated(...)`. The payment-session model avoids creating private server-side query state when cookies are unavailable or the Passport is not authenticated. After hydration and admission, the controller can reconcile, poll, and navigate using customer-authorized reads.
+
+The invariant is more important than a particular visual shell: server HTML and the hydration-time initial render must agree about private payment/order data. Do not render customer-owned payment state on the server when the request cannot authorize it, and do not let the provider return itself settle Commerce.
+
+For the deeper SSR return and Passport recovery rationale, maintainers can consult the internal architecture note. The public rule remains: settle on verified server facts; recover private browser state only after hydration and authorization.
+
+## Reliability and security invariants
+
+Use this checklist when extending or reviewing the payment flow:
+
+- Amount and currency are immutable, server-owned session facts.
+- Provider selection is scene-allowlisted and revalidated when the session is created.
+- Provider calls have durable operation records, idempotency keys, claim leases, and recovery paths.
+- Webhooks are verified against the raw body and the selected server-side provider client.
+- Verified webhook facts are correlated with the persisted session before trusted mutation.
+- Webhook receipts and provider event IDs are deduplicated.
+- Terminal session transitions, audit records, and outcome outbox entries are durable and atomic.
+- Outbox delivery is at-least-once; Commerce consumers must handle duplicate and out-of-order delivery safely.
+- Browser callbacks, frontend polling, and Passport recovery never directly settle Commerce.
+- Callback continuations are opaque, short-lived, signed, and allowlisted by the server.
+- Payment-session endpoints enforce authenticated ownership; route admission does not replace resource authorization.
+- Provider secrets and private configuration never enter DTOs, OpenAPI output, frontend state, audit summaries, or public documentation.
+
+## Source-reading map
+
+For backend contract and orchestration:
+
+1. `vona/src/suite-vendor/a-pay/modules/a-pay/src/types/payment.ts`
+2. `vona/src/suite-vendor/a-pay/modules/a-pay/src/controller/paymentSession.ts`
+3. `vona/src/suite-vendor/a-pay/modules/a-pay/src/service/paymentSession.ts`
+4. `vona/src/suite-vendor/a-pay/modules/a-pay/src/service/providerOperation.ts`
+5. `vona/src/suite-vendor/a-pay/modules/a-pay/src/controller/paymentCallback.ts`
+6. `vona/src/suite-vendor/a-pay/modules/a-pay/src/controller/webhook.ts`
+7. `vona/src/suite-vendor/a-pay/modules/pay-mock/src/bean/payProvider.mock.ts`
+8. `vona/src/suite-vendor/a-pay/modules/pay-paypal/src/bean/payProvider.paypal.ts`
+9. `vona/src/suite-vendor/a-pay/modules/pay-stripe/src/bean/payProvider.stripe.ts`
+10. `vona/src/suite/a-commerce/modules/commerce-trade/src/service/order.ts`
+
+For frontend contracts and consumption:
+
+1. `zova/src/suite-vendor/a-pay/modules/a-pay/src/types/payment.ts`
+2. `zova/src/suite-vendor/a-pay/modules/a-pay/src/model/paymentSession.ts`
+3. `zova/src/suite-vendor/a-pay/modules/a-pay/src/api/paymentSession.ts`
+4. `zova/src/suite-vendor/a-pay/modules/a-pay/src/apiSchema/paymentSession.ts`
+5. `zova/src/suite-vendor/a-pay/modules/a-pay/src/service/paymentCoordinator.ts`
+6. `zova/src/suite-vendor/a-pay/modules/a-pay/src/component/paymentNextAction/controller.tsx`
+7. `zova/src/suite/a-commerce/modules/commerce-trade/src/routes.ts`
+8. `zova/src/suite/a-commerce/modules/commerce-trade/src/page/checkout/controller.tsx`
+9. `zova/src/suite/a-commerce/modules/commerce-trade/src/page/payment/controller.tsx`
+
+For the generated contract handoff, follow the backend DTO/OpenAPI source to the generated Zova API/types and then to the model/page consumer. See [Vona + Zova Integration](/fullstack/vona-zova-integration) and [Contract Loop Playbook](/fullstack/contract-loop-playbook).
+
+## Relationship to other guides
+
+- [Suites and Modules](/fullstack/suites-and-modules) explains the suite-first source-tree model.
+- [Payment Provider Sandbox Configuration](/fullstack/payment-sandbox-configuration) explains sanitized PayPal and Stripe Sandbox setup, public-origin configuration, and end-to-end validation.
+- [Vona + Zova Integration](/fullstack/vona-zova-integration) explains the cross-framework integration boundary.
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook) explains how backend contracts become generated frontend consumers.
+- [Reading Zova for Vue Developers](/frontend/reading-zova-for-vue-developers) explains controller, model, service, and IoC roles in Zova-native terms.
+- [Transaction Guide](/backend/transaction-guide) and [Queue Guide](/backend/queue-guide) provide framework-level background for the durable phases used by A-Pay.
+
+## Verification
+
+For documentation changes, run:
+
+```bash
+npm run docs:build
+```
+
+Then confirm that **Fullstack / Architecture & Integration → A-Pay Payment Suite** opens correctly and that the linked public guides resolve. When the implementation changes, recheck this page against current source; generated contracts and legacy operational notes are not substitutes for authored source truth.

package/cabloy-docs/fullstack/payment-sandbox-configuration.md

@@ -0,0 +1,285 @@
+# Payment Provider Sandbox Configuration
+
+This guide explains how to validate the current PayPal and Stripe payment providers in a Cabloy Basic Sandbox environment.
+
+Use it after understanding the architecture in [A-Pay Payment Suite](/fullstack/a-pay-payment-suite). It covers safe, reproducible configuration and validation with placeholders. It does **not** authorize Live payment traffic, replace provider compliance requirements, or include real account values, secrets, deployment-specific paths, tunnel commands, or internal operational diagnostics.
+
+## What Sandbox validation proves
+
+A complete Sandbox validation proves the server can:
+
+1. expose a configured provider as a Commerce payment method;
+2. create a provider-neutral payment session;
+3. redirect the customer to a provider Sandbox flow;
+4. receive a provider callback and verified webhook;
+5. persist the normalized payment result;
+6. deliver one durable outcome to Commerce; and
+7. settle the order idempotently.
+
+It does **not** prove that Live credentials, a Live webhook endpoint, or production operations are approved. Keep Sandbox and Live provider accounts, credentials, webhook endpoints, and merchant references separate.
+
+## Security boundary
+
+Provider credentials and webhook material are backend-only configuration. Store them in the Vona server environment or deployment secret store. For an uncommitted local setup, use the backend local override:
+
+```text
+vona/env/.env.local
+```
+
+Never put provider credentials or private merchant configuration in:
+
+- Zova or other frontend environment files;
+- generated API contracts or frontend state;
+- source code, commits, screenshots, issue comments, or public logs.
+
+A browser redirect, callback, or success screen is **not** payment settlement authority. Settlement requires verified provider facts, correlation with the persisted payment session, durable state changes, and idempotent Commerce outcome handling.
+
+## Shared server configuration
+
+Both providers need a canonical, externally reachable HTTPS origin. A provider must be able to reach the webhook endpoint from the public Internet, so `localhost`, a private address, or an unreachable host is insufficient. An approved HTTPS tunnel can forward a public hostname to a local Vona process during Sandbox work.
+
+```dotenv
+SERVER_SERVE_PROTOCOL=https
+SERVER_SERVE_HOST=<public-https-host>
+SERVER_SUBDOMAINOFFSET=<domain-parts-count>
+```
+
+`SERVER_SERVE_PROTOCOL` and `SERVER_SERVE_HOST` are the canonical external origin used to generate provider callback URLs. They are distinct from the hostname and port on which the Vona process listens.
+
+Use the same public hostname for:
+
+- `SERVER_SERVE_HOST`;
+- generated provider callback URLs;
+- the provider Dashboard webhook endpoint.
+
+Restart Vona after changing server or provider environment values.
+
+### Map the public host to the intended instance
+
+`SERVER_SUBDOMAINOFFSET` controls how Vona derives an instance name from the incoming hostname. This matters for provider callbacks and webhooks because they arrive through the public host, not the browser's local development address.
+
+With an offset of `2`, an ordinary two-label base domain works as follows:
+
+```text
+example.com            -> default instance ''
+merchant.example.com   -> named instance 'merchant'
+eu.merchant.example.com -> named instance 'merchant.eu'
+```
+
+The default instance is explicitly named `''`; an unknown hostname-derived instance does not silently fall back to it. Unknown, unavailable, or disabled instances can produce HTTP `423` before the provider webhook reaches A-Pay.
+
+For a public hostname whose **complete** label sequence should resolve to the default instance, set `SERVER_SUBDOMAINOFFSET` to the number of labels in that complete hostname. For example, a generic four-label tunnel shape such as:
+
+```text
+<id>.<region>.devtunnels.ms
+```
+
+may need:
+
+```dotenv
+SERVER_SUBDOMAINOFFSET=4
+```
+
+Do not copy that value blindly. Count the actual hostname labels and recalculate the offset whenever the public hostname changes. If the remaining labels intentionally represent a named instance, use the base-domain label count instead and ensure that derived instance exists and is enabled.
+
+Read [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution) for the full host-to-instance model and [Docker + Cloudflare Deployment](/fullstack/deploy-cloudflare-docker) for public-origin deployment context.
+
+## Callback and webhook URLs
+
+For redirect-capable providers, A-Pay generates callback URLs from the trusted server origin. The current callback paths are:
+
+```text
+GET /api/pay/payment-callback/return?state=<opaque-token>
+GET /api/pay/payment-callback/cancel?state=<opaque-token>
+```
+
+The `state` value is a short-lived signed server token. It binds the return to the payment session and a server-selected continuation. The provider and browser do not choose an arbitrary continuation URL.
+
+The current default webhook endpoint templates are:
+
+```text
+POST https://<public-host>/api/pay/webhook/pay-paypal:paypal/default
+POST https://<public-host>/api/pay/webhook/pay-stripe:stripe/default
+```
+
+Here, `pay-paypal` and `pay-stripe` are provider names, while `default` is the provider client name. `/api` is the repository's default global API prefix. If a deployment configures a different global prefix, substitute that prefix in both callback and webhook URLs.
+
+Register the exact current public HTTPS endpoint with the provider. Do not let a browser-supplied `Host`, `Origin`, or return URL replace the configured server origin.
+
+## PayPal Sandbox
+
+### Backend configuration
+
+Configure the selected PayPal Sandbox client on Vona only:
+
+```dotenv
+PAYPAL_ENVIRONMENT=sandbox
+PAYPAL_CLIENT_ID=xxxxx
+PAYPAL_CLIENT_SECRET=xxxxx
+PAYPAL_WEBHOOK_ID=xxxxx
+PAYPAL_MERCHANT_REFERENCE=xxxxx
+```
+
+| Variable                    | Purpose                                                                                                               |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `PAYPAL_ENVIRONMENT`        | Selects `sandbox` or `live`. Use `sandbox` for this guide.                                                            |
+| `PAYPAL_CLIENT_ID`          | Identifies the selected PayPal REST application.                                                                      |
+| `PAYPAL_CLIENT_SECRET`      | Authenticates server-side PayPal API and webhook-verification work.                                                   |
+| `PAYPAL_WEBHOOK_ID`         | Identifies the registered PayPal webhook when the server asks PayPal to verify a delivery. It is not the webhook URL. |
+| `PAYPAL_MERCHANT_REFERENCE` | Identifies the expected Sandbox merchant/payee for provider-fact correlation.                                         |
+
+The values must all belong to the same PayPal Sandbox environment. The Commerce payment scene offers PayPal only when the required PayPal values and the server origin are complete.
+
+### Dashboard setup
+
+1. Select the PayPal **Sandbox** environment.
+2. Create or select an isolated Sandbox merchant and buyer account.
+3. Create or select the REST application for that Sandbox environment.
+4. Copy the application's client ID and secret into the Vona backend secret source.
+5. Register this endpoint in the same Sandbox environment:
+
+   ```text
+   POST https://<public-host>/api/pay/webhook/pay-paypal:paypal/default
+   ```
+
+6. Store the resulting webhook ID as `PAYPAL_WEBHOOK_ID` and configure the expected Sandbox merchant reference.
+7. Subscribe only to capture and refund event types supported by the current adapter. Avoid broad unrelated event families.
+8. Restart Vona and confirm the provider becomes available in the authenticated Commerce payment-method projection.
+
+### Validate a PayPal payment
+
+1. Create a Sandbox Commerce order and select the PayPal candidate.
+2. Start payment and confirm the browser is redirected to PayPal Sandbox approval.
+3. Approve using the Sandbox buyer account.
+4. Let the browser return through the signed A-Pay callback; the backend captures or reconciles the persisted provider order.
+5. Confirm a verified webhook receipt is processed, the `PaymentSession` reaches a normalized terminal state, and Commerce receives exactly one payment outcome.
+6. Repeat the browser return and redeliver the provider webhook. The order, inventory, coupon, audit, and outbox effects must not duplicate.
+7. Validate full and partial refunds where the current provider capability and business policy allow them.
+
+## Stripe Sandbox
+
+### Backend configuration
+
+Configure the selected Stripe Sandbox client on Vona only:
+
+```dotenv
+STRIPE_ENVIRONMENT=sandbox
+STRIPE_SECRET_KEY=xxxxx
+STRIPE_WEBHOOK_SECRET=xxxxx
+STRIPE_MERCHANT_REFERENCE=xxxxx
+```
+
+| Variable                    | Purpose                                                                                                                            |
+| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `STRIPE_ENVIRONMENT`        | Selects `sandbox` or `live`. Use `sandbox` for this guide.                                                                         |
+| `STRIPE_SECRET_KEY`         | Creates the server-side Stripe client for Checkout, query, and refund operations. Use a Sandbox secret key, not a publishable key. |
+| `STRIPE_WEBHOOK_SECRET`     | Verifies the raw request body and `Stripe-Signature` header for the registered endpoint.                                           |
+| `STRIPE_MERCHANT_REFERENCE` | Optional deployment/merchant label carried in the client configuration; it does not replace either Stripe secret.                  |
+
+The Commerce payment scene offers Stripe only when its Sandbox secret key, endpoint signing secret, and server origin are complete.
+
+### Dashboard setup
+
+1. Select the Stripe **Sandbox** environment.
+2. Copy a Sandbox secret key into the Vona backend secret source. Do not use a publishable key as `STRIPE_SECRET_KEY`.
+3. Register this endpoint in the same Sandbox environment:
+
+   ```text
+   POST https://<public-host>/api/pay/webhook/pay-stripe:stripe/default
+   ```
+
+4. Store the signing secret from that exact endpoint as `STRIPE_WEBHOOK_SECRET`.
+5. Subscribe to the Checkout, PaymentIntent, and refund lifecycle events required by the current adapter and the intended validation flow. Avoid unrelated event families.
+6. Restart Vona and confirm the provider becomes available in the authenticated Commerce payment-method projection.
+
+### Validate a Stripe payment
+
+1. Create a Sandbox Commerce order and select the Stripe candidate.
+2. Start payment and confirm the browser is redirected to Stripe Hosted Checkout.
+3. Complete Checkout with a Stripe-provided Sandbox test payment method.
+4. Let the browser return through the signed A-Pay callback; the backend reconciles persisted Stripe facts.
+5. Confirm the endpoint receives a verified webhook, the `PaymentSession` reaches its normalized terminal state, and Commerce receives exactly one payment outcome.
+6. Redeliver the webhook and repeat the browser return. Settlement and business side effects must converge to one result.
+7. Validate full and partial refunds where supported, and confirm an indeterminate provider result remains recoverable rather than being treated as successful.
+
+Use the current Stripe documentation for the appropriate Sandbox test payment methods. Do not treat any example test value as a Cabloy-specific payment requirement.
+
+## Verify the complete flow
+
+For either provider, use this end-to-end checklist:
+
+1. Restart Vona after configuration changes.
+2. Authenticate and load the Commerce payment-method projection.
+3. Confirm the provider appears only with complete, environment-matched configuration.
+4. Create a USD test order and select the provider candidate.
+5. Start the payment and verify the expected provider Sandbox redirect.
+6. Complete or cancel the provider flow and return to the application.
+7. Confirm the server callback asks the provider to confirm or reconcile; it must not trust browser success parameters.
+8. Confirm the provider dashboard records a successful webhook delivery and Vona verifies it.
+9. Confirm the persisted `PaymentSession` reaches the expected provider-neutral terminal state.
+10. Confirm Commerce receives one durable outcome and exposes the corresponding settled order state.
+11. Redeliver the same webhook and repeat the browser return to prove idempotency and race convergence.
+12. Exercise supported full and partial refunds; confirm repeated provider events and queries converge to one refund outcome.
+
+## Troubleshooting
+
+### The provider does not appear in Checkout
+
+Check the following:
+
+- All required values are configured in Vona, not Zova.
+- Every key, secret, webhook identifier/signing secret, merchant reference, and selected environment belongs to the same Sandbox environment.
+- Stripe uses a secret key, not a publishable key.
+- `SERVER_SERVE_PROTOCOL` and `SERVER_SERVE_HOST` are configured.
+- Vona was restarted after changing the environment.
+- The public hostname is current and the provider candidate remains available for the active payment scene.
+
+### The callback or webhook reaches HTTP `423`
+
+Treat this as an instance-resolution check first:
+
+- Count the labels in the incoming public hostname.
+- Recheck `SERVER_SUBDOMAINOFFSET`.
+- Verify whether the host should map to the default instance or a named instance.
+- Verify that any intended named instance exists and is enabled.
+- Do not expect an unknown hostname-derived instance to fall back to the default instance.
+
+### Webhook signature verification fails
+
+Check the following:
+
+- The endpoint is publicly reachable over HTTPS.
+- The configured public hostname matches the registered provider endpoint.
+- The provider credentials and webhook identifier/signing secret belong to the same Sandbox environment and exact endpoint.
+- Vona has the current values after restart.
+- The integration preserves the provider's required raw request body and signature/transmission headers.
+
+### The browser returns, but the order is not settled
+
+A normal browser return is not proof of payment. Inspect the durable flow in order:
+
+1. payment session state;
+2. linked provider operation state;
+3. webhook receipt and signature-verification result;
+4. outbox delivery state;
+5. redacted provider error summary.
+
+Do not manually mark the order paid, recreate inventory/coupon effects, or reuse a consumed provider approval URL to bypass a delayed callback or webhook.
+
+## Relationship to other guides
+
+- [A-Pay Payment Suite](/fullstack/a-pay-payment-suite) explains session ownership, provider-neutral contracts, settlement, and Zova consumption.
+- [Multi-Instance and Instance Resolution](/backend/multi-instance-and-instance-resolution) explains how hostname labels and `SERVER_SUBDOMAINOFFSET` select an instance.
+- [Docker + Cloudflare Deployment](/fullstack/deploy-cloudflare-docker) explains public HTTPS origin deployment context.
+- [Vona + Zova Integration](/fullstack/vona-zova-integration) explains the fullstack contract boundary.
+- [Contract Loop Playbook](/fullstack/contract-loop-playbook) explains generated backend-to-frontend contracts.
+
+## Verification
+
+After changing payment configuration or documentation:
+
+```bash
+npm run docs:build
+```
+
+For a real Sandbox validation, repeat provider callback and webhook deliveries deliberately. The expected result is one verified payment/refund outcome and one Commerce business effect, even when external delivery is repeated or arrives in a different order.