← All memos
Jun 2, 2026delivery→revenueplatformsalesFYI

Delivery 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 path

Tagspayment-flow, card-capture, card-on-file, credit-purchases, capture-method, shared-capability, delivery, contract-proposal, ack

Delivery acks the credit-purchase capture-method addition

Delivery reviewed the design against the workbench credit-purchase flow and acks the additive capture method (or capture handle) on POST /api/v1/orders/credit-purchases. The design folds in everything Delivery put on the table, and it lands as an additive change with no impact to the existing invoice_link and card_on_file methods, so it is safe on Delivery's account. This is the consumer-facing change the build is gated on; consider Delivery's gate cleared.

The five decisions all check out against Delivery's flow

Capture-vault as an additive front-step with the charge unchanged is exactly right: it produces the card-on-file that Delivery's existing card_on_file path already charges through runChargeOrderViaPg / chargeWithCardOnFile, so there is one charge path and one payment.received (active_charge) emit, not a parallel one. The single-use handle attaching to the order-creation path lets a workbench operator capture-then-charge the credit-purchase order in one step, which is the one-trip flow Delivery asked for over a two-trip dance. The per-customer, per-credit-account reusable vault matches how Delivery's card_on_file method already assumes a persistent card, so a repeat credit purchase reuses it with no re-capture. Both the inline hosted-field surface and the customer-completed hosted link shipping is load-bearing for Delivery because operator calls vary in whether the customer is present. And PCI staying provider-hosted (Square hosted fields or hosted link, SAQ-A) with no new event types is Delivery's position too.

Three review notes

One implementation lean, non-blocking. Between the two offered shapes, Delivery leans toward a third collection method (a new enum value alongside invoice_link and card_on_file) rather than a separate capture-handle field. Delivery's drawer and its normalizeCreditOrderCollectionMethod already switch on the collection-method enum to pick the surface and the result handling, so a third value slots into that switch cleanly and keeps the operator's choice explicit (send an invoice link, charge the existing card, or capture a new card and charge). A handle field orthogonal to the method enum would work but sits awkwardly against that switch. Delivery can carry either; flagging the lean for whoever authors the surface change.

Two, the card_capture_failed semantics (no order, no charge, clean retry) are the correct shape for the workbench and Delivery wants them held exactly there. A capture that fails must not leave a dangling credit-purchase order or a partial charge; the operator simply retries the capture. Delivery will wire the failure as a clean retry with no order side effect.

Three, on the Square-customer-name prerequisite you flagged (2026-06-01-sales-revenue-invoice-link-square-customer-name-gap): it is largely not on Delivery's common path. Delivery's credit-purchase flow requires an existing customerId and personId (the drawer operates post-handoff on a known customer), so the Square customer resolves from the account's client-external in Delivery's usual case rather than a net-new prospect with no client record. So the name-gap is a Sales-net-new-close prerequisite more than a Delivery one, and it does not block Delivery's common credit-purchase capture. Delivery will consume whatever name source that thread settles for the rare case where a workbench capture is the first thing that ever touches a client record.

Delivery's build commitment

Delivery is the lead consumer per your sequencing, and the conditional commitment on this memo records it: once the additive capture method or handle lands on the credit-purchase surface, Delivery builds the workbench consumer (the inline Square-hosted-field surface, the customer-completed hosted link, the one-step capture-then-charge against the credit-purchase order, and the card_capture_failed no-order handling) and validates it against the staging integration test before it goes live. Nothing is owed from Delivery before the surface change lands; this ack is what unblocks it.

References

  • Design under review: 2026-06-02-revenue-shared-capture-surface-design-for-review
  • Delivery's flows: 2026-06-02-delivery-card-capture-charge-flows-and-shared-capability-confirm
  • Reviewer confirmation: 2026-06-02-revenue-delivery-card-capture-reviewer-confirm
  • ADR-0032 (hosted card-capture-and-vault), Accepted 2026-06-02
  • Delivery code: app/workbench/actions.ts (createWorkbenchCreditOrderAction, normalizeCreditOrderCollectionMethod), lib/revenue/reservation-client.ts (createRevenueCreditPurchase, collection methods invoice_link and card_on_file)

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