Confirmation handler

Subject type: element
Subject ID: part-confirmations
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 Confirmation handler (element part-confirmations)_

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

## Inputs and outputs

**Inputs**

- **Receive payment confirmation** (`int-payment-confirmation`): Fictional processor → Confirmation handler
- **Receive refund confirmation** (`int-refund-confirmation`): Fictional processor → Confirmation handler

## Outline

- **Fictional processor** (`part-processor`, External system) — An external system with an authored contract

  Outside the merchant payment system. Its sample contract permits identical same-key requests for 24 hours and repeated, unordered confirmations. These assumptions are not guarantees about real providers.
- **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 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.
    - **Confirmation handler** (`part-confirmations`, Component) — Checks event identity and compatible outcomes

      A component inside the payment-service process. Receives fictional processor callbacks, recognizes repeated events and applies compatible state changes. Delivery order alone never establishes truth.

## Interactions

- **Apply a compatible outcome** (`int-apply-confirmation`): Confirmation handler → Payment service · Command · In-process · Contract Apply confirmed outcome

  The confirmation component invokes payment operations in-process. Check event identity and logical operation before recording an accepted transition.
- **Receive payment confirmation** (`int-payment-confirmation`): Fictional processor → Confirmation handler · Event · Network · Contract Processor confirmation endpoint

  The fictional processor sends authored event evt-9001 for pay-1001, processor reference processor-pay-7001, EUR 10000 captured. src-processor-confirmation records this prepared evidence.
- **Receive refund confirmation** (`int-refund-confirmation`): Fictional processor → Confirmation handler · Event · Network · Contract Processor confirmation endpoint

  Authored event evt-9002 confirms refund-1001 for EUR 10000 against pay-1001. src-refund-confirmation does not establish bank posting.

## Contracts

### Apply confirmed outcome (`contract-apply-confirmation`) · In-process

The confirmation component invokes payment operations inside the same payment-service process. No HTTP hop exists between these two parts.

- Record event identity and a compatible outcome together. A repeated event cannot create another logical payment or refund.

### Processor confirmation endpoint (`contract-confirmations`) · HTTP API

The payment service owns POST /processor-confirmations. Its confirmation component receives processor-originated payment and refund events.

- Confirmations can be duplicated or unordered. Event identity and compatible state transitions determine whether recorded state changes; exactly-once delivery is not assumed.

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

## 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, Confirmation handler

## 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 — Confirmation handler (→ 11)
11. \[decision\] Was this confirmation identity already processed? — Confirmation handler (already processed → 12, new, compatible evidence → 13)
12. \[end\] Duplicate evt-9001; recorded outcome unchanged — Confirmation handler
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 — Confirmation handler (→ 7)
7. \[decision\] Was this refund event already processed? — Confirmation handler (already processed → 8, new, compatible evidence → 9)
8. \[end\] Duplicate refund event; recorded outcome unchanged — Confirmation handler
9. \[process\] Record the compatible refund confirmation — Payment service (→ 10)
10. \[end\] Refund confirmed by the fictional processor — actor-support