Payment Service
Purpose
Payment orchestration — initiates, authorizes, processes, and completes financial transfers.
Responsibilities
- Payment initiation and state machine
- Idempotency enforcement
- Fraud check coordination
- Ledger posting trigger
- Refund and reversal initiation
Non-Responsibilities
- Fraud decision logic (Fraud Service)
- Ledger posting (Ledger Service)
- Account validation details (Account Service)
APIs
| Method | Endpoint | Auth | Idempotent | Description |
|---|---|---|---|---|
| POST | /api/v1/payments | Bearer | Yes | Initiate payment |
| GET | /api/v1/payments/{id} | Bearer | — | Get payment status |
| POST | /api/v1/payments/{id}/cancel | Bearer | Yes | Cancel payment |
| POST | /api/v1/payments/{id}/refund | Bearer | Yes | Refund payment |
Database
| Table | Key Columns | Description |
|---|---|---|
| payments | id, from_account, to_account, amount, currency, status | Payment records |
| payment_state_history | payment_id, status, timestamp | State transitions |
| idempotency_records | key, request_hash, response, status | Idempotency store |
Kafka
Produces: PaymentInitiated, PaymentAuthorized, PaymentCompleted, PaymentFailed, PaymentRefunded, FraudCheckRequested
Consumes: FraudCheckCompleted, LedgerTransactionCreated
Partition key: payment_id
Consumer group: payment-service-group
Dependencies
Sync: Account Service, Fraud Service (with timeout) Async: Kafka for saga coordination
Failure Handling
- Fraud timeout → retry then fail
- Ledger failure → saga compensation
- Duplicate request → return cached response
Scaling
Highest traffic service. HPA on CPU and custom payment queue depth metric.
Security
CUSTOMER role for own payments. Idempotency-Key header required on POST.
Observability
Metrics: payment_success_total, payment_failure_total, payment_processing_latency.