Payment

02 / Implementation record

Core flows

1. Create payment and emit payment-created event

   • Trigger: internal service call PaymentService.createPayment.
   • Steps: persist Payment, append PaymentHistory(NEW), publish PaymentCreatedEvent.
   • Output: persisted payment with audit history row.
   • Failure/edge cases: persistence/serialization errors during history write.

2. Provider payment execution

   • Trigger: PaymentProvidersExecutor.initPayment (manual/job-driven).
   • Steps: delegate to provider (PaymentProvider.executePayment), translate to PaymentUpdateData, apply status update.
   • Output: provider reference + updated payment status.
   • Failure/edge cases: provider exception sets payment to ERROR.

3. Payment status update

   • Trigger: provider callback logic or internal update call.
   • Steps: locate payment by UUID or externalId, lock by payment UUID, enforce monotonic status progression, append history, publish PaymentStatusUpdatedEvent when changed.
   • Output: updated payment and history.
   • Failure/edge cases: invalid amount for confirmed status, unknown payment, lock/contention handling.

4. Subscription initialization and checkout redirect

   • Trigger: POST /subscriptions or PUT /subscriptions.
   • Steps: validate open-subscription constraints, resolve plan+user, call provider initSubscription, return redirect URL.
   • Output: checkout redirect payload.
   • Failure/edge cases: existing open subscription, missing user/plan, provider failures.

5. Stripe subscription lifecycle sync

   • Trigger: Stripe webhook (/payments/webhooks/stripe).
   • Steps: verify signature, process events (invoice.paid, customer.subscription.created|updated|deleted), create/update subscription state and related payment rows.
   • Output: synchronized local subscription/payment state.
   • Failure/edge cases: signature mismatch, event ordering races, missing metadata.

6. Subscription payment posting after transaction completion

   • Trigger: consumed TransactionStatusUpdatedEvent.
   • Steps: when transaction is COMPLETED, locate subscription by debitReferenceId, append subscription payment history.
   • Output: subscription history enriched by completed transaction.
   • Failure/edge cases: missing subscription for event payload.

Core flow source: backend/modules/payment/AGENTS.md