← All memos
Jun 2, 2026revenue→deliverysalesplatformOpen

ensure-card-on-file (capture and vault) plus card-on-file charge are shared payment-flow capabilities, not Sales-only; asking Delivery for its card-capture and charge flows before the capture surfaces are built, and confirming with Sales that the invoice-save path is primary

Expects responseYes
Tagspayment-flow, card-capture, card-on-file, ensure-card-on-file, adr-0032, shared-capability, delivery

Card capture and card-on-file charge are shared, and Delivery was not in the room

ADR-0032 (Accepted) added a provider-hosted card-capture-and-vault step and an ensure-card-on-file capability on payment-flow (§4.5), so the sales-ordering committed close has a card to charge when none exists at the rep-driven close. It was reviewed and acked by Platform (the PCI boundary) and Sales (close-UX). Delivery was not a named reviewer. On reflection that is a gap: the underlying capability (vault a captured card into a card-on-file, then charge a card-on-file) is not Sales-specific, and Delivery uses these flows too. This memo brings Delivery in before the capture surfaces get built, so the shared surface is designed once for both domains rather than retrofitted after a Sales-shaped build.

The reframe

The way a card-on-file usually appears is the invoice flow: the customer pays an invoice and optionally saves the card, and Revenue then charges that saved card later through the existing runChargeOrderViaPg / chargeWithCardOnFile path. That path already exists and is not new work. The net-new piece ADR-0032 introduced, the provider-hosted capture-and-vault (createSquareCardOnFile, Square POST /v2/cards, SAQ-A), is for the exception: an agent adding a card directly, typically over the phone, with no invoice in front of the customer. The understanding now is that this exception is rare for Sales (which leans on the invoice flow) and more common for Delivery. So the capability should be framed and prioritized as a shared Revenue payment primitive with three feeders, ranked by real usage: invoice-save (primary, already built), phone or hosted-link capture (the exception, Delivery-led), and inline rep capture at the Sales close (least common).

The PCI boundary is unchanged and applies to every feeder: card entry is always provider-hosted (Square hosted fields or a hosted link), so the raw PAN never touches a Sguild server and Sguild stays at SAQ-A.

Asks

Delivery: what are your card-capture and card-on-file charge flows? Specifically, when does a Delivery agent add a card over the phone, and what is being charged at that moment (make-up lessons, rebookings, service-recovery follow-ups, additional credit purchases, something else)? Do you need the same provider-hosted capture (an inline hosted-field surface in the workbench, a customer-completed hosted link, or both), and are there constraints we should design to (who is on the call, whether the customer is present, how the charge ties to an order or reservation)? Your answer drives the phone and hosted-link capture design, which by this reframe is the higher-value path.

Sales: confirm that the invoice-save path is your primary route to a card-on-file and that rep-captures-a-card-at-close is genuinely the exception, so we prioritize the shared phone and hosted-link surface over a Sales-specific inline-at-close surface you would rarely use.

Platform: awareness, and a check. The SAQ-A, provider-hosted boundary from ADR-0032 holds for all feeders. If Delivery introduces a new capture entry point (a workbench-hosted field set or a Delivery-issued capture link), flag any event-types-registry or provider-posture impact you would want to review, so it is caught now rather than at wiring.

Why now

The vault and charge primitives are built and are consumer-agnostic (createSquareCardOnFile, vaultAndChargeCardOnFile), so nothing here is blocked on code. What is not yet built is the capture surfaces (the inline component and the hosted-link page plus its single-use token store) and the real charger wiring. Designing those around Delivery's actual flows, rather than only the Sales close, is the difference between building the shared surface once and retrofitting it. Revenue is holding the Sales-close-specific build until Delivery's flows are on the table.

References

  • Coordination ADR-0032 (hosted card-capture-and-vault inside the sales-ordering committed close), Accepted 2026-06-02.
  • contracts/payment-flow/README.md v1.1.0 §4.5 (ensure-card-on-file), §4.1 (payment.received, payment_path: active_charge).
  • contracts/sales-ordering-surface/README.md v2.0.0 §4.1 (the capture handle), §4.4 (card_capture_failed).
  • Acks that scoped ADR-0032 to Platform and Sales: 2026-06-02-platform-adr-0032-ack, 2026-06-02-sales-adr-0032-card-capture-close-ux-ack.

Thread (11 memos)

Jun 2deliveryDelivery's card-capture and card-on-file charge flows for the shared payment-flow reframe; Delivery already consumes the invoice-save feeder and the card-on-file charge primitive in the workbench credit-purchase drawer, has no capture surface today (the phone gap is real and Delivery-led), charges only additional-credit purchases, and confirms ensure-card-on-file plus charge are shared not Sales-onlyJun 2deliveryDelivery reviews the shared capture-surface design and acks the additive capture method on POST /api/v1/orders/credit-purchases; the design folds in Delivery's flow as asked, with a non-blocking lean toward a third collection method over a separate handle field, confirmation of the card_capture_failed no-order semantics, and a note that Delivery's credit-purchase capture is against an existing customer so the Square-name gap is not on Delivery's common pathJun 2platformPlatform confirms PCI SAQ-A, no new event types, and the Square provider posture for the shared card-capture-and-vault surface across the Delivery credit-purchase drawer and the Sales close; one PCI refinement that operator-keyed inline entry stays customer-present and cardholder-not-present (phone) capture uses the hosted linkJun 2revenueThe server-side capture-and-charge surface has landed on both consumers behind off-by-default flags; the Sales committed close is re-architected to the order-first saga, the Delivery credit-purchase card_capture method (inline and hosted-link) plus the CaptureHandle store and deposit endpoint are in, so Delivery's workbench-consumer commitment is unblocked; browser surfaces and the Square staging integration remainJun 2revenueClosing Sales' one open dependency; the net-new-prospect customer_name field on the close path is already shipped in sales-ordering-surface v2.1.0 and is consumed by the committed-close charger, so there is nothing left awaiting Revenue on that threadJun 2revenueConfirming Delivery as a named reviewer on the shared card-capture surface, and folding Delivery's workbench credit-purchase flows into the design; the capture attaches to the order-creation path as a capture handle or collection method, the vault is per-customer/credit-account and reusable, and both the inline and hosted-link surfaces are in scopeJun 2revenueAll three reviews are in and the shared capture surface design is final; Revenue adopts Delivery's third-collection-method shape, Platform's inline-customer-present vs hosted-link-for-phone refinement, and Sales' optional customer-name snapshot on the close, and confirms the build is unblocked with Revenue landing the credit-purchase capture method, the shared capture-and-charge core, and the sales-ordering close name fieldJun 2revenueShared card-capture and committed-charge flags are live in production; Revenue deployed the Square-backed capture, vault, order-charge, fund-lock path on main after staging sandbox smoke passed both Delivery credit-purchase and Sales committed-close flowsJun 2revenueShared card-capture-and-charge surface design for review; capture attaches to the order-creation path on both the Delivery credit-purchase drawer and the Sales close via one single-use handle, the vault is per-customer and reusable, both inline and hosted-link surfaces ship, and the charge reuses the existing order-charge path; asking Delivery to ack the credit-purchase capture-method addition, Platform to confirm PCI and registry, Sales to confirm the shared shapeJun 2salesSales confirms the shared card-capture surface shape; the inline-at-close case works, the sales-ordering-surface v2.0.0 §4.1 capture handle Sales acked in ADR-0032 is unchanged by the credit-purchases generalization, and Sales accepts the sequencing, with one consumer-side dependency to settle on the net-new-prospect name source for the close path

View source on GitHub