HYBRID-CHAINDEVELOPERS
DOCUMENTATIONv2

OPERATE · MODULE 12

Commerce

Onboard workspace merchants, define catalog and checkout policy, create structured invoices, observe rotational-wallet payments, and hand verified evidence into separately owned settlement and fulfillment lifecycles.

BUSINESS CASES

Where this module fits

  • merchant onboarding and policy review
  • catalog and structured invoice creation
  • checkout capability issuance
  • invoice cancellation before payment
  • rotational-wallet observation and reconciliation
  • merchant settlement handoff
  • Commerce-backed digital-asset delivery

PRIMARY CONSUMERS

Who integrates it

  • merchant platforms
  • commerce operators
  • checkout agents

PREREQUISITES

What must exist first

  • commerce:write and merchant administration authority in the authenticated workspace
  • eligible merchant operational wallet, settlement currency, checkout rails, compliance posture, and customer-data policy
  • fresh purpose-bound step-up and RFC 9421 signature for consequential planned mutations

RECOMMENDED WORKFLOW

Compose the module safely.

  1. 01

    create a PENDING_REVIEW merchant profile bound to an eligible operational destination

  2. 02

    activate merchant capabilities only through a separate reviewed lifecycle

  3. 03

    create catalog products and invoices from server-validated line items and totals

  4. 04

    observe checkout and payment evidence from Payments and rotational wallets

  5. 05

    cancel only unpaid eligible invoices or enter separately owned refund and exception workflows

  6. 06

    settle an eligible rotational wallet through its exact owner and verify retained settlement evidence

MODULE CONTRACTS

Every mapped endpoint

Each operation states whether its request shape is authoritative in OpenAPI, reviewed as a planning profile, or intentionally left as an outline pending an owner schema.

GETList wallets/api/v2/operational-walletsList purpose-built AI and merchant MPC wallets in the authenticated workspace and signed network context.›POSTCreate wallet/api/v2/operational-walletsCreate a purpose-built AI or merchant operational wallet that requires an independent MPC enrollment and settles only to the same-context primary treasury.›GETGet wallet/api/v2/operational-wallets/{wallet_uuid}Return one purpose-built operational MPC wallet, its independent enrollment and activation posture, balance, and primary treasury settlement target.›POSTPause wallet/api/v2/operational-wallets/{wallet_uuid}/pausePause new operational use while retaining the wallet, balance, settlement target, and audit evidence.›POSTResume wallet/api/v2/operational-wallets/{wallet_uuid}/resumeResume an independently activated operational wallet without changing its workspace, network, purpose, or settlement target.›POSTRevoke wallet/api/v2/operational-wallets/{wallet_uuid}/revokePermanently retire an operational wallet while retaining enrollment, activation, settlement, and event commitments.›POSTRequest treasury settlement/api/v2/operational-wallets/{wallet_uuid}/settlementsCreate an idempotent settlement request from an active operational wallet to the immutable primary treasury in the same workspace and network.›GETGet allocation summary/api/v2/operational-wallets/summaryReturn primary, AI, merchant, deployed operational, and pending-settlement allocation for the authenticated workspace and network.›GETList invoices/api/v2/commerce/invoicesList merchant invoices and payment lifecycle state.›POSTCreate invoice/api/v2/commerce/invoicesCreate a checkout-backed merchant invoice with customer, line items, settlement, and expiry terms.›GETGet invoice/api/v2/commerce/invoices/{invoice_uuid}Return invoice terms, checkout destination, payment detection, and settlement evidence.›POSTCancel invoice/api/v2/commerce/invoices/{invoice_uuid}/cancellationsCancel an unpaid eligible invoice.›GETList merchant profiles/api/v2/commerce/merchantsList merchant profiles available to the active workspace.›POSTCreate merchant profile/api/v2/commerce/merchantsCreate a merchant operating profile with settlement and checkout policy.›POSTActivate merchant profile/api/v2/commerce/merchants/{merchant_uuid}/activationsActivate a reviewed merchant profile at an exact version so its catalog and invoice lifecycle can proceed without granting settlement authority.›GETList products/api/v2/commerce/productsList reusable merchant catalog products.›POSTCreate product/api/v2/commerce/productsCreate a reusable product with pricing, currency, fulfillment, and metadata.›POSTPublish product/api/v2/commerce/products/{product_uuid}/publicationsPublish one reviewed catalog draft at an exact version so it can be selected for invoice line items.›POSTSynchronize rotational wallets/api/v2/commerce/rotational-wallet-synchronizationsRequest idempotent synchronization and reconciliation of merchant rotational wallets.›GETList rotational wallets/api/v2/commerce/rotational-walletsList invoice-scoped rotational wallets and reconciliation posture.›POSTSettle rotational wallet/api/v2/commerce/rotational-wallets/{wallet_uuid}/settlementsPlanned capability: authorize fee-aware settlement of one rotational wallet into its merchant destination.›GETGet all merchants/api/v2/merchant/allPlanned capability: list all merchants through the authoritative commerce service boundary.›GETGet all invoices/api/v2/merchant/all_invoicesPlanned capability: list all invoices through the authoritative commerce service boundary.›POSTCancel invoice/api/v2/merchant/cancel_invoicePlanned capability: apply the requested transition to invoice through the authoritative commerce service boundary.›GETGet checkout data/api/v2/merchant/checkoutPlanned capability: list checkout data through the authoritative commerce service boundary.›POSTCreate new merchant/api/v2/merchant/createPlanned capability: apply the requested transition to new merchant through the authoritative commerce service boundary.›GETGet merchant details/api/v2/merchant/detailsPlanned capability: list merchant details through the authoritative commerce service boundary.›POSTSet merchant details/api/v2/merchant/detailsPlanned capability: apply the requested transition to set merchant details through the authoritative commerce service boundary.›POSTChange enabled status/api/v2/merchant/enabled_statusPlanned capability: apply the requested transition to change enabled status through the authoritative commerce service boundary.›GETGet invoice status/api/v2/merchant/invoice_statusPlanned capability: return the current posture for invoice status through the authoritative commerce service boundary.›POSTCreate new invoice/api/v2/merchant/new_invoicePlanned capability: apply the requested transition to new invoice through the authoritative commerce service boundary.›GETGet merchants overview/api/v2/merchant/overviewPlanned capability: list merchants overview through the authoritative commerce service boundary.›POSTReserve payment wallet/api/v2/merchant/reserve_walletPlanned capability: apply the requested transition to reserve payment wallet through the authoritative commerce service boundary.›GETGet all rotational wallets/api/v2/merchant/rotational_walletsPlanned capability: list all rotational wallets through the authoritative commerce service boundary.›POSTSettle balances/api/v2/merchant/settle_balancesPlanned capability: apply the requested transition to settle balances through the authoritative commerce service boundary.›GETGet all settlements/api/v2/merchant/settlementsPlanned capability: list all settlements through the authoritative commerce service boundary.›GETSync all rotational wallets/api/v2/merchant/sync_rotational_walletsPlanned capability: list sync all rotational wallets through the authoritative commerce service boundary.›GETList invoices/api/v2/billing/invoicesPlanned capability: list cursor-paginated billing invoices for the caller.›
RELATED MODULESReturn to the complete V2 directory ↗