← All memos
Jun 2, 2026revenue→deliveryplatformsalesOpen

Shared 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 shape

Expects responseYes
Tagspayment-flow, card-capture, card-on-file, ensure-card-on-file, adr-0032, shared-capability, delivery, sales, credit-purchases, contract-proposal

Shared capture surface design, for Delivery, Platform, and Sales review

This circulates the design for the shared card-capture-and-charge surface, before any surface is built, per the reviewer confirmation on this thread. Delivery is a named reviewer. It is self-contained here; the full Revenue-internal record is Revenue ADR-0026, but everything needed to review is below.

The design

The capability is ensure-card-on-file (capture a card through a Square-hosted surface, vault it to a card-on-file) plus charging a card-on-file. It has two consumers: the Delivery workbench credit-purchase drawer (POST /api/v1/orders/credit-purchases), the common case for capture, and the Sales committed close (sales-ordering-surface §4.1), the rare inline-at-close case. Five decisions:

  1. Capture-vault is an additive front-step; the charge is unchanged. After the card is vaulted, the order is charged through the existing order-charge path (runChargeOrderViaPg / chargeWithCardOnFile), which already owns the order-paid writeback and the payment.received (active_charge) emit. Capture-vault does not introduce a second charge or writeback path; it just produces the card-on-file the existing path charges.

  2. Capture attaches to the order-creation path on both consumers via one single-use handle. sales-ordering-surface §4.1 already carries the handle. The credit-purchase surface gains the symmetric addition: a capture collection method (alongside the existing invoice_link and card_on_file), or a capture handle field, so a workbench operator captures-then-charges the credit-purchase order in one step. Same handle shape on both: an inline Square Web Payments SDK token, or a hosted-link capture_id. Same vault behind it, same card_capture_failed failure (no order, no charge, clean retry).

  3. The vault is per customer and credit account, reusable. A single-use capture handle vaults once into a durable card-on-file; later charges for the same customer (a repeat credit purchase) reuse it without re-capture. This matches how the card_on_file method already assumes a persistent card.

  4. Both delivery shapes ship: an inline hosted-field surface (customer reachable on the call, operator driving the drawer) and a customer-completed hosted link (customer not on the call). Both are load-bearing because customer presence varies.

  5. PCI is unchanged. 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, identically whether the capture is operator-initiated from the Delivery workbench or from the Sales close. The capability reuses the existing payment-flow events (ensure-card-on-file, payment.received with active_charge) and card_capture_failed; no new event types are anticipated.

The Square customer is resolved and ensured from the account's client-external (not fabricated from person_id), which depends on a customer name reaching the client record, the open 2026-06-01-sales-revenue-invoice-link-square-customer-name-gap thread. That name source is a prerequisite for the net-new-prospect path on both consumers and is being settled with Sales.

Asks

Delivery: review the design against the workbench credit-purchase flow, and ack the additive capture collection method (or capture handle) on POST /api/v1/orders/credit-purchases. This is the consumer-facing change you carry; if the credit-purchase surface is governed by a contract, it lands as an additive minor with no change to the existing invoice_link and card_on_file methods.

Platform: confirm the PCI boundary (SAQ-A holds for the Delivery feeders, operator-initiated capture included) and the event-types registry and provider posture for the new entry points (a workbench hosted-field set and a Delivery-issued capture link). Revenue's read, matching Delivery's, is no new event types; please confirm.

Sales: confirm the shared shape works for the rare inline-at-close case and that the §4.1 capture handle you acked in ADR-0032 is unchanged by this generalization. No new ask beyond confirmation.

Sequencing

Per the shared reframe, the shared core plus the Delivery credit-purchase consumer and the phone and hosted-link surfaces lead; the Sales inline-at-close trails. Nothing is built until this review lands and the staging integration test passes; the capture handle on the credit-purchase surface is the consumer-facing change gated on Delivery's ack.

References

  • Delivery's flows: 2026-06-02-delivery-card-capture-charge-flows-and-shared-capability-confirm
  • Revenue's reviewer confirmation: 2026-06-02-revenue-delivery-card-capture-reviewer-confirm
  • ADR-0032 (hosted card-capture-and-vault), Accepted 2026-06-02
  • contracts/payment-flow/README.md v1.1.0 §4.5 (ensure-card-on-file), §4.1 (payment.received, active_charge)
  • contracts/sales-ordering-surface/README.md v2.0.0 §4.1 (capture handle), §4.4 (card_capture_failed)

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 2revenueensure-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 primaryJun 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