Skip to content

STORY: Publish durable payment instruction state events #250

Closed

Description

@ramioooz

Outcome

Payment Service publishes durable, versioned payment-instruction state events so downstream workflow components can observe payment progress without synchronous coupling.

Parent and Sprint

Scope

  • Add a PostgreSQL-backed outbox written in the same transaction as payment-instruction creation and terminal state transitions.
  • Publish versioned PENDING, COMPLETED, and FAILED payment-state events through the existing SIT Kafka platform.
  • Preserve stable event identity, correlation, causation, instruction identity, idempotency key, amount, currency, status, and occurred-at fields.
  • Apply at-least-once publication with bounded retry and durable failure visibility using existing repository conventions.
  • Keep payment-provider credentials, public payment routes, and direct account or ledger mutation out of this story.

Acceptance Criteria

  • Each persisted payment state transition produces exactly one durable outbox record in the same database transaction.
  • Publisher restart or transient Kafka failure retries safely without losing the event or creating a second business transition.
  • Published events conform to a versioned organization contract and can be inspected in AKHQ.
  • SIT verification demonstrates creation and one terminal outcome with matching PostgreSQL outbox and Kafka evidence.
  • No direct balance mutation or synchronous call to Account or Ledger Service is introduced.
  • Only load-bearing persistence/publication coverage is added; no redundant unit-test suite or CI job is created.

Delivery

  • Implement from current payment-service main in an isolated branch.
  • Add or update the organization AsyncAPI contract only when required by the implementation.
  • Open a normal, non-draft PR linked to this story and parent epic EPIC: Payment Rail Architecture #31.
  • Update project status and handoff documentation with verification evidence.

Activity

  1. self-assigned this
    on Sep 6, 2026
  2. ramioooz commented on Sep 6, 2026

    @ramioooz
    MemberAuthor

    Implementation is available for review:\n\n- payment-service PR: https://github.com/digital-bank-java/payment-service/pull/13\n- config-repo PR: https://github.com/digital-bank-java/config-repo/pull/48\n- infra-sit PR: https://github.com/digital-bank-java/infra-sit/pull/41\n- contract PR: https://github.com/digital-bank-java/.github/pull/251\n\nVerification: payment-service Maven verify with -DskipUnitTests=true passed with 19 tests using Docker/Testcontainers; the SIT Kafka chart lint/template validation passed. These PRs are coordinated and must be merged before payment-state-event SIT verification.

  3. ramioooz commented on Sep 6, 2026

    @ramioooz
    MemberAuthor

    Handoff documentation is now prepared in PR #252, alongside the implementation and delivery PRs:

    Payment Service Maven test and verify, PostgreSQL/Testcontainers outbox coverage, container smoke, and Helm validation passed. The remaining acceptance is post-merge SIT verification of the outbox event in Kafka/AKHQ and PostgreSQL; no provider integration, balance mutation, or redundant CI/test suite was added.

  4. ramioooz commented on Sep 6, 2026

    @ramioooz
    MemberAuthor

    Post-merge SIT rollout (2026-09-07)

    • Merged payment-service#13 mainline was built locally as digital-bank-java/payment-service:0.0.2.
    • Helm lint and rendering passed for the merged chart (0.2.0, app version 0.0.2).
    • Kafka Helm release revision 4 was upgraded successfully in digital-bank-sit.
    • The required topics now exist:
      • payment.instruction.state.v1
      • payment.instruction.state.v1.dlq
    • Payment Service release revision 4 completed successfully.
    • The deployment is 1/1 Ready and the pod is running the freshly built image digest.
    • Flyway is up to date and startup logs contain no Kafka or outbox errors.

    Remaining acceptance is behavioral: create a protected payment instruction, complete or fail it, and compare the PostgreSQL outbox row with the Kafka event in AKHQ. No credentials, tokens, or payment data were recorded.

    Related merged changes:

  5. ramioooz commented on Sep 7, 2026

    @ramioooz
    MemberAuthor

    Payment Service candidate validation recorded: built digital-bank-java/payment-service:sit-outbox-fix-20260907 from PR #14 with 22 tests passing during the container build, deployed it with the existing SIT values, and verified Helm revision 6 with a 1/1 Ready pod. Readiness returned HTTP 200 and structured logs showed a clean startup. PR #14 remains open; functional PENDING/COMPLETED/FAILED state-event and Kafka/outbox acceptance remains after merge.

  6. ramioooz commented on Sep 7, 2026

    @ramioooz
    MemberAuthor

    Post-merge SIT rollout checkpoint for the durable payment state-event implementation.

    • Merged implementation: payment-service #13
    • Merged retry-accounting fix: payment-service #14
    • Candidate built from merged mainline: digital-bank-java/payment-service:sit-payment-events-20260907
    • Helm release payment-service in digital-bank-sit: revision 7, status deployed.
    • Deployment: 1/1 ready, zero restarts; readiness returned {"status":"UP"}.
    • Kafka topics confirmed: payment.instruction.state.v1 and payment.instruction.state.v1.dlq.
    • Startup logs show the application started on port 8085 with the sit profile.

    This records deployment and platform readiness only. Functional creation/terminal-transition, duplicate-publication, PostgreSQL outbox, and AKHQ evidence remain to be executed before closing this story.

  7. ramioooz commented on Sep 7, 2026

    @ramioooz
    MemberAuthor

    Additional SIT boundary verification:

    • An unauthenticated POST /internal/v1/payment-instructions returned 401 with WWW-Authenticate: Bearer and application/problem+json.
    • No payment instruction or outbox mutation was created by this check.

    The remaining positive-path acceptance (PENDING creation, terminal transition, outbox row, Kafka event, and duplicate publication) requires an authorized synthetic payment.internal bearer token. No credential value was read or fabricated.

  8. ramioooz commented on Sep 9, 2026

    @ramioooz
    MemberAuthor

    Governance correction: assigned the native GitHub Issue Type Story. The issue remains correctly parented under EPIC: Payment Rail Architecture (#31) in Sprint 5.

  9. added theissue type on Sep 9, 2026
  10. ramioooz commented on Sep 9, 2026

    @ramioooz
    MemberAuthor

    Controlled SIT acceptance (2026-09-10)

    • Authenticated payment instruction creation through API Gateway returned 201 Created.
    • Repeating the same normalized request returned 200 OK with idempotent replay and the original instruction identity.
    • Completion returned 200 OK; PostgreSQL showed the instruction in COMPLETED state.
    • PostgreSQL outbox evidence for the instruction contained one PENDING row and one COMPLETED row.
    • Kafka topic payment.instruction.state.v1 contained matching PENDING and COMPLETED PaymentInstructionStateChanged.v1 events for the same instruction, amount 25 AED, currency AED, and correlation payment-acceptance.
    • No provider integration, account/ledger mutation, direct downstream call, or secret value was introduced.
    • Temporary Auth fixture and port-forward were cleaned up; SIT returned to baseline and remained healthy.

    The durable payment state-event story acceptance criteria are complete.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

Labels

No labels
No labels

Type

Projects

No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions