Payment architecture
Payment architecture
Section titled “Payment architecture”Audience: backend, product
Status: specced
Owns: backend
Depends on: System architecture, Orchestrator backend, CAP Payment module, LMS API, Event catalog
Rule: Orchestrator never knows price
Section titled “Rule: Orchestrator never knows price”Orchestrator’s payment processor must never invent a price. The service that owns the purchasable computes the amount, then OL processes (amount, reference) pairs.
| Purchasable | Prices | Client-facing pay HTTP |
|---|---|---|
| CAP application | CAP | POST /applications/:id/pay |
| LMS enrollment / level offering | LMS | checkout routes |
| Organization cohort | CAP + LMS catalogues; OL snapshots line items | OL POST /v1/organizations/:orgId/cohorts/:id/pay |
Cohort invoices are the first SKU owned by Orchestrator. OL still calls CAP/LMS for current catalogue amounts at quote time — it does not hard-code RPL/NSQ/offering fees. See Organization module.
Calling CAP/LMS price RPCs from an OL quote is allowed only for the cohort SKU (internal gRPC, never the public pay path for applications). Application and enrollment initiation stays product → OL InitiatePayment.
| Concern | Owner |
|---|---|
| Pricing (RPL fee, NSQ fee, course price, …) | CAP / LMS (catalogues). Cohort quote snapshots those amounts on OL |
Processing (checkout, provider adapter, webhook, payments row) |
Orchestrator |
| Client-facing pay API | CAP/LMS for applications/enrollments; OL for organization cohorts |
For application and enrollment checkout, clients never talk to Orchestrator to start Paystack. Amount is computed server-side in CAP/LMS and passed on internal gRPC InitiatePayment. For cohorts, the org client talks to OL REST; OL recomputes the snapshot and uses the same payment adapter in-process (referenceType: organization_cohort). Webhooks remain OL-only.
Flow (CAP application payment)
Section titled “Flow (CAP application payment)”sequenceDiagram participant Client participant CAP participant OL as Orchestrator participant PS as Paystack participant RMQ as RabbitMQ
Client->>CAP: POST /cap/applications/:id/pay CAP->>CAP: Validate stage; compute amount CAP->>OL: gRPC InitiatePayment(amount, referenceType, referenceId, ...) OL->>OL: payments row pending OL->>PS: Provider createCheckout PS-->>OL: checkoutUrl + providerReference OL-->>CAP: paymentId, checkoutUrl CAP-->>Client: checkoutUrl PS->>OL: Webhook (single URL) OL->>OL: Verify signature; mark success OL->>RMQ: outbox payment.completed RMQ->>CAP: payment.completed CAP->>CAP: Match referenceId; unlock next stage- Client → CAP:
POST /cap/applications/:id/pay - CAP validates state (correct stage, not already paid) and computes the amount (RPL fee, NSQ fee, etc.).
- CAP → Orchestrator (gRPC):
InitiatePayment({ amount, currency, referenceType: "cap_application", referenceId: applicationId, userId, purpose, metadata }) - Orchestrator creates a
paymentsrow (pending), calls the provider adapter, returns{ paymentId, checkoutUrl }to CAP. - CAP → Client: checkout URL.
- Provider → Orchestrator webhook — one URL; only Orchestrator holds the provider secret and verifies signatures.
- Orchestrator marks success and outbox-publishes
payment.completed{ referenceType, referenceId, paymentId, amount, paidAt, provider? }. - CAP consumes the event, matches
referenceIdtoapplicationId, unlocks Folder Arrangement (RPL) or induction (NSQ).
CAP is the client-facing entry point and calls Orchestrator server-to-server — never the reverse for pricing or initiation.
Provider adapters (same shape as stage strategies)
Section titled “Provider adapters (same shape as stage strategies)”Closed set of adapters in Orchestrator code; adding a provider is a new class — CAP and the public API contract do not change. payments.provider records which adapter handled each row (regional routing / failover).
interface PaymentProviderAdapter { readonly key: string; // "paystack" | "flutterwave" | ...
createCheckout(input: { amount: number; currency: string; reference: string; metadata: Record<string, unknown>; }): Promise<{ providerReference: string; checkoutUrl: string }>;
verifyWebhookSignature(rawBody: Buffer, signature: string): boolean;
parseWebhookEvent(rawBody: Buffer): { providerReference: string; status: "success" | "failed"; };}Paystack is the first adapter; design stays provider-agnostic.
Idempotency (both ends)
Section titled “Idempotency (both ends)”| Side | Rule |
|---|---|
| CAP | Before InitiatePayment, check for an existing pending or successful payment against application_id. Pending with a stored checkoutUrl is returned as 200 (resume); completed is 409; do not re-initiate blindly |
| Orchestrator | Webhooks are at-least-once: unique constraint on provider_reference; replay of an already-success payment is a no-op |
Webhooks only in Orchestrator
Section titled “Webhooks only in Orchestrator”- One registered provider webhook URL
- One place holding the provider secret
- One signature-verification path
No business service (CAP, LMS, …) exposes its own payment-provider webhook endpoint.
Organization cohort settlement
Section titled “Organization cohort settlement”On payment.completed with referenceType: organization_cohort:
- Activate the cohort only if it is still
PENDING_PAYMENT(24h quote TTL; late webhook onEXPIREDdoes not activate). - Credit CAP centre wallets once using OL policy
organization_cohort_settlement(split20/80 default;effectiveFrom <= paidAt). LMS line items are platform revenue. - Candidate
POST /pay/ LMS checkout for a consumed seat returns 200{ settlement: "organization_cohort", checkoutUrl: null }and unlocks the workflow withoutInitiatePaymentand without a second wallet credit.
Full rules: Organization module.
Generalization
Section titled “Generalization”Same flow for LMS course payments (referenceType: lms_enrollment) or level-offering packages (lms_level_enrollment). Organization cohorts use referenceType: organization_cohort with OL as the client-facing business service. WorkMasters later can still use InitiatePayment. LMS snapshots the charged amount on the entitlement / level enrollment so a later catalogue price change cannot rewrite a completed purchase. Staff admin payments and dashboard (GET /admin/payments*, GET /admin/dashboard) read those LMS checkout snapshots — they do not list Orchestrator payments rows. Org transaction history reads OL payments for organization_cohort.
See also
Section titled “See also”- Product intent → Payment module · LMS checkout · Organization
- OL tables / Phase 1 → Orchestrator backend
- Event row → Event catalog (
payment.completed) - Workflow gate → RPL lifecycle · LMS lifecycle · Workflow abstraction