Skip to content
arula

Meridian Engineering / Lab 2

Payment Processor agent guidance

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

  1. Define / Plan
  2. Execute
  3. Judge
  4. Learn

What you are developing

Intuition

Recognize the limits of an agent’s local view and authority.

Common language / Standardization

State repository scope, governing rules, and expected returns precisely.

Habit / Behavior

Consult the applicable instructions before delegating and reconcile the results yourself.

Use this material alongside the stage you are working on. Return to the complete journey.

CLAUDE.md — pgs-payment-processor

The Payment Processor side of the represented refund seam. The workspace root CLAUDE.md applies here too; this file adds what is specific to this service.

What this service is responsible for

  • exposing the represented refund API
  • the authoritative refund decisions in this slice, because they depend on state only this service holds:
    • how much of an order remains refundable, from the total captured amount less what has already been refunded
    • whether a refund targeting a specific capture fits within that capture’s own amount
    • whether this refund duplicates one already accepted
  • the represented online authorization step
  • returning correct response and error semantics

What it must never do

  • Create a settlement artifact. Settlement, injection, LCS and DCF are downstream and outside this service. There is no exception to this.
  • Hold WSAPI or TTA-specific logic. This service knows about refunds, not about the shape of the caller that happens to be in front of it today.
  • Implement any Void flow. Void-Auth, Void-Capture, Void-Pay and Void-Refund are all out of scope. Code near the refund path that looks like it belongs to that work is not an invitation.

Idempotency

Deduplicate on the identity as received. Do not derive, normalise or reconstruct it: a service that deduplicates against an identity it invented for itself is not deduplicating anything the caller can rely on. If the identity arriving here looks wrong, that is a finding about the seam, to be raised — not repaired locally.

Error semantics

200 processed, 400 validation failure, 409 duplicate, 500 system error. Responses to the caller are opaque: no stack traces, no internal class names, no field values. Business refusals are structured outcomes, not exceptions.

Download the unchanged original source