9fac160258
Add independent payment-service (port 8012, payment_db) with foundation licensing, BYO-PSP, merchant accounts, idempotent requests, callbacks, and immutable ledger. Co-authored-by: Cursor <cursoragent@cursor.com>
72 lines
1.8 KiB
Markdown
72 lines
1.8 KiB
Markdown
# Phase 14.4 — Callback & Verification
|
|
|
|
| Field | Value |
|
|
| --- | --- |
|
|
| Identifier | `payment-14.4` |
|
|
| Implementation Priority | **HIGH** |
|
|
| Status | Complete |
|
|
| Service | `payment` |
|
|
| Depends On | `payment-14.3` |
|
|
|
|
> Full specification: [payment-roadmap.md](../../payment-roadmap.md#phase-14-4--callback--verification)
|
|
|
|
## Purpose
|
|
|
|
Ingest PSP callbacks/webhooks, verify signatures, reconcile with PSP verify API, transition requests to paid/failed.
|
|
|
|
## Business Scope
|
|
|
|
Trusted callback processing; admin reconcile retry; publish events for verticals to mark orders paid.
|
|
|
|
## Technical Scope
|
|
|
|
Aggregates: PaymentCallbackLog, PaymentVerificationAttempt. Public callback routes per adapter. `verify_payment()`, `parse_callback()`.
|
|
|
|
## Dependencies
|
|
|
|
`payment-14.3`
|
|
|
|
## Out of Scope
|
|
|
|
Immutable ledger authority (14.5), refunds, Accounting posting.
|
|
|
|
## Capabilities
|
|
|
|
`payment.callbacks`, `payment.verification`, `payment.webhooks`
|
|
|
|
## Permissions
|
|
|
|
`payment.callbacks.view`, `payment.requests.reconcile|manage`; signature-gated public callbacks
|
|
|
|
## Events
|
|
|
|
`payment.callback.received|verified|rejected`, `payment.request.paid|failed`
|
|
|
|
## API Contracts
|
|
|
|
POST `/api/v1/callbacks/{provider_code}/{connection_id}`, POST `.../verify`, GET callback logs
|
|
|
|
## Data Ownership
|
|
|
|
Payment owns callback logs; PSP transaction ids as external refs.
|
|
|
|
## Provider Ownership
|
|
|
|
Webhook secrets in adapter layer.
|
|
|
|
## Integration Rules
|
|
|
|
Never trust return URL alone; always PSP verify. Fast callback ack; async verify allowed.
|
|
|
|
## Quality Gates
|
|
|
|
Signature forgery, replay protection, tenant routing isolation.
|
|
|
|
## Definition of Done
|
|
|
|
Mock callback → verified paid; outbox events; verticals can subscribe.
|
|
|
|
## Future Compatibility
|
|
|
|
Multi-version callbacks per PSP; international webhook formats.
|