Module F (Finance — Tenders / Tax / Gift Cards) — Functional Decomposition

Artifact layer. Third of three Canary module artifact layers: 1. Canonical spec (vendor-neutral) — Canary-Retail-Brain/modules/F-finance.md 2. Code/schema crosswalk (Canary-specific) — Brain/wiki/canary-module-f-finance.md 3. Functional decomposition (Counterpoint-substrate-aware, L2/L3 + user stories) — this card

Governing thesis

F owns the tender, tax, and gift-card substrate for the spine. Counterpoint exposes a flexible PayCode taxonomy (any tender — cash, card, AR, gift card, alternative-payment-rail — definable by the customer), a TaxCode list with multi-authority preservation per Document, a GiftCard family with per-code template support, and a Secure Pay tokenization surface. Every payment activity flows through T's Document polling (PS_DOC_PMT[] is per-Document) — F surfaces the configuration, T surfaces the activity, and the two together feed Q's tender-mix anomalies and the AR-vs-tender reconciliation that bridges to R.

For a Lawn & Garden tenant specifically, three vertical realities shape F's posture: (1) multi-tier tender mix is real — landscaper customers pay AR (open ledger), retail walk-ins pay card or cash, gift cards are seasonally heavy (Mother's Day / holidays); (2) multi-authority tax stacking is the norm — city + county + state preserved per Document line is required for tax-authority reconciliation without external joins; (3) alternative payment rails are an opportunity — Zelle / Venmo / Cash App / Bitcoin Lightning can fit in the PayCode taxonomy for vendor-side payments, and Canary can pull the wallet activity into CRDM as a Canary-native option-(e) wedge.

F is ● Full direct in every Counterpoint Solution Map cell, but the cell hides three concerns: (1) PayCode + TaxCode are cached server-side 24h so polling discipline matters, (2) the Secure Pay tokenization surface has unique authentication semantics — three endpoints don't require an APIKey but require the registration option enabled, and (3) AR ledger surfacing cross-cuts R — Customer_OpenItems is technically a Customer endpoint but its use is finance-shaped (aging buckets, B2B credit posture, collection workflows).

Executive summary

Posture: archetype-shaped against Counterpoint specifically. The PayCode taxonomy flexibility is treated as a feature — F surfaces whatever the customer has defined without normalization. Alternative-payment-rail integration (Zelle / Venmo / Lightning) is flagged as a Canary-native option, not bundled into the substrate path.

L1 → L2 → L3 framework

L1 (Solution Map cell)         F = ● Full direct (Counterpoint tender / tax / gift card / Secure Pay surface — ~12 endpoints)
                                 │
L2 (Process areas)               ├── F.1  Tender taxonomy (PayCode)
                                 ├── F.2  Tax code surfacing
                                 ├── F.3  Gift card surface
                                 ├── F.4  Per-Document payment + tax flattening   (cross-cut with T)
                                 ├── F.5  Tokenization + Secure Pay (NSPTransaction)
                                 ├── F.6  AR ledger surfacing                     (cross-cut with R, J)
                                 └── F.7  Cross-module substrate contracts
                                 │
L3 (Functional processes)       (31 — enumerated per L2 below)
                                 │
L4 (Implementation detail)      Lives in SDDs + module specs
                                  (Canary-Retail-Brain/modules/F-finance.md,
                                   docs/sdds/canary/ncr-counterpoint-retail-spine-integration.md §6.3)

L4 implementation stubs

All L3 processes below are stub-pending at L4. Until an SDD section or module spec covers a process explicitly, treat the following as open:

F.1 — Tender taxonomy (PayCode)

Purpose. Counterpoint's PayCode is the customer-defined tender taxonomy. Every distinct tender (CASH, VISA, MC, AMEX, CHECK, AR, GIFTCARD, custom alternative-payment-rail entries) is a row. F surfaces the taxonomy at tenant bootstrap and re-syncs on cache invalidation.

Companion cards. ncr-counterpoint-api-reference § "Pay codes / tax", ncr-counterpoint-endpoint-spine-map § "Pay codes / tax — module F".

L3 processes

User stories

• As F, I want the PayCode taxonomy ingested at tenant bootstrap and refreshed daily, so Q's tender-mix rules always see the current set of defined tenders.
• As an Operator onboarding a new garden-center tenant in Owl, I want to map each PayCode to a classification (cash / card / AR / gift / alt-wallet / other) interactively, with auto-suggestion based on PayCode descriptors.
• As a Garden-Center Buyer who pays specialty growers via Zelle, I want to add a "ZELLE-VENDOR" PayCode in Counterpoint and have Canary recognize it as an alt-wallet vendor-payment tender, routing the resulting receivers correctly.
• As Q (Q-TM-01), I want the per-tenant cash-PayCode set available so cash-only register patterns are computed against the right tender denominator.

F.2 — Tax code surfacing

Purpose. Counterpoint's TaxCodes list defines the available tax-code rows. The actual tax application per transaction lives in the Document — PS_DOC_TAX[] carries multi-authority preservation per line (city + county + state stacked). F surfaces both the TaxCode list (config) and the per-Document tax detail (activity, via T cross-cut in F.4).

Companion cards. ncr-counterpoint-api-reference § "Pay codes / tax", ncr-counterpoint-document-model § "Taxes (PS_DOC_TAX[])".

L3 processes

User stories

• As F, I want the TaxCode list refreshed daily and per-store default tax codes joined inline, so Q-TC-01 mismatch detection has both the expected and actual tax stacks available without round-trips.
• As an Operator, I want per-store expected-jurisdiction-stacks captured at onboarding (e.g., "Glendora store: LA + LA-COUNTY + CA"), so Q can flag tax-stack mismatches deterministically.
• As Q (Q-TC-02), I want tax-exempt customer status accessible per transaction so retail-pattern usage of exemption can pattern-detect.

F.3 — Gift card surface

Purpose. Counterpoint's GiftCard family covers issued gift cards (GiftCard / GiftCards) plus the gift-card code template (GiftCardCode / GiftCardCodes — the SKU-like entity for new gift-card issuance). F surfaces both. Per-Document gift-card activity (sale of new card, redemption of existing card) flows through T's Document polling (PS_DOC_GFC[]).

Companion cards. ncr-counterpoint-api-reference § "Gift card", ncr-counterpoint-document-model § "PS_DOC_GFC".

L3 processes

User stories

• As F, I want every issued gift card's balance available without per-query Counterpoint round-trips, so Owl analytics on gift-card outstanding-liability are fast.
• As Q, I want gift-card redemption activity correlated to the original card's issuance and prior activity, so over-redemption or balance-mismatch patterns are detectable.
• As a Garden-Center GM in Owl, I want to ask "what's our outstanding gift-card liability" and get a real-time number drillable to per-card detail.

F.4 — Per-Document payment + tax flattening (cross-cut with T)

Purpose. The actual payment and tax activity lives in PS_DOC_PMT[] and PS_DOC_TAX[] per Document. T's parser flattens both. F's role is to define the canonical shape these flatten into and the contracts that downstream consumers (Q, R, C) read against. This L2 explicitly cross-cuts with T.3.4 (payment flattening) and T.3.5 (tax flattening) — the work happens in T's parser; F owns the contract.

Companion cards. ncr-counterpoint-document-model § "Payments" + § "Taxes", canary-module-t-functional-decomposition.md T.3.4 + T.3.5.

L3 processes

User stories

• As F, I want every PII-sensitive payment field (SIG_IMG, raw PAN, raw CVV) confirmed redacted at the T-parser layer before it reaches CRDM, so F never has to filter in downstream queries.
• As Q (Q-TC-01), I want every Document's full multi-authority tax stack available in Events.transaction_taxes so jurisdiction-mismatch detection has the true breakdown, not a summed total.
• As Q (Q-TM-02), I want payment apply-to instructions available so a "card paid, then changed to cash" tender-swap pattern is detectable from PS_DOC_PMT_APPLY audit-log delta.
• As Owl, I want to answer "what's my tender mix this week by store" and get card / cash / AR / gift / alt-wallet split with per-store drilldown.

F.5 — Tokenization + Secure Pay (NSPTransaction)

Purpose. Counterpoint's Secure Pay tokenization surface is unique within the API — three of its endpoints (POST /NSPTransaction, POST /Store/{StoreId}/Tokenize, GET /Store/{StoreId}/TokenizeInfo) don't require an APIKey but require the registration option enabled. The card-on-file tokenization replaces raw PAN with a token; F surfaces the token + tokenization status, never the PAN.

Companion cards. ncr-counterpoint-api-reference § "Tokenization", ncr-counterpoint-phase-0-context-brief § "Three company-scoped endpoints don't require an APIKey".

L3 processes

User stories

• As F, I want per-tenant tokenization status visible at a glance so customers operating Secure Pay see "all cards tokenized" or "N cards still pending tokenization" — the latter is a PCI-relevant gap.
• As Canary's Compliance Story, I want the tokenization-only contract enforced — F never persists PAN, F never even sees PAN past the parser layer.
• As an Operator triaging a card-related issue, I want to look up a card-on-file by token and see its tokenization status + last-charged-date + customer reference, without ever exposing the PAN.

F.6 — AR ledger surfacing (cross-cut with R, J)

Purpose. Counterpoint's AR ledger (Customer_OpenItems + customer-record AR fields) is technically a Customer endpoint but its semantics are finance-shaped — aging buckets, credit posture, collection workflows. F surfaces the AR ledger and provides the contracts that R (per-customer AR exposure), J (PO cost flow into AR), and C (B2B credit posture) read against.

Companion cards. canary-module-c-functional-decomposition.md § C.3.5 (R-side surface), ncr-counterpoint-api-reference § "Customer — Module C" § Customer_OpenItems.

L3 processes

User stories

• As F, I want every B2B customer's open AR aging available without per-query Counterpoint round-trips, so collection workflows in Fox can prioritize without latency.
• As J, I want PO cost flow (committed receipts, realized receipts) reconciled against F's AR aging so the buying triangle (J + F + C) closes the loop.
• As Owl, I want to answer "which landscaper accounts are 60+ days overdue" and get a sorted list with per-customer drill-down to the open invoices.
• As an LP Analyst (Q.6 vertical pack), I want AR-customer status available so Q-TM-01 (cash-only register pattern) doesn't fire on stations that disproportionately serve AR-paying landscapers (where lower cash share is expected).

F.7 — Cross-module substrate contracts

Purpose. F supplies tender + tax + AR substrate to T (parse), Q (rules), R (AR view), J (cost flow), and C (B2B credit). This L2 is the contract registry. Symmetric to T.7 / C.6 / S.7 / J.8b.

L3 contracts (registry)

User stories

• As F, I want every contract in F.7 enforced via the contract test suite, so a silent break (e.g., tax authorities accidentally summed) shows up at conformance test, not at first Q-TC-01 false-negative.
• As Q, I want to assert at boot that F surfaces all contracted fields including the per-store expected jurisdiction stack and the multi-authority preservation, so a contract break shows up at startup.
• As Canary's Compliance Story, I want the PII-redaction guarantee (F.7.4) audit-testable — periodic checks confirm SIG_IMG and raw PAN are not present anywhere in CRDM.

Counterpoint Endpoint Substrate

The following Counterpoint endpoints are the direct API surface for Module F's L3 processes. Each row maps to the CRDM entity F materializes and the L2 process area that owns it.

Assumptions requiring real-customer validation

Highest-leverage gaps: F-01 (PayCode classification mapping) and F-03 (per-store expected jurisdiction stacks). Both are engagement-knowable only — every customer has unique conventions. Capture both at onboarding as part of the CATz Phase II To-Be Workshop output.

Customer-specific overrides

Empty until a real customer engagement starts. Format reserved:

Customer: <name>
PayCode classification mapping:
  <PayCode value> | <CASH | CARD | AR | GIFT | ALT-WALLET | OTHER>
  ...
Alt-payment-rail PayCodes (if any):
  <PayCode> → <wallet name>
Per-store expected tax jurisdiction stacks:
  <STR_ID> | [<authority1>, <authority2>, <authority3>, ...]
Tax-exempt customer convention: <field name + value pattern>
Secure Pay deployed: <yes — N stores | no>
Tokenization status target: <100% / partial / N/A>
AR ledger active: <yes — typical aging buckets | no>
Disabled F.x processes (with reason):
  F.x.x: <reason>
ASSUMPTION resolutions:
  ASSUMPTION-F-NN: resolved as <answer>; source: <evidence>
  ...

Additional user stories

The following user stories expand F's coverage across onboarding, override workflows, split-tender redemption, AR currency, and gift-card recovery scenarios. They supplement the per-L2 stories above.

• As a store admin, I need to add a new PayCode during onboarding (after initial bootstrap) so that a non-standard tender type accepted at this location is properly classified from day one.
• As a cashier supervisor, I need to override the system-defaulted tax code on a specific line item so that a tax-exempt product sold with a regular receipt is correctly classified.
• As a customer, I need to apply a gift card to a purchase where the card balance is less than the purchase total so that the partial balance is applied and the remainder charged to another tender.
• As an accounts receivable manager, I need to view AR aging in local currency for a Canadian B2B customer so that I can assess credit posture without manual currency conversion.
• As a store manager, I need to reassign the balance from a lost or damaged gift card to a replacement card so that the customer's stored value is preserved.

Operating notes

Cast of actors:

F is an unusually cross-cut module. F.4 explicitly cross-cuts with T (where the parsing actually happens — F owns the contract, not the parser). F.6 cross-cuts with R (Customer_OpenItems is a Customer endpoint by URL but a Finance concern by semantics). Both cross-cuts are intentional — modules-by-semantics, not modules-by-endpoint-URL.

The PayCode taxonomy flexibility is a feature. Counterpoint customers can define any tender they want. F preserves the customer's taxonomy verbatim and lets per-tenant classification mapping (F.1.4) layer the meaning on top. This is what enables the alternative-payment-rail wedge (F.1.5 / F.7.9) — Zelle / Venmo / Lightning fit naturally as customer-defined PayCodes.

Three Secure Pay endpoints have unique auth. POST /NSPTransaction, POST /Store/{StoreId}/Tokenize, GET /Store/{StoreId}/TokenizeInfo don't require an APIKey but do require the registration option. T.1.5 auth injection has to know about this exception per endpoint family.

Related

• Canary-Retail-Brain/modules/F-finance.md — L1 canonical spec
• canary-module-f-finance.md — L2 Canary code/schema crosswalk
• canary-module-q-functional-decomposition.md — sister card; F.2.4 + F.4 + F.7.x drive Q-TM and Q-TC rule families
• canary-module-t-functional-decomposition.md — sister card; T.3.4 + T.3.5 (parsing) implements F.4 contracts
• canary-module-c-functional-decomposition.md — sister card; C.3.4 + C.3.5 (AR-customer + AR aging surface) reads from F.6
• canary-module-o-functional-decomposition.md — sister card; O.6.4 (cost reconciliation) and O.8.5 (PO recommendation as substrate) bridge with F's AR posture
• ncr-counterpoint-api-reference.md — full PayCode / TaxCode / GiftCard / Tokenization detail
• ncr-counterpoint-document-model.md — PS_DOC_PMT[] + PS_DOC_TAX[] + PS_DOC_GFC[] substrate
• ncr-counterpoint-endpoint-spine-map.md — per-endpoint × CRDM × spine map for F family
• ncr-counterpoint-rapid-pos-relationship.md — multi-tier tender + multi-authority tax mapping
• garden-center-operating-reality.md — alt-payment-rail wedge context, multi-tier tender mix
• rapid-pos-counterpoint-user-pain-points.md — eCommerce sync + payment-terminal pain themes
• (CATz) proof-cases/specialty-smb-counterpoint-solution-map.md — F row = ● Full direct
• (CATz) method/artifacts/module-functional-decomposition.md — the artifact template this card follows