Payment records
Keeps requests, outcomes and evidence identities
Subject type: element
Subject ID: part-payment-store
Project ID: showroom-payments
Revision: 1
Project settings version: 1
Project settings hash: sha256:11eb9324f48ccccdfbf345321fa5ffff2df6e34be7357a383b848db997e22834
# Copper Lane Payments — Current design · illustrative baseline
_Revision 1 · content sha256:7d9b11dda8ea28f26ac0388f730e683ac048439e58ee8d63c71d9d5ebd6f528e_
_Context for Payment records (element part-payment-store)_
Illustrative payment system · authored sample knowledge
_Readiness 0% · 1 open decisions · 1 decided_
## Use cases that pass through it
- Pay for the €100 lamp
- Refund the unavailable lamp
## Outline
- **Copper Lane Payments** (`system-payments`, Boundary, system in scope) — One shared picture of a fictional payment
Illustrative system · authored sample records. A merchant payment service connected to a fictional processor. No bank, wallet, settlement product or real processor integration is represented.
- **Payment records** (`part-payment-store`, Data store) — Keeps requests, outcomes and evidence identities
The fictional payment service owns this authoritative store. Tables describe a proposed design. Example values are authored notes, not live transaction rows or bank observations.
- **Payment service** (`part-payments`, Process) — Owns logical operations and recorded state
Owns payment and refund operations, their stable keys and state transitions. Processor calls cross the network. Its confirmation component calls payment operations in-process.
## Interactions
- **Read and record payment state** (`int-record-state`): Payment service → Payment records · Data · Network · Contract Payment state storage
Persist the logical payment, operation key, accepted outcome and processed confirmation identity. Repeating a delivery must not create another payment.
## Contracts
### Payment state storage (`contract-payment-store`) · SQL
The payment service owns reads and writes of order references, logical payments, confirmations and refunds in the modeled PostgreSQL design.
- Event identity is recorded with the accepted state transition. The schema is illustrative, not a deployed payment backend.
## Data model
### Processor confirmation (`data-confirmation`) · Owner Payment service
Authored event evt-9001 confirms pay-1001; evt-9002 confirms refund-1001. Event identity supports deduplication, but arrival order alone never establishes truth. Sources: src-processor-confirmation and src-refund-confirmation.
- event\_id: string, identifier, required — A stable identifier in this authored sample, independent of network delivery attempts.
- payment\_id: reference → Payment, required — An explicit relation to the original authored operation or order reference.
- refund\_id: reference → Refund — An explicit relation to the original authored operation or order reference.
- outcome: string, required — The outcome reported by an authored processor record, checked against the logical operation and compatible state.
- → Payment (N:1)
- → Refund (N:1)
### Order reference (`data-order`) · Owner Payment service
Authored order ord-1042 requests EUR 10000 for Mira’s lamp. This is the minimal payment-facing reference, not a complete merchant order system. Source: src-purchase-requirement.
- id: string, identifier, required — A stable identifier in this authored sample, independent of network delivery attempts.
- amount\_minor: integer, required — Integer minor units. EUR 10000 represents the fictional €100.00 purchase or full refund.
- currency: string, required — The authored example uses EUR; it is not a live exchange rate or price feed.
### Payment (`data-payment`) · Owner Payment service
Authored logical payment pay-1001 references ord-1042 for EUR 10000, using pay-op-1001. Its initial timeout leaves the outcome unknown. src-processor-confirmation later records evt-9001 and processor-pay-7001.
- id: string, identifier, required — A stable identifier in this authored sample, independent of network delivery attempts.
- order\_id: reference → Order reference, required — An explicit relation to the original authored operation or order reference.
- amount\_minor: integer, required — Integer minor units. EUR 10000 represents the fictional €100.00 purchase or full refund.
- currency: string, required — The authored example uses EUR; it is not a live exchange rate or price feed.
- operation\_key: string, required — pay-op-1001 identifies the same logical operation for identical requests inside the fictional 24-hour contract window.
- state: enum, confirming | paid | declined, required — Confirming means unknown. Paid requires compatible processor evidence. Declined requires an explicit decline, not a timeout.
- processor\_reference: string — Optional until the processor outcome is known. The authored confirmation supplies processor-pay-7001.
- → Order reference (N:1)
### Refund (`data-refund`) · Owner Payment service
Authored refund-1001 references pay-1001 for EUR 10000 with separate key refund-op-1001. The requested state precedes prepared confirmation evt-9002; bank posting remains unknown to this sample.
- id: string, identifier, required — A stable identifier in this authored sample, independent of network delivery attempts.
- payment\_id: reference → Payment, required — An explicit relation to the original authored operation or order reference.
- amount\_minor: integer, required — Integer minor units. EUR 10000 represents the fictional €100.00 purchase or full refund.
- currency: string, required — The authored example uses EUR; it is not a live exchange rate or price feed.
- operation\_key: string, required — refund-op-1001 is separate from the payment key and retained when retrying the same authored refund.
- state: enum, requested | confirmed, required — Requested records intent. Confirmed requires compatible fictional processor evidence; neither state reports bank posting.
- → Payment (N:1)
## Database designs
### Payment state · illustrative PostgreSQL design (`database-payments`) · PostgreSQL · Payment records
Proposed physical design for the authored logical entities. Payment and refund records link to their order and original operation; processed confirmation identity is explicit. No database or payment backend is provisioned.
#### `public.orders` · Entity Order reference
- id text NOT NULL
- amount\_minor bigint NOT NULL
- currency text NOT NULL
- _PRIMARY KEY (id)_
#### `public.payments` · Entity Payment
- id text NOT NULL
- order\_id text NOT NULL
- amount\_minor bigint NOT NULL
- currency text NOT NULL
- operation\_key text NOT NULL
- state text NOT NULL
- processor\_reference text
- _PRIMARY KEY (id)_
- _FOREIGN KEY (order\_id) → orders (id)_
#### `public.confirmations` · Entity Processor confirmation
- event\_id text NOT NULL
- payment\_id text NOT NULL
- refund\_id text
- outcome text NOT NULL
- _PRIMARY KEY (event\_id)_
- _FOREIGN KEY (payment\_id) → payments (id)_
- _FOREIGN KEY (refund\_id) → refunds (id)_
#### `public.refunds` · Entity Refund
- id text NOT NULL
- payment\_id text NOT NULL
- amount\_minor bigint NOT NULL
- currency text NOT NULL
- operation\_key text NOT NULL
- state text NOT NULL
- _PRIMARY KEY (id)_
- _FOREIGN KEY (payment\_id) → payments (id)_
## Domain
### Processor confirmation (`concept-confirmation`) · Merchant payments
Authored evidence about one payment or refund operation. Event identity and compatible state determine how it can affect recorded knowledge.
- Repeated or unordered delivery is possible; a missing answer is not proof of failure.
- Carried by: Payment service, Processor confirmation
### Order (`concept-order`) · Merchant payments
The merchant request to buy Mira’s €100 lamp, represented only by the payment-facing reference ord-1042.
- The merchant fulfils only after processor-confirmed payment.
- → Order requires a Logical payment
- Carried by: Payment service, Order reference
### Logical payment (`concept-payment`) · Merchant payments
One business payment operation, pay-1001. Retrying its network request does not inherently create a new payment.
- An unanswered request retains its logical identity; a new explicit attempt after a confirmed decline is a different operation.
- → Logical payment has evidence in Processor confirmation
- Carried by: Payment service, Payment
### Refund (`concept-refund`) · Merchant payments
A separate operation that references an existing payment. refund-1001 requests the full fictional EUR 10000.
- Requested and processor-confirmed outcomes are distinct. Confirmation does not establish bank posting.
- → Refund references a Logical payment
- Carried by: Payment service, Refund
## Decisions
### Who owns a payment that remains unresolved? (`dec-unresolved-payment-escalation`, open)
The fictional contract’s key window is bounded. If the existing outcome still cannot be established, keep the uncertainty open. An owner and escalation policy have not been decided.
- Affects: Payment service
### A timeout means unknown, not failed (`dec-timeout-is-unknown`, decided)
Checkout’s authored 10-second deadline can expire before the processor outcome is known. Starting another payment would risk charging twice if the unanswered operation succeeded.
- Keep confirming: Retain the same logical payment and key while seeking its existing outcome. Identical retries inside the fictional 24-hour window refer to that operation.
- Start another payment immediately: Treat a missing answer as failure and create another payment with a new operation key. — The first payment may already have succeeded. A new operation permits a possible duplicate charge.
- **Chosen:** Keep confirming
Keep Confirming payment visible until compatible evidence establishes the outcome. Beyond the 24-hour key window, inspect the existing operation first. Confirmed decline permits a separate explicit attempt.
- Evidence: note src-purchase-requirement: Authored src-purchase-requirement: Mira buys a EUR 100.00 lamp. The fictional shop fulfils only after processor-confirmed payment.
- Evidence: note src-payment-request: Authored src-payment-request: order ord-1042, logical payment pay-1001, EUR 10000 minor units and operation key pay-op-1001.
- Evidence: note src-checkout-timeout: Authored src-checkout-timeout: no reply reached checkout within 10 seconds. This proves the wait ended, not that the processor failed.
- Evidence: note src-processor-confirmation: Authored src-processor-confirmation: evt-9001 confirms EUR 10000 captured for pay-1001 with reference processor-pay-7001. Repeated delivery uses the same event identity.
- Evidence: note src-refund-confirmation: Authored src-refund-confirmation: evt-9002 confirms refund-1001 for EUR 10000 against pay-1001. Bank posting is outside this story.
- Evidence: note src-processor-contract: Authored src-processor-contract: identical same-key requests identify one operation for 24 hours. Confirmations may repeat or arrive out of order. Beyond that window, inspect the existing outcome before another attempt.
- Affects: Payment service
## Flows
### Resolve one payment without inventing its outcome (`flow-pay-order`) · uc-pay-order › pay-process
flow-pay-order details pay-process in uc-pay-order. Two start points distinguish the original request from a later processor event. Authored records reveal knowledge, not live telemetry.
1. \[start\] Payment request arrives — Payment service (→ 2)
2. \[process\] Record pay-1001 before calling the processor — Payment service (→ 3)
3. \[process\] Submit pay-op-1001 with the same parameters — Payment service (→ 4)
4. \[decision\] What does the available evidence establish? — Payment service (confirmed → 6, confirmed decline → 7, no answer before deadline → 8)
5. \[end\] Payment confirmed; the shop may fulfil — part-checkout
6. \[process\] Record the confirmed payment outcome — Payment service (→ 5)
7. \[error\] Confirmed decline; an explicit new attempt is possible — part-checkout
8. \[process\] Keep pay-1001 confirming; do not invent failure — Payment service (→ 9)
9. \[end\] Show Confirming payment; outcome remains unknown — part-checkout
10. \[start\] A processor confirmation arrives separately — part-confirmations (→ 11)
11. \[decision\] Was this confirmation identity already processed? — part-confirmations (already processed → 12, new, compatible evidence → 13)
12. \[end\] Duplicate evt-9001; recorded outcome unchanged — part-confirmations
13. \[process\] Record the compatible confirmation and payment outcome — Payment service (→ 5)
### Request and confirm the €100 refund (`flow-refund-payment`) · uc-refund-payment › refund-process
flow-refund-payment details refund-process in uc-refund-payment. A request and a later confirmation have separate entry points. There is no claim about bank posting.
1. \[start\] Support requests a refund for pay-1001 — Payment service (→ 2)
2. \[decision\] Is this confirmed payment eligible for this refund? — Payment service (not eligible → 3, eligible → 4)
3. \[error\] Reject an unsupported or already completed refund — Payment service
4. \[process\] Record refund-1001 and submit refund-op-1001 — Payment service (→ 5)
5. \[end\] Refund requested; its outcome is still unknown — actor-support
6. \[start\] A refund confirmation arrives separately — part-confirmations (→ 7)
7. \[decision\] Was this refund event already processed? — part-confirmations (already processed → 8, new, compatible evidence → 9)
8. \[end\] Duplicate refund event; recorded outcome unchanged — part-confirmations
9. \[process\] Record the compatible refund confirmation — Payment service (→ 10)
10. \[end\] Refund confirmed by the fictional processor — actor-support