Meridian Engineering / Lab 2
Meridian decisions
Consult the sources that support your understanding, decisions, and evidence throughout the work.
Your orientation Reference · supports every work phaseIntuition · Common language · Habit
Where you are in the work
- Define / Plan
- Execute
- Judge
- Learn
What you are developing
Intuition
Recognize when a proposed decision exceeds the evidence or scope.
Common language / Standardization
Make authority, exclusions, requirements, and readiness explicit.
Habit / Behavior
Trace decisions to sources; keep unknowns explicit instead of inventing defaults.
Use this material alongside the stage you are working on. Return to the complete journey.
PGS_DECISIONS.md — decision register
Every behaviour represented in this lab is recorded here with its source and its layer. This file is the authority participants reason against when the code and their assumptions disagree.
Layers
| Layer | Meaning |
|---|---|
Meridian FACT |
Supported by the supplied Meridian source material, cited below |
LAB REPRESENTATION |
An intentional simplification or lab-chosen detail, explicitly labelled |
NOT MODELLED |
Deliberately excluded; the source is silent or the behaviour is out of scope |
Rule this register exists to enforce
Inventing lab code is acceptable. Inventing Meridian platform behaviour is not. Where the source is silent, the silence is recorded here rather than resolved by a plausible default.
Sources referenced: pgs-lab-spec-pack.md Spec 1 (Support Refunds for S2I transactions),
pgs-epic-feature-story-examples.md, pgs-example-claude-md-for-labs.md.
1. Request and response contract
| # | Decision | Source | Layer |
|---|---|---|---|
| 1.1 | Refund request field mapping WSAPI → Payment Processor, as tabulated in §2 below | Spec 1, “Request field mapping (WSAPI → Payment Processor API)” | Meridian FACT |
| 1.2 | Response carries order.totalCapturedAmount, order.totalRefundedAmount, order.status (REFUNDED, PARTIALLY_REFUNDED), and transaction.authorizationResponse.{responseCode,approvalCode} |
Spec 1, “Response fields (selection)” | Meridian FACT |
| 1.3 | Currency cannot change on a refund; it is carried but not re-evaluated at the seam | Spec 1, mapping table note on transaction.currency |
Meridian FACT |
2. Field mapping (implemented verbatim)
| WSAPI field | Required | Payment Processor field |
|---|---|---|
merchantId |
Yes | merchantWsApiId |
transactionId |
Yes | wsApiSupport.transactionWsApiId |
orderId |
Yes | wsApiSupport.orderWsApiId |
version |
Yes | wsApiSupport.wsApiVersion |
transaction.amount |
Yes | amounts.transactionAmount |
transaction.currency |
Yes | paymentCurrency |
transaction.reference |
No | merchantOrder.transactionReference |
transaction.targetTransactionId |
Conditional | wsApiSupport.targetTransactionWsApiId |
action.refundAuthorization |
No | wsApiSupport.refundAuthorization |
3. Endpoint selection
| # | Decision | Source | Layer |
|---|---|---|---|
| 3.1 | Two refund endpoints exist, selected by which identifiers the caller supplies | Spec 1, “API contract” | Meridian FACT |
| Caller supplies | Endpoint |
|---|---|
| Order ID + original transaction ID (payment) | POST /card-payments/{card_payment_gateway_id}/refunds |
| Payment gateway ID + capture transaction gateway ID | POST /card-payments/{card_payment_gateway_id}/card-captures/{card_transaction_gateway_id}/refunds |
| # | Decision | Source | Layer |
|---|---|---|---|
| 3.2 | Representative lab case: a request carrying transaction.targetTransactionId is the capture-target case and must use the capture-refund endpoint |
Derived directly from 3.1 | Meridian FACT (mapping) + LAB REPRESENTATION (choice of this case as the representative one) |
| 3.3 | Explicit non-rule. Endpoint choice is not online versus offline | Spec 1 treats these as separate concerns | Meridian FACT |
Online/offline is request-body state carried by
action.refundAuthorization→wsApiSupport.refundAuthorization. Selecting an endpoint on the basis of online/offline would encode a Meridian rule that does not exist.
4. Status codes and error semantics
| # | Decision | Source | Layer |
|---|---|---|---|
| 4.1 | 200 processed, 400 validation failure, 403 missing refund privilege, 405 invalid method, 409 idempotency conflict, 500 system error |
Spec 1, “HTTP status codes” | Meridian FACT |
| 4.2 | A repeated request carrying the same idempotency key returns 409 and creates no second refund |
Spec 1, “Error scenarios” and acceptance criteria | Meridian FACT |
| 4.3 | Client errors (4xx) are distinguished from server errors (5xx); responses to callers never leak stack traces, internal class names, or sensitive data | pgs-example-claude-md-for-labs.md, “Error handling” |
Meridian FACT |
| 4.4 | 403 for missing REFUNDS privilege is a real source-backed status. Merchant-privilege enforcement is NOT MODELLED in this lab slice — the represented seam covers contract, idempotency and error-semantic correctness. Entitlement remains a legitimate downstream concern and must not be invented into the seam. |
Spec 1, “Merchant privileges” | NOT MODELLED |
5. Business rules
| # | Decision | Source | Layer |
|---|---|---|---|
| 5.1 | A refund must not exceed the total captured amount unless EXCESSIVE_REFUNDS is granted; per-capture refunds must not exceed each capture’s amount |
Spec 1, “Business rules” | Meridian FACT |
| 5.2 | The remaining-refundable determination therefore depends on stored transaction state (totalCapturedAmount, totalRefundedAmount), which the Payment Processor holds. Payment Processor is authoritative for it. |
Derived from 5.1 and 1.2 | Meridian FACT |
| 5.3 | EXCESSIVE_REFUNDS itself is NOT MODELLED; the lab represents the base rule only, and the excessive-refund path is out of scope for this slice |
Spec 1 lists excessive refund as Phase 1.1 | NOT MODELLED |
| 5.4 | Boundary validation may legitimately exist in more than one service. What must not exist twice is an independently-encoded authoritative domain decision. | Scenario Document §7 | Meridian FACT |
6. Idempotency
| # | Decision | Source | Layer |
|---|---|---|---|
| 6.1 | Every money-moving path is idempotent; a repeated request must never double-refund | pgs-example-claude-md-for-labs.md, non-negotiable 2 |
Meridian FACT |
| 6.2 | Duplicate detection produces 409 |
Spec 1 | Meridian FACT |
| 6.3 | Transport of the identity. The source states the rule and the status but never names a transport field. This lab carries the identity as the WSAPI body field idempotencyKey, propagated across the seam as the HTTP header Idempotency-Key. |
Source silent | LAB REPRESENTATION |
| 6.4 | Key derivation is NOT MODELLED and is not graded. The incoming, caller-supplied key is used unchanged. Only propagation and stability across the seam are assessed. Inventing a composition rule would manufacture a requirement the source does not state. |
Source silent | NOT MODELLED |
7. Online and offline
| # | Decision | Source | Layer |
|---|---|---|---|
| 7.1 | Refunds may be offline (against an existing PAYMENT or CAPTURE) or online (authorization plus a settlement leg handled downstream); the flag is controlled by CPC | Spec 1, “In scope (Phase 1)” | Meridian FACT |
| 7.2 | The lab treats online/offline state as an input supplied to the seam. CPC’s ownership of that decision is not modelled, and neither TTA nor Payment Processor is presented as owning it. | Scenario Document §4 | LAB REPRESENTATION |
| 7.3 | The online path performs represented authorization-facing behaviour via a deterministic lab stub with no network dependency | Lab construct | LAB REPRESENTATION |
| 7.4 | No settlement artifact is ever created. Settlement, injection, LCS and DCF are downstream and outside this service. | Spec 1, “Out of scope” | Meridian FACT |
8. Correlation and observability
| # | Decision | Source | Layer |
|---|---|---|---|
| 8.1 | A correlation ID is propagated across every service hop | pgs-example-claude-md-for-labs.md, non-negotiable 3 |
Meridian FACT (principle) |
| 8.2 | The specific header used on the represented refund seam is a lab choice. The correlation headers named in the supplied material (X-Client-Correlation-Id, X-Mc-Correlation-Id, X-Mc-Correlation-Request-ID, X-Mc-Tns-Logging-Id, X-Mc-Toggle-Version) belong to the Retrieve Payer Authentication API, not the refund path. They are not presented here as the Meridian refund-path correlation header. |
Source establishes the principle, not the refund-path header | LAB REPRESENTATION |
| 8.3 | No PAN, PII, key, credential, token, or authorization code is written to any log on any path | pgs-example-claude-md-for-labs.md, non-negotiable 1 |
Meridian FACT |
9. Scope boundaries
| # | Decision | Source | Layer |
|---|---|---|---|
| 9.1 | All Void flows (Void-Auth, Void-Capture, Void-Pay, Void-Refund) are out of scope and must not be implemented | Spec 1, “Out of scope” | Meridian FACT |
| 9.2 | Pre-settlement reversals, unsettled transactions, and non-card refunds are out of scope | Spec 1, “Out of scope” | Meridian FACT |
| 9.3 | There is no pre-risk assessment on subsequent refund transactions; inventing a risk or fraud call in the refund path fabricates a dependency | Spec 1, “Out of scope” | Meridian FACT |
| 9.4 | CPC, injection, LCS API, DCF, A3RS, BECS, BPSS, ISO 8583 / DE48 mapping, regional routing and blue-green topology are outside the lab runtime | Scenario Document §12 | NOT MODELLED |
| 9.5 | The wider Meridian flow is WSAPI → TTA → Payment Processor → CPC → Injection → LCS API → DCF. Only TTA → Payment Processor is executable here. |
Spec 1 context; Scenario Document §4 | Meridian FACT (flow) + LAB REPRESENTATION (slice) |
10. Contract evolution
| # | Decision | Source | Layer |
|---|---|---|---|
| 10.1 | APIs are contract-first; the OpenAPI document is the source of truth and a non-breaking change updates the spec rather than forking a version | pgs-example-claude-md-for-labs.md, “APIs” |
Meridian FACT |
| 10.2 | Production deployments are incremental, reversible and version-tolerant across instances | pgs-epic-feature-story-examples.md, “Controlled Production Deployments” |
Meridian FACT |
| 10.3 | The lab contract version numbers (v1, v2) and the specific additive delta between them are a lab construct |
Lab construct | LAB REPRESENTATION |
| 10.4 | The rollout order derived in this lab belongs to the specific additive change represented here. Producer-first is not presented as a universal Meridian rule. | Scenario Document §8 | Meridian FACT (principle) |
11. Layering and architecture
| # | Decision | Source | Layer |
|---|---|---|---|
| 11.1 | Controller (API) → Service (business logic) → Repository (persistence). Controllers hold HTTP concerns only. | pgs-example-claude-md-for-labs.md, “Architecture and code shape” |
Meridian FACT |
| 11.2 | Configuration is externalised; no secrets, hostnames or environment-specific URLs in source | pgs-example-claude-md-for-labs.md |
Meridian FACT |
| 11.3 | In-memory stores replace Oracle/H2 persistence for the lab | Lab construct | LAB REPRESENTATION |
12. Open questions
Recorded rather than resolved. An implementation that silently answers one of these has encoded an unresolved question as production fact, which is a hard-fail condition.
| # | Question | Why it is open |
|---|---|---|
| 12.1 | Exact production idempotency-key derivation | Source defines the duplicate rule and the 409, never the derivation |
| 12.2 | The production correlation header on the refund path | Named headers in source belong to a different API |
| 12.3 | Whether merchant-privilege enforcement belongs at this seam or downstream | Source establishes the privileges; it does not assign them to a component in this slice |
Change log
| Date | Change |
|---|---|
| 2026-09-04 | Initial register. Phase A. SEED-05 endpoint mapping recorded and gated; SEED-06 candidate testing completed. |