Skip to content

8.5 Payment Service - Domain and Application

Sprint: Sprint 08 - Order and Payment
Feature ID: 8.5
Subtasks: 8.5.1, 8.5.2, 8.5.3, 8.5.4, 8.5.5

Objective

Deliver "Payment Service - Domain and Application" within Sprint 08 - Order and Payment.

Dependencies

Aggregated from the subtasks below (prerequisite task IDs and enablers):

  • 8.4.2
  • 8.5.1
  • 8.5.2

Subtasks

8.5.1 Mock PSP adapter

  • ID: 8.5.1
  • Title: Implement mock PSP gateway adapter
  • Description: A PspGateway port with a mock implementation simulating success/failure (configurable, e.g. by amount or test flag) returning an external reference. Wrapped in a Resilience4j circuit breaker as an external dependency (NFR-10).
  • Business Purpose: Stand in for a real PSP so payment flows are testable (FR-25).
  • Inputs: FR-25, analysis Section 8.7, NFR-10.
  • Outputs: PSP port + mock adapter.
  • Acceptance Criteria:
  • The mock returns success and failure deterministically per its config; calls are breaker-guarded.
  • Dependencies: 8.4.2
  • Complexity: M

8.5.2 Idempotent charge command and endpoint

  • ID: 8.5.2
  • Title: Implement POST /api/v1/payments with idempotency
  • Description: ChargePaymentCommand keyed by paymentRequestId/Idempotency-Key: if already processed, return the prior result; otherwise charge via the PSP, persist the payment + attempt, and publish payment.completed.v1 or payment.failed.v1 via the outbox.
  • Business Purpose: Reliable, non-duplicating payment processing (FR-25, FR-26).
  • Inputs: FR-25, FR-26, event-catalog payment events.
  • Outputs: Charge command, handler, DTOs, endpoint, events.
  • Acceptance Criteria:
  • A successful charge emits payment.completed.v1; a failure emits payment.failed.v1; replaying the same paymentRequestId returns the original result and does not re-charge.
  • Dependencies: 8.5.1
  • Complexity: L

8.5.3 Consume order.created for auto-charge

  • ID: 8.5.3
  • Title: Implement order.created.v1 consumer initiating payment
  • Description: Idempotent (inbox) consumer of order.created.v1 that initiates a charge for the order amount, reusing the charge command. This is the saga step 3 producer of payment outcomes.
  • Business Purpose: Drive the onboarding saga from order to payment asynchronously (FR-10).
  • Inputs: event-catalog saga sequence, FR-10.
  • Outputs: Kafka consumer + inbox guard.
  • Acceptance Criteria:
  • Consuming order.created.v1 produces exactly one payment attempt (inbox-deduplicated) and emits a payment outcome event.
  • Dependencies: 8.5.2
  • Complexity: M

8.5.4 Failed-payment retry scheduler

  • ID: 8.5.4
  • Title: Implement 24/72/168h retry for failed payments
  • Description: A scheduler re-attempting failed payments at 24, 72, and 168 hours, recording each as a new payment_attempt, emitting payment.completed.v1 on eventual success or giving up after the final interval (FR-27).
  • Business Purpose: Recover transient payment failures on a defined cadence (FR-27).
  • Inputs: FR-27.
  • Outputs: Retry scheduler + attempt tracking.
  • Acceptance Criteria:
  • A failed payment is retried at the configured intervals; a later success emits payment.completed.v1; attempts are capped after 168h.
  • Dependencies: 8.5.2
  • Complexity: M

8.5.5 Get payment and refund

  • ID: 8.5.5
  • Title: Implement GET /api/v1/payments/{id} and POST /{id}/refund
  • Description: GetPaymentQuery and RefundPaymentCommand (used in compensation) emitting payment.refunded.v1. Refund is idempotent.
  • Business Purpose: Payment visibility and compensation support (FR-12 compensation).
  • Inputs: analysis Section 8.7, event-catalog payment.refunded.v1.
  • Outputs: Query/command + endpoints + event.
  • Acceptance Criteria:
  • GET returns the payment; refunding a completed payment emits payment.refunded.v1; a second refund of the same payment is a no-op.
  • Dependencies: 8.5.2
  • Complexity: M

Acceptance Criteria

Each subtask above carries its own objective, testable acceptance criteria. This feature is complete when every subtask's acceptance criteria are met.

Deliverables

  • PSP port + mock adapter.
  • Charge command, handler, DTOs, endpoint, events.
  • Kafka consumer + inbox guard.
  • Retry scheduler + attempt tracking.
  • Query/command + endpoints + event.

Definition of Done

  • All subtasks (8.5.1, 8.5.2, 8.5.3, 8.5.4, 8.5.5) completed and their acceptance criteria verified.
  • All listed dependencies satisfied.
  • Build and tests green per the global conventions in ../README.md (Section 3).