Skip to content

Payment architecture

Audience: backend, product
Status: specced
Owns: backend
Depends on: System architecture, Orchestrator backend, CAP Payment module, LMS API, Event catalog

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.

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
  1. Client → CAP: POST /cap/applications/:id/pay
  2. CAP validates state (correct stage, not already paid) and computes the amount (RPL fee, NSQ fee, etc.).
  3. CAP → Orchestrator (gRPC): InitiatePayment({ amount, currency, referenceType: "cap_application", referenceId: applicationId, userId, purpose, metadata })
  4. Orchestrator creates a payments row (pending), calls the provider adapter, returns { paymentId, checkoutUrl } to CAP.
  5. CAP → Client: checkout URL.
  6. Provider → Orchestrator webhook — one URL; only Orchestrator holds the provider secret and verifies signatures.
  7. Orchestrator marks success and outbox-publishes payment.completed { referenceType, referenceId, paymentId, amount, paidAt, provider? }.
  8. CAP consumes the event, matches referenceId to applicationId, 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.

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
  • 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.

On payment.completed with referenceType: organization_cohort:

  1. Activate the cohort only if it is still PENDING_PAYMENT (24h quote TTL; late webhook on EXPIRED does not activate).
  2. Credit CAP centre wallets once using OL policy organization_cohort_settlement (split 20/80 default; effectiveFrom <= paidAt). LMS line items are platform revenue.
  3. Candidate POST /pay / LMS checkout for a consumed seat returns 200 { settlement: "organization_cohort", checkoutUrl: null } and unlocks the workflow without InitiatePayment and without a second wallet credit.

Full rules: Organization module.

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.