refactor!: Refactor Payment constructs (including related extensions) from shopping/ to common/

docs/documentation/core-concepts.md

@@ -186,8 +186,8 @@ up-to-date list.
 | :--- | :--- | :--- |
 | `dev.ucp.shopping.discount` | checkout, cart | Discount codes and promotions |
 | `dev.ucp.shopping.fulfillment` | checkout | Shipping and delivery options |
-| `dev.ucp.shopping.payment_authentication` | checkout | Browser-surface device data collection and 3DS challenges |
-| `dev.ucp.shopping.ap2_mandate` | checkout | Non-repudiable authorization for autonomous commerce |
+| `dev.ucp.common.payment.authentication` | checkout | Browser-surface device data collection and 3DS challenges |
+| `dev.ucp.common.payment.ap2_mandate` | checkout | Non-repudiable authorization for autonomous commerce |
 | `dev.ucp.shopping.buyer_consent` | checkout, cart | Explicit consent capture |
 
 ### Services

docs/documentation/schema-authoring.md

@@ -144,7 +144,7 @@ Do **not** appear in registries.
 
 Examples:
 
-- `schemas/shopping/payment.json` — Payment configuration (part of checkout)
+- `schemas/common/types/payment.json` — Payment configuration (part of lower funnel capabilities like checkout in retail shopping)
 
 ### Type Schemas
 

docs/specification/glossary.md

@@ -44,6 +44,7 @@ acronym in each specification Markdown file spells out the full term (e.g.,
 | Term                         | Acronym | Definition                                                                                                                                                |
 | :--------------------------- | :------ | :-------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Business**                 | -       | The entity selling goods or services. In UCP, they act as the **Merchant of Record (MoR)**, retaining financial liability and ownership of the order.     |
+| **Buyer**                    | -       | The transacting customer or end consumer completing a commerce action over UCP. Synonymous to vocabularies like `user` and `consumer`.                    |
 | **Location**                 | -       | A physical place (e.g., store, restaurant, property, pickup point) identified by a stable, opaque string in a Business's namespace.                       |
 | **Increment**                | -       | Optional [ordering granularity](overview/index.md#ordering-increment) of a sale basis, a count of steps; advisory for Platform-authored quantities.       |
 | **Merchant of Record**       | MoR     | The legal entity responsible for the sale, including financial liability and order ownership.                                                             |

docs/specification/overview/index.md

@@ -91,7 +91,7 @@ values
 Section 6) and within which
 [JCS](https://www.rfc-editor.org/rfc/rfc8785.html){ target="_blank" }
 canonicalization, required for
-[AP2 mandate signing](../ap2-mandates.md#canonicalization), is defined. The
+[AP2 mandate signing](../payment/extensions/ap2-mandates.md#canonicalization), is defined. The
 same cap derives `scale`'s maximum of 15: at scale 16, one whole unit
 (10^16 steps) would be unrepresentable. An out-of-range value is
 schema-invalid and is rejected like any other invalid payload.
@@ -248,7 +248,7 @@ The grammar is defined independently of the object it is bound to. Request
 Constraints bind it to objects in the next request and add `path`; other UCP
 schemas reuse it where a declaration already identifies the object it
 constrains, such as
-[`available_instruments[].constraints`](site:schemas/shopping/types/available_payment_instrument.json),
+[`available_instruments[].constraints`](site:schemas/common/types/available_payment_instrument.json),
 whose object is the `constraint_target` declared by the instrument schema for
 that entry's `type`.
 
@@ -533,7 +533,7 @@ In this example, a Business emits `ucp.request_constraints` on an available card
 instrument to require `billing_address` in the next request if it contains a
 matching submitted card instrument:
 
-<!-- ucp:example schema=shopping/types/available_payment_instrument op=read direction=response -->
+<!-- ucp:example schema=common/types/available_payment_instrument op=read direction=response -->
 ```json
 {
   "type": "card",
@@ -563,7 +563,7 @@ network token must carry a `cryptogram` with its `eci_value`. Each credential
 family is its own schema, so every branch discriminates on the credential's own
 `type` and no rule has to branch on a sibling field:
 
-<!-- ucp:example schema=shopping/types/available_payment_instrument op=read direction=response -->
+<!-- ucp:example schema=common/types/available_payment_instrument op=read direction=response -->
 ```json
 {
   "type": "card",
@@ -595,16 +595,16 @@ it. The sibling `required` applies to every matching instrument; the `anyOf`
 branches then apply to the nested `credential` object, which must satisfy at
 least one. Each branch pins `type` with `const`, so a branch matches only the
 credential family it describes;
-[`payment_credential.json`](site:schemas/shopping/types/payment_credential.json)
+[`payment_credential.json`](site:schemas/common/types/payment_credential.json)
 already requires `type` on every credential, so no branch has to name it in
-`required`. A [PAN credential](site:schemas/shopping/types/pan_credential.json)
+`required`. A [PAN credential](site:schemas/common/types/pan_credential.json)
 without a `cvc` fails, as does a [network
-token](site:schemas/shopping/types/network_token_credential.json) missing its
+token](site:schemas/common/types/network_token_credential.json) missing its
 `eci_value`.
 
 Because every branch pins the discriminator, the branch set also closes the
 accepted credential families. A handler
-[token credential](site:schemas/shopping/types/token_credential.json) is a valid
+[token credential](site:schemas/common/types/token_credential.json) is a valid
 credential at this position but satisfies neither branch, so this Business does
 not accept it at this path. A Business that later accepts another family adds a
 branch for it.
@@ -2470,7 +2470,7 @@ either suffices.
 This rule governs **HTTP transport identity**. Payload-layer
 assertions (e.g., AP2 mandate JWTs carried in the request body) have
 their own identity binding and key-resolution rules; see
-[AP2 Mandates](../ap2-mandates.md).
+[AP2 Mandates](../payment/extensions/ap2-mandates.md).
 
 ## Payment Architecture
 
@@ -2497,11 +2497,11 @@ touch raw financial credentials.
 
 For scenarios requiring cryptographic proof of user authorization (e.g.,
 autonomous AI agents), UCP supports the **AP2 Mandates Extension**
-(`dev.ucp.shopping.ap2_mandate`). This optional extension provides
+(`dev.ucp.common.payment.ap2_mandate`). This optional extension provides
 non-repudiable authorization through verifiable digital credentials.
 
 See [Transaction Integrity](#transaction-integrity-and-non-repudiation)
-and [AP2 Mandates Extension](../ap2-mandates.md) for details on when and how to
+and [AP2 Mandates Extension](../payment/extensions/ap2-mandates.md) for details on when and how to
 use this extension.
 
 #### Credential Flow & PCI Scope
@@ -2579,10 +2579,10 @@ the [Payment Handler Guide](../payment/guide.md#resolving-available_instruments)
 for the full resolution semantics.
 
 **Instrument Cardinality:** A checkout submission **MUST** contain exactly one
-payment instrument unless the `dev.ucp.shopping.split_payments` capability is
+payment instrument unless the `dev.ucp.common.payment.split_payments` capability is
 active. Businesses **MUST** reject submissions that violate this constraint with
 a `payment_failed` error in `messages[]`. See
-[Split Payments](../payment/split-payments.md) for the extension that relaxes this
+[Split Payments](../payment/extensions/split-payments.md) for the extension that relaxes this
 constraint.
 
 ### Implementation Scenarios
@@ -2906,8 +2906,8 @@ certified and handle:
 4. Log payment events without logging credentials
 5. Set appropriate credential timeouts
 6. For autonomous commerce scenarios requiring cryptographic proof, consider
-    supporting the `dev.ucp.shopping.ap2_mandate` extension (see
-    [AP2 Mandates Extension](../ap2-mandates.md))
+    supporting the `dev.ucp.common.payment.ap2_mandate` extension (see
+    [AP2 Mandates Extension](../payment/extensions/ap2-mandates.md))
 
 **For Platforms:**
 
@@ -2916,9 +2916,9 @@ certified and handle:
 3. Implement timeout handling for credential acquisition
 4. Clear credentials from memory after submission
 5. Handle credential expiration gracefully (re-acquire if needed)
-6. For autonomous agents, consider using the `dev.ucp.shopping.ap2_mandate`
+6. For autonomous agents, consider using the `dev.ucp.common.payment.ap2_mandate`
     extension for cryptographic proof of authorization (see
-    [AP2 Mandates Extension](../ap2-mandates.md))
+    [AP2 Mandates Extension](../payment/extensions/ap2-mandates.md))
 
 **For Payment Credential Providers:**
 
@@ -2950,10 +2950,10 @@ payment architecture:
 The core payment architecture described above can be extended for specialized
 use cases:
 
-- **AP2 Mandates Extension** (`dev.ucp.shopping.ap2_mandate`): Adds
+- **AP2 Mandates Extension** (`dev.ucp.common.payment.ap2_mandate`): Adds
     cryptographic proof of user authorization for autonomous commerce scenarios
     where non-repudiable evidence is required. See
-    [AP2 Mandates Extension](../ap2-mandates.md).
+    [AP2 Mandates Extension](../payment/extensions/ap2-mandates.md).
 
 - **Custom Handler Types**: Payment credential providers can define custom
     handlers to support new payment instruments. See
@@ -3411,7 +3411,7 @@ business-emitted snapshot of the originating checkout's attribution.
 
 For scenarios requiring cryptographic proof of authorization (e.g., autonomous
 agents, high-value transactions), UCP supports the **AP2 Mandates Extension**
-(`dev.ucp.shopping.ap2_mandate`). When this optional extension is negotiated:
+(`dev.ucp.common.payment.ap2_mandate`). When this optional extension is negotiated:
 
 - Businesses provide a cryptographic signature on checkout terms
 - Platforms provide cryptographic mandates proving user authorization
@@ -3420,7 +3420,7 @@ This mechanism provides strong, end-to-end cryptographic assurances about
 transaction details and participant consent, significantly reducing risks of
 tampering and disputes.
 
-See [AP2 Mandates Extension](../ap2-mandates.md) for complete specification,
+See [AP2 Mandates Extension](../payment/extensions/ap2-mandates.md) for complete specification,
 implementation guide, and examples.
 
 ## Versioning

docs/specification/payment/examples/encrypted-credential-payment-handler.md

@@ -121,7 +121,7 @@ Businesses advertise the platform's handler. The `business_id` field identifies
 the business, which the platform uses to look up the correct public key for
 encryption.
 
-The only supported instrument schema is [CardPaymentInstrument](site:schemas/shopping/types/card_payment_instrument.json), the only supported checkout credential schema is `EncryptedCredential`, and the only supported source credential schema is [PanCredential](site:schemas/shopping/types/pan_credential.json).
+The only supported instrument schema is [CardPaymentInstrument](site:schemas/common/types/card_payment_instrument.json), the only supported checkout credential schema is `EncryptedCredential`, and the only supported source credential schema is [PanCredential](site:schemas/common/types/pan_credential.json).
 
 **Note:** The `EncryptedCredential` shape would be formally defined in the handler's schema (referenced via the `schema` field in the handler declaration).
 
@@ -359,5 +359,5 @@ Content-Type: application/json
 
 ## References
 
-* **Identity Schema:** [schemas/shopping/types/payment_identity.json](site:schemas/shopping/types/payment_identity.json)
-* **Instrument Schema:** [schemas/shopping/types/card_payment_instrument.json](site:schemas/shopping/types/card_payment_instrument.json)
+* **Identity Schema:** [schemas/common/types/payment_identity.json](site:schemas/common/types/payment_identity.json)
+* **Instrument Schema:** [schemas/common/types/card_payment_instrument.json](site:schemas/common/types/card_payment_instrument.json)

docs/specification/payment/examples/platform-tokenizer-payment-handler.md

@@ -176,7 +176,7 @@ platform's handler specification (referenced via `spec`) documents the
 `/detokenize` endpoint URL exposed by the platform's
 **payment credential provider**.
 
-The handler accepts [PanCredential](site:schemas/shopping/types/pan_credential.json) and [NetworkTokenCredential](site:schemas/shopping/types/network_token_credential.json) for tokenization and produces [TokenCredential](site:schemas/shopping/types/token_credential.json) for checkout.
+The handler accepts [PanCredential](site:schemas/common/types/pan_credential.json) and [NetworkTokenCredential](site:schemas/common/types/network_token_credential.json) for tokenization and produces [TokenCredential](site:schemas/common/types/token_credential.json) for checkout.
 
 **Note:** The result of `/detokenize` contains **sensitive payment data**.
 Both the sender (platform's credential provider) and receiver
@@ -414,12 +414,12 @@ Content-Type: application/json
 ## Runtime Payment Authentication Actions
 
 This handler supports both Action types from the negotiated
-[Payment Authentication extension](../authentication.md):
+[Payment Authentication extension](../extensions/authentication.md):
 
 | Action type | Use |
 | :---------- | :-- |
-| `dev.ucp.payment.device_data_collection` | Collect device/browser data for the selected tokenized instrument. |
-| `dev.ucp.payment.three_ds_challenge` | Present a buyer-facing 3DS challenge during payment completion. |
+| `dev.ucp.common.payment.device_data_collection` | Collect device/browser data for the selected tokenized instrument. |
+| `dev.ucp.common.payment.three_ds_challenge` | Present a buyer-facing 3DS challenge during payment completion. |
 
 When either step is needed, the Business returns the corresponding Action while
 processing the selected instrument. Its `config.payment_instrument_id` identifies
@@ -519,4 +519,4 @@ The platform's payment credential provider verifies that:
 
 * **Pattern:** [Tokenization Payment Handler](../guide.md)
 * **API Pattern:** [handlers/tokenization/openapi.json](site:handlers/tokenization/openapi.json)
-* **Identity Schema:** [schemas/shopping/types/payment_identity.json](site:schemas/shopping/types/payment_identity.json)
+* **Identity Schema:** [schemas/common/types/payment_identity.json](site:schemas/common/types/payment_identity.json)

docs/specification/payment/actions/device-data-collection.md → docs/specification/payment/extensions/actions/device-data-collection.md

@@ -20,7 +20,7 @@ This specification defines the device data collection Action type declared by
 the [Payment Authentication extension](../authentication.md):
 
 ```text
-dev.ucp.payment.device_data_collection
+dev.ucp.common.payment.device_data_collection
 ```
 
 It asks the Platform to mount an invisible payment-authentication surface to
@@ -56,11 +56,11 @@ will not wait for, the Business **MUST NOT** emit an Action.
 
 The Action is emitted under its type key:
 
-<!-- ucp:example schema=shopping/payment_authentication def=dev.ucp.shopping.checkout extract=$.actions target=$.actions op=read -->
+<!-- ucp:example schema=common/payment_authentication def=dev.ucp.shopping.checkout extract=$.actions target=$.actions op=read -->
 ```json
 {
   "actions": {
-    "dev.ucp.payment.device_data_collection": [
+    "dev.ucp.common.payment.device_data_collection": [
       {
         "id": "ddc-1",
         "config": {
@@ -74,7 +74,7 @@ The Action is emitted under its type key:
 ```
 
 The config shape is defined inline by the
-[Payment Authentication extension schema](site:schemas/shopping/payment_authentication.json).
+[Payment Authentication extension schema](site:schemas/common/payment_authentication.json).
 
 | Field | Type | Required | Notes |
 | :---- | :--- | :------- | :---- |
@@ -100,7 +100,7 @@ The Platform **MUST**:
 
 Mounting the surface **MUST** follow the shared
 [Payment Authentication rendering contract](../authentication.md#surface-rendering-and-notifications)
-and [Embedded Protocol security requirements](../../embedded-protocol.md#security).
+and [Embedded Protocol security requirements](../../../embedded-protocol.md#security).
 
 On the web the surface is typically a hidden iframe. A native Platform may use
 an isolated webview or equivalent browser surface. It **MUST NOT** be visible to

docs/specification/payment/actions/three-ds-challenge.md → docs/specification/payment/extensions/actions/three-ds-challenge.md

@@ -20,7 +20,7 @@ This specification defines the 3DS challenge Action type declared by the
 [Payment Authentication extension](../authentication.md):
 
 ```text
-dev.ucp.payment.three_ds_challenge
+dev.ucp.common.payment.three_ds_challenge
 ```
 
 It asks the Platform to present a buyer-facing payment-authentication surface to
@@ -55,11 +55,11 @@ challenge occurrence.
 
 The Action is emitted under its type key:
 
-<!-- ucp:example schema=shopping/payment_authentication def=dev.ucp.shopping.checkout extract=$.actions target=$.actions op=read -->
+<!-- ucp:example schema=common/payment_authentication def=dev.ucp.shopping.checkout extract=$.actions target=$.actions op=read -->
 ```json
 {
   "actions": {
-    "dev.ucp.payment.three_ds_challenge": [
+    "dev.ucp.common.payment.three_ds_challenge": [
       {
         "id": "three-ds-challenge-1",
         "config": {
@@ -73,7 +73,7 @@ The Action is emitted under its type key:
 ```
 
 The config shape is defined inline by the
-[Payment Authentication extension schema](site:schemas/shopping/payment_authentication.json).
+[Payment Authentication extension schema](site:schemas/common/payment_authentication.json).
 
 | Field | Type | Required | Notes |
 | :---- | :--- | :------- | :---- |
@@ -102,7 +102,7 @@ The Platform **MUST**:
 
 Mounting the surface **MUST** follow the shared
 [Payment Authentication rendering contract](../authentication.md#surface-rendering-and-notifications)
-and [Embedded Protocol security requirements](../../embedded-protocol.md#security).
+and [Embedded Protocol security requirements](../../../embedded-protocol.md#security).
 
 On the web the surface may be a full-page frame, modal frame, or separate window
 when the negotiated handler defines that presentation and its security policy.