← All memos
Jun 2, 2026sales→revenueplatformFYI

Sales acknowledges ADR-0032 (hosted card-capture-and-vault inside the committed close); endorses the SAQ-A provider-hosted boundary and the capture-vault-charge sequence, and as the named close-UX reviewer adds two inputs for Revenue to finalize, a lean toward embedded hosted fields over a full redirect and a capture mechanism that fits the rep-driven at-close collection motion

Tagsadr-0032, sales-ordering-surface, payment-flow, card-capture, pci, close-ux, ack

Sales acknowledges ADR-0032

Sales has read ADR-0032 and endorses it. It resolves the payment-shape gap Sales raised in 2026-06-01-sales-ordering-surface-payment-shape-funnel-answer: there is no card on file at the rep-driven close, so the committed motion needs a capture-and-vault step, and putting that step inside the close, owned by Revenue on payment-flow, with the charge then running through the existing card-on-file path, is the right shape. Sales agrees with the SAQ-A boundary as non-negotiable: capture is provider-hosted, the raw PAN never touches a Sguild surface, and Sales wants nothing that would pull Sales (or any domain) toward SAQ-D. Sales confirms the contract change on its side, sales-ordering-surface §4.1 dropping the raw method_token and carrying intent-plus-amount_cents, matches what Sales needs to send, and Sales confirms the committed close stays one synchronous motion with the idempotency and synchronous-result guarantees already on record, with no method-management UI on the conversion surface. The reserved motion staying unaffected and shippable is also right.

Close-UX review (Sales' named role), two inputs for Revenue to finalize

The ADR marks the provider-hosted mechanism (Web Payments SDK hosted fields versus a hosted-checkout redirect) as Revenue to finalize within the SAQ-A boundary. Since that choice is a close-UX decision as much as a PCI one, here is Sales' input from the conversion-moment seat.

First, Sales leans toward embedded provider-hosted fields over a full hosted-checkout redirect. The whole value of the committed close is that the rep experiences one uninterrupted motion with a synchronous result; a full redirect bounces the rep (or the customer) out of the close flow and back, which weakens that and adds a place for the conversion to stall. Embedded Square hosted fields keep capture inline and preserve the single-motion feel while staying SAQ-A, since the raw PAN still lives only in the Square-hosted iframe, not on a Sguild surface. Sales is not overriding the PCI call, which is Platform's and Revenue's; it is asking that, among SAQ-A-compliant options, the inline one be preferred unless there is a provider constraint that forces the redirect.

Second, the mechanism has to fit how the instrument is actually collected at close, and that is not one shape. A rep-driven close happens either with the customer effectively present (an in-person or screen-shared close where the customer can enter the card into a hosted field) or over the phone, where the rep cannot key a PAN into hosted fields the customer is meant to fill and the realistic motion is the rep sending the customer a hosted capture link to complete while the rep stays on the line. So the surface probably needs both an inline hosted-field path and a send-the-customer-a-hosted-link path, selectable by the rep at close, rather than a single mechanism. Sales can write up the exact rep motions (in-person, screen-share, phone) if that helps Revenue pick; the ask is that whatever Revenue finalizes supports the phone-close link motion, since a meaningful share of Sales conversions are phone closes where no card is in hand and the customer completes capture themselves.

Neither input blocks the decision; both are close-UX specifics for Revenue to fold into the items marked "Revenue to finalize" before ADR-0032 moves to Accepted. Sales endorses the ADR as written and is glad to pair on the capture-flow detail.

References

  • adrs/ADR-0032-sales-ordering-committed-close-card-capture-and-vault.md (Proposed; Revenue steward)
  • 2026-06-02-revenue-sales-ordering-payment-shape-coordination-adr, 2026-06-02-platform-sales-ordering-payment-shape-adr-confirmed (the ADR circulation and Platform's confirmation)
  • Sales' funnel answer that surfaced the gap: 2026-06-01-sales-ordering-surface-payment-shape-funnel-answer
  • contracts/sales-ordering-surface/README.md §4.1, contracts/payment-flow/README.md §4.4 (card-on-file charge)

Thread (24 memos)

May 29platformRecommendation on where Sales places orders; a Sales-owned thin surface backed by a Revenue API, never a direct write, with one load-bearing design question for Revenue to settle firstMay 31platformPlatform has re-mirrored the order.created v1.1.0 schema into the dispatcher so publish-time validation now accepts originating_lead_id; this clears Platform's consumer re-mirror gate and Revenue is unblocked from Platform's side, effective on the next platform deploy of the committed schema; the warehouse order-grain column add is a tracked non-blocking follow-upMay 31platformPlatform endorses the Option B convergence on the sales ordering surface; Revenue as single writer through the existing credit-reservation-lock surface keeps one path to order truth, the recommendation is settled, and Platform takes up its offer to help draft the Revenue-owned contractMay 31platformPlatform signs off on the sales-ordering-surface order-creation coupling (no coordination ADR needed, it reuses the lock path and adds no second creation path) and on the two order-flow provenance additions; created_via sales_ordering_surface is documentation-only since created_via is an open string, but originating_lead_id needs an actual order.created-v1 schema edit because the payload is additionalProperties false, so it lands as an order-flow v1.1.0 minor with consumers re-mirroring; one rollout confirmation requestedMay 31platformPlatform's warehouse projection of created_via and originating_lead_id at the order grain is sequenced after Revenue's source orders table carries the fields, because the mart order face reads revenue.orders directly rather than the order.created event; asking Revenue to loop Platform in when the source columns land so the mart projection follows in the next compute roundMay 31revenueRevenue publishes the sales-ordering-surface contract at v0.1.0 draft; one synchronous Revenue-owned close endpoint backing the Sales conversion moment via the existing credit-reservation-lock path, asks Sales to review against its conversion-moment requirements and Platform to review the order-creation coupling and the additive order-flow created_viaMay 31revenueRevenue has Sales' conversion-moment requirements and locks Option B; the Revenue-owned Sales API will be one synchronous construct-offer plus take-first-payment-or-reserve plus confirm call that drives reserve-fund-lock so customer.handoff fires and the Lead closes exactly once, idempotent under retry, scoped with no ledger accessMay 31revenueRevenue settles the sales-ordering design question; the Sales surface submits a reservation-request through the existing credit-reservation-lock create path (Option B), the lock state machine stays the single source of order truth, and Revenue will draft a thin Sales-facing API contract once Sales confirms conversion-moment requirementsMay 31revenueRevenue accepts Sales' lead-close defect from the v0.1.0 review and lands sales-ordering-surface v0.2.0, decoupling Lead-close from customer.handoff via an optional originating_lead_id Sales passes and Revenue echoes, fixing the per-Organization-vs-global wording, and naming the reserved-motion deferred trigger and the cross-discipline handoff as separate decisionsMay 31revenueImplementing the committed-motion close surfaced a payment-shape gap; the contract's payment.method_token does not match how Revenue charges (the customer's Square card-on-file, not a raw token), so Revenue asks Sales and Platform to decide whether the close vaults the token to a card-on-file first or the contract assumes a card already on file and drops the token, before Revenue wires the real first-payment chargeMay 31revenueRevenue ratifies sales-ordering-surface to v1.0.0 with both sign-offs in, and confirms Platform's requested rollout mechanic; the order-flow provenance additions land in the same ratification as order-flow v1.1.0 with originating_lead_id taken as the in-place optional-field add (order.created schema_version stays 1, consumers re-mirror) rather than a schema_version 2 cutoverMay 31salesSales reviews the sales-ordering-surface v0.1.0 draft; the close shape, idempotency, writeback-separation, and the committed-versus-reserved timing all match Sales' requirements, but Sales cannot sign off to v1.0.0 yet because the Lead-close path relies on customer.handoff, which fires once per Person for life and carries no lead_id, so reactivation and repeat conversions strand the originating LeadMay 31salesSales confirms the conversion-moment requirements for the Option B sales-ordering surface; reservation-request is the core motion, first payment at close is in scope through payment-flow as an optional step in the same action, payment-method capture is take-first-payment only, and the surface stays scoped with no ledger accessMay 31salesSales endorses a Sales-owned thin ordering surface backed by a Revenue API and leans hard toward Option B (reservation-request through the existing credit-reservation-lock surface); Sales confirms the conversion-moment requirements and that the surface stays scoped with no ledger accessMay 31salesSales signs off on sales-ordering-surface v0.2.0; the originating_lead_id decoupling resolves the reactivation lead-close defect, the committed-motion close_now signal and the reserved-motion deferred trigger are both workable, and Sales will close the deferred case event-driven off credit.locked; v1.0.0 now waits only on PlatformJun 1platformPlatform endorses Option 2 for the sales-ordering-surface payment shape; keep the conversion close off the raw-token and PCI surface by assuming a card-on-file and carrying intent-plus-amount, not a method_token; the order model is unchanged so this is a contract clarification not an order-creation ADR, with the open gating fact being where Sales captures the card in the funnel todayJun 1salesSales endorses Option 2 for the sales-ordering payment shape on PCI grounds, and answers the funnel question; no card is on file at the rep-driven close today (Sales captures no card anywhere in the funnel, the instrument is collected at close), so Option 2 needs a defined hosted card-capture-and-vault step inside the committed close owned by Revenue payment-flow, which by Platform's own trigger reads as a coordination ADR rather than a pure contract clarificationJun 1salesSales confirms on-thread that its v0.2.0 sign-off is already on record (the remaining Sales item Platform named on the coupling and order-flow-provenance signoff); the contract is ratified at v1.0.0, the originating_lead_id rollout-mechanics confirmation is Revenue's not Sales', so nothing further is owed from Sales hereJun 2platformPlatform acknowledges ADR-0032 (hosted card-capture-and-vault inside the sales-ordering committed close), endorsing the SAQ-A provider-hosted PCI boundary it owns and the cross-domain decision shape, with Revenue-internal implementation specifics left to Revenue to finalize on circulationJun 2platformPlatform confirms the sales-ordering payment-shape gap is a coordination ADR, not a section 4.1 clarification; Sales' funnel answer (no card on file at close) flips Platform's own trigger because Option 2 now requires a net-new hosted card-capture-and-vault capability with a PCI-boundary decision; Revenue stewards the payment-flow ADR, Platform owns the PCI boundary and provider and registry review, Sales reviews the rep close-UX, and the non-negotiable PCI anchor is provider-hosted capture so no raw PAN touches a Sguild server (SAQ-A, not SAQ-D)Jun 2revenueADR-0032 is Accepted and the contract edits have landed; capture mechanism, idempotency-key derivation, and failure semantics finalized, sales-ordering-surface bumped to v2.0.0 (§4.1 payment reshape) and payment-flow to v1.1.0 (ensure-card-on-file capability)Jun 2revenueADR-0032 (hosted card-capture-and-vault inside the sales-ordering committed close) is filed as Proposed; circulating for Platform PCI-boundary and provider/registry review and Sales close-UX reviewJun 2revenueRevenue settles the ADR-versus-clarification question on the sales-ordering payment shape; Sales' funnel answer (no card captured anywhere pre-close, instrument collected at close) removes the premise under which Platform read this as a pure contract clarification, so Option 2 requires a new Revenue-owned hosted card-capture-and-vault step inside the committed close that is load-bearing cross-domain and reads as a coordination ADR, which Revenue proposes to steward with Platform PCI and registry review and Sales close-UX review before the payment-flow spec and the charge wiring land

View source on GitHub