Go: Fintech

View saved version →

---
name: go-clearing-settlement-reconciliation
description: "Use after capture for Go settlement, reconciliation, exceptions, and repair. Do not use for initial authorization."
license: Apache-2.0
compatibility: "Go 1.24 or newer; rail cutoffs, calendars, reports, and finality come from current provider and scheme contracts."
---

# Go clearing, settlement, and reconciliation

Do not collapse payment acceptance, clearing, settlement, payout, and bank movement into one success flag. They are separate evidence domains with different timing and finality.

## Preserve evidence

Ingest external reports and statements immutably with artifact identity, source version, checksum, retrieval time, business date, completeness/sequence evidence, and parser version. A corrected artifact does not overwrite its predecessor: record `supersedes` lineage and create explicit rematching or reversal work. Make re-ingestion idempotent. Preserve raw evidence under access and retention policy; derive versioned normalized items separately.

## Match at item level

Match stable external/internal identity first, then amount, currency, lifecycle, account, and time window. Support 1:1, 1:N, and N:1 match groups when the source economics require them. Every normalized economic component belongs to exactly one explained match group or one explicit exception; never reuse an item across groups. Each group must satisfy a currency-preserving equation over captures, refunds, fees, reserves, adjustments, and bank movement.

Exceptions include missing internal, missing external, duplicate, amount/currency mismatch, status mismatch, timing break, and incomplete or superseded evidence. Persist the rule and source versions behind every match decision.

Aggregate totals are controls, not sufficient reconciliation. Equal and opposite item errors can net to zero.

## Adjust deliberately

Age timing breaks by rail calendars and cutoffs. Separate automated detection from authorized remediation. Adjust with linked immutable ledger entries; never rewrite the original payment or report. Reruns must not duplicate adjustments or erase prior decisions.

## Recovery and operations

Use restartable batches, checkpoints, deterministic matching, bounded concurrency, and work queues with ownership. Publish completeness, unmatched amount/count, age, duplicate count, and source freshness without leaking sensitive data.

Read [references/reconciliation-model.md](references/reconciliation-model.md) for stages and controls. For Fedwire acceptance, cancellation, outage, and resend semantics, read [references/fedwire-finality-and-contingency.md](references/fedwire-finality-and-contingency.md) and verify the deployed circular version.

For FedACH post-origination processing, read [references/ach-returns-and-corrections.md](references/ach-returns-and-corrections.md). Keep returns, Notifications of Change, reversals, and disputed returns distinct; their value effects, roles, and permitted timing are not interchangeable.

For rail business days, holidays, processing windows, cutoff extensions, and schedule changes, read [references/business-time-and-cutoffs.md](references/business-time-and-cutoffs.md). Persist the governing schedule and timezone version with each decision; a UTC calendar date, fixed offset, or `Add(24*time.Hour)` is not a rail calendar.

## Output contract

State source evidence, matching key, timing policy, exception taxonomy, adjustment authorization, and replay behavior. Missing or silently auto-matched money is a critical defect.

Referenced files: 7

View saved version →

---
name: go-financial-idempotency
description: "Use only for financial request identity, replay, retention, and ambiguity. Do not use for non-financial effects."
license: Apache-2.0
compatibility: "Go 1.24 or newer; external idempotency guarantees must match the active provider contract."
---

# Go financial idempotency

Idempotency means equivalent retries under one authenticated operation identity produce at most one committed financial effect and a consistent outcome.

## Define identity and scope

Scope the key by tenant/principal, operation type, and target resource. Bind it to a canonical fingerprint of semantic input. Reject same-key different-input reuse. Never put PII or secrets in the key.

## Serialize first use

Use a durable unique constraint or equivalent atomic claim. Store state such as processing, succeeded, failed-final, and ambiguous; include response/result evidence, canonical fingerprint, attempt owner, lease/version, and provider operation identity. Check-then-insert without a constraint races. A process-local mutex or cache cannot survive replicas and crashes.

## Couple effect and record

When local state is the effect, write idempotency record, domain transition, ledger journal, and stored result in one transaction. For an external provider, persist the attempt before calling, reuse the same provider identity, and reconcile ambiguity before issuing a new operation.

Recover abandoned `processing` ownership with a bounded lease and compare-and-swap or fencing transition. Lease expiry proves only that the prior worker lost local ownership; it never proves an external effect failed. A taker-over must first query or reconcile using the stable provider identity, then either record the discovered result or repeat only under the provider's same-identity guarantee.

## Retention and replay

Retain records for the maximum credible client, webhook, and operational replay window. Define behavior after expiry explicitly. Do not prune while in-flight or ambiguous operations can still resolve. Return the stored outcome only if authorization and current disclosure policy allow it.

Read [references/idempotency-record.md](references/idempotency-record.md) for a state model.

When the effect crosses a payment-provider API, read [references/provider-idempotency-contract.md](references/provider-idempotency-contract.md). Provider keys differ in supported operations, scope, retention, concurrency, response replay, and regional behavior; encode the deployed endpoint contract instead of assuming a generic header supplies permanent deduplication.

## Output contract

State key scope, fingerprint, concurrency control, atomic boundary, result replay, ambiguity, and retention. Treat mismatched reuse and duplicate financial effects as critical failures.

Referenced files: 5

View saved version →

---
name: go-fintech-security-compliance
description: "Use for Go payment compliance, sanctions, tokenization, audit, and PCI. Do not use for generic exploits or legal advice."
license: Apache-2.0
compatibility: "Go 1.24 or newer; standards and regulatory obligations require current qualified interpretation for the actual system."
---

# Go fintech security and compliance

Minimize the systems and people that can store, process, transmit, or affect sensitive payment data. Compliance evidence must follow actual controls, not documentation theater.

## Scope the data

Classify account data, sensitive authentication data, PII, secrets, reusable payment/network tokens, detokenization handles, low-value opaque correlation IDs, derived identifiers, and audit records. Prefer hosted collection or tokenization that prevents raw data from entering the service. Map every store, log, queue, trace, backup, analytics stream, and support tool the data can reach.

Do not retain applicable sensitive authentication data after authorization, even when encrypted. This includes card verification codes, PIN/PIN blocks, and full track data. Confirm the exact classification and disposition against the current PCI DSS and qualified assessor guidance for the deployed flow; code inspection cannot establish compliance.

Tokenization narrows scope only when raw collection, detokenization authority, routing, failure queues, telemetry, support access, analytics, backups, and model/tool inputs remain separated in the real data flow. Classify reusable tokens and detokenization handles as authority-bearing values. Prove deletion and retention outcomes across derived stores rather than deleting only the primary row.

## Enforce authority

Authenticate users and services at an assurance level matching risk. Authorize by subject, tenant, action, resource, amount, and workflow state. Separate maker/checker or privileged approval where required. Rotate and revoke credentials; isolate cryptographic keys and record key version without logging secret material.

## Preserve auditability

Record actor, authority, operation, target, before/after state reference, reason, time, correlation, and approval in tamper-evident durable storage. Keep logs and traces free of PAN, authentication data, reusable credentials or payment tokens, detokenization handles, secrets, and unnecessary PII. Classify token-like values before logging; an approved low-value correlation ID is not interchangeable with a reusable credential. Restrict access and test evidence retrieval.

## Engineer change controls

Threat-model sensitive changes, review generated artifacts and dependencies, pin CI inputs, separate duties for releases, prove rollback/migration behavior, and keep retention/deletion schedules enforceable. A checklist does not certify PCI DSS or any regulation; involve qualified security, compliance, and legal owners.

Read [references/control-boundaries.md](references/control-boundaries.md) for tokenization, scope, retention, and audit failure cases.

For sanctions screening, holds, adjudication, list changes, and provider failure, read [references/sanctions-screening-controls.md](references/sanctions-screening-controls.md). Exact duties and dispositions come from the current risk-based compliance program and qualified legal/compliance owners, not from a match score or this skill.

For payment-provider callbacks, read [references/webhook-authenticity.md](references/webhook-authenticity.md). Verify the provider's exact signed representation and endpoint/account/environment key before trusting the payload, then separately enforce durable deduplication, ordering, authorization, and financial state invariants.

## Output contract

State data classification, trust boundary, authority decision, control owner, evidence, and residual compliance uncertainty. Never claim certification from code review.

Referenced files: 6

View saved version →

---
name: go-money-and-ledgers
description: "Use for Go money, rounding, allocation, journal, balance, and reversal invariants. Do not use for provider state."
license: Apache-2.0
compatibility: "Go 1.24 or newer; currency and accounting rules require current product and jurisdiction evidence."
---

# Go money and ledgers

Money is a typed exact value. A ledger is immutable evidence, not a mutable balance table with an audit log added later.

## Represent money

Carry amount and currency together. Use integer minor units when the product contract fits one exponent; use exact decimal with explicit scale when it does not. Never use binary floating point for postings or settlement amounts. Validate currency, scale, range, and sign at the boundary.

Rounding is a named business operation: specify mode, scale, stage, and residual allocation. ISO/CLDR metadata alone cannot choose half-even versus half-up, cash rounding, or the legally correct tax stage; obtain product, contract, and jurisdiction evidence. Do not round intermediate values merely for display. Allocate remainders with a stable tie-break independent of map iteration so parts sum exactly to the source amount. Persist the per-part allocation and policy version; refunds and reversals use the original allocation rather than recomputing it under a new order or policy.

For FX, persist the booked quote identity, source and time, base/quote direction, exact rate and scale, rounding stage, resulting amounts, residual disposition, and policy version. Balance journals per currency; connect the two currency legs through explicit FX position or clearing accounts rather than netting unlike units. A reversal uses the original booking evidence unless the product contract creates a new conversion.

## Post a journal

Persist immutable entries with journal ID, account, currency, signed side/amount, effective and recorded time, operation identity, and source evidence. Enforce per-journal, per-currency balance in the same transaction. Use reversal or adjustment journals rather than editing history.

Distinguish pending, posted, and available balances if the product needs them. Derive balances from entries or maintain a projection transactionally coupled to entries and rebuildable from them.

## Concurrency and audit

Where overdraft, limits, reservations, or sequence matter, the decision read, authoritative balance/reservation mutation, journal posting, and operation claim share one atomic boundary. Name the anomaly and use a locked authoritative row, conditional balance/version update, or serializable transaction with whole-transaction retry. Enforce logical posting identity with a database uniqueness constraint. A balanced journal can still be unauthorized or economically wrong; preserve the business command and approval evidence. Avoid sensitive payloads while keeping immutable actor, time, reason, and correlation.

When the product exposes available balance, authorizations, or internal holds, read [references/reservations-and-balances.md](references/reservations-and-balances.md). Define which pending and posted entries affect availability, then make the decision and reservation one conditional durable transition.

Use `go-data-consistency` for the database anomaly and `go-financial-idempotency` for operation identity and replay.

Read [references/money-ledger-invariants.md](references/money-ledger-invariants.md) for arithmetic and schema checks, [references/fx-booking.md](references/fx-booking.md) for conversion evidence, and [references/corrections-and-effective-time.md](references/corrections-and-effective-time.md) for reversals, backdating, closed periods, and as-of replay.

## Output contract

State exact representation, rounding, journal balance, mutation policy, and concurrency invariant. Zero tolerance for silent precision loss or unbalanced committed entries.

Referenced files: 7

View saved version →

---
name: go-payment-lifecycles
description: "Use only for payment/rail authorization, capture, refund, webhook, and ambiguity. Do not use for non-financial effects."
license: Apache-2.0
compatibility: "Go 1.24 or newer; provider, rail, and scheme state semantics are version- and region-specific."
---

# Go payment lifecycles

Model provider evidence as events and local payment state as a constrained projection. A network result is not automatically a financial result.

## Define the machine

List states, legal commands, provider requests, provider evidence, terminality, amount constraints, expiry, and late-event behavior. Keep authorization, capture, refund, reversal, dispute, and settlement distinct even if the UI says “paid.”

## Handle ambiguous outcomes

A timeout or lost response after request transmission can mean success, failure, or still processing. Persist the attempt and stable provider identity, replay only under the provider's idempotency contract, identify what evidence is authoritative for this provider or rail and whether its query can lag, and reconcile asynchronous evidence. Never create a new payment identity merely because the response was missing. If the deployed provider or rail contract is unavailable, stop at a conditional state machine; do not transfer Stripe-specific idempotency, expiry, or finality semantics to ACH or another rail.

## Apply events safely

Verify authenticity before parsing into trusted events. Deduplicate by provider event or operation identity, but make handlers tolerant of out-of-order evidence. Distinguish duplicate, stale, future/missing-predecessor, conflicting, and contract-invalid evidence. Persist future evidence such as refund success arriving before capture success and reevaluate it when prerequisites arrive; quarantine only contract-invalid or irreconcilably conflicting evidence. Apply transitions conditionally against current version/state.

## Amount and terminality

Enforce cumulative capture and refund limits with exact money. Partial capture/refund and multiple disputes can coexist. “Succeeded” may be locally terminal for fulfillment while chargebacks and settlement adjustments remain possible.

For multi-capture or partial-refund flows, allocate each amount-bearing operation to stable payment, capture, shipment or item, and provider identities. Fulfill only the durably captured allocation, never a payment-wide Boolean. Persist provider capability and final-capture semantics, serialize concurrent amount decisions, and reconcile aggregate fields to item-level evidence. Read [references/partial-capture-and-refund-accounting.md](references/partial-capture-and-refund-accounting.md); its Stripe rules remain Stripe-specific.

Read [references/payment-machine.md](references/payment-machine.md) for transition and ambiguity rules.

For partial authorization, incremental authorization, capture, void, or authorization-reversal changes, read [references/authorization-adjustments.md](references/authorization-adjustments.md). Preserve requested, approved, capturable, captured, and released amounts separately; provider-specific remainder-release behavior is not a portable payment rule.

For card disputes, chargebacks, evidence, or representment, read [references/disputes-and-evidence.md](references/disputes-and-evidence.md). A dispute is its own amount-bearing case and deadline lifecycle; it is not a Boolean on the original payment or proof that a refund resolved the issuer process.

Use `go-financial-idempotency` for repeated-request identity, and `go-clearing-settlement-reconciliation` for post-capture external reports and settlement breaks.

## Output contract

Provide the state/event table, authoritative evidence, ambiguity policy, and illegal-transition handling. Do not compress the design into booleans or infer provider success from HTTP status alone.

Referenced files: 7

View saved version →

---
name: review-go-fintech-change
description: "Use as lead for fintech Go diff/PR review: money, payments, settlement, payment data, and audit. Do not use for general work."
license: Apache-2.0
compatibility: "Go 1.24 or newer; product, provider, rail, and compliance contracts control the review."
---

# Review a Go fintech change

Treat any path that can invent, duplicate, lose, misstate, or conceal money as financial-integrity sensitive.

## Trace the financial effect

Follow authenticated command, money representation, idempotency identity, state transition, provider attempt, ledger posting, event, settlement evidence, reconciliation, response, and audit record. Identify exact transaction boundaries and unknown-outcome windows.

For every caller, payment, provider, or replay identity, verify its authority scope and canonical payload binding. State all three behaviors explicitly: equivalent input replays the same outcome; different input is rejected before a new effect or prior-result disclosure; wrong authority learns nothing. Saying an identity is “bound to a fingerprint” is not an enforceable finding unless the mismatch path is defined.

Treat product, provider, rail, report, and repository semantics already supplied by the task as the review contract. Choose the narrowest focused skill that owns the dominant financial effect: `go-money-and-ledgers` for arithmetic or journal invariants, `go-payment-lifecycles` for provider states, `go-financial-idempotency` for financial replay identity, `go-clearing-settlement-reconciliation` for post-capture evidence, or `go-fintech-security-compliance` for regulated data and audit controls. Do not load adjacent skills merely because the diff mentions their topic.

For report ingestion, payout, settlement, or reconciliation code, read `go-clearing-settlement-reconciliation` before findings even when business contracts are supplied. Source completeness, source and parser provenance, exclusive match-group membership, currency-preserving equations, and completion evidence are correctness invariants rather than optional background. Load another focused or cross-collection skill only when an unresolved invariant directly changes the financial finding; stop once it is resolved.

## Critical schedules

- concurrent same-key and different-payload requests;
- timeout after provider or database may have committed;
- duplicate, delayed, and out-of-order webhooks;
- partial capture/refund and cumulative amount races;
- rounding residual across allocations and currencies;
- unbalanced or mutable journal history;
- report re-ingestion and duplicate adjustment;
- late chargeback or settlement event after local terminal state;
- cross-tenant replay, excessive privilege, or sensitive data in telemetry;
- mixed versions during schema and state-machine rollout.

## Findings

Zero tolerance: silent precision loss, unbalanced committed entries, duplicate financial effects, illegal state transitions presented as success, missing reconciliation evidence, or sensitive authentication data leakage. Tie every finding to a reachable schedule and authoritative invariant. State the exact identity, amount, currency, evidence state, authority, known/failed/ambiguous outcome, durable consequence, smallest repair, and required backfill or reconciliation. Do not treat provider documentation as universal across rails.

Read [references/financial-finding-standard.md](references/financial-finding-standard.md) only when the task requires a formal audit format or a finding still lacks one of those dispositions.

## Output contract

Lead with critical financial-integrity findings, then security/compliance and operational risks. State when scheme, legal, or compliance interpretation requires a qualified owner; never infer certification.

Audit the final prose against every applicable financial-effect boundary. Do not rely on naming idempotency, reconciliation, or an adjustment to imply payload mismatch handling, evidence lineage, replay safety, exact arithmetic, or immutable correction.

Referenced files: 4