Skip to content

Add Infrastructure Service for Payments to Cellix framework #325

Description

@noce-nick

Summary

Add vendor-agnostic payment infrastructure to Cellix through:

  • @cellix/service-payment — defines the payment service contract required by Cellix applications.
  • @cellix/service-payment-mock — provides an in-memory implementation for development and testing.

Future vendor integrations, such as @cellix/service-payment-cybersource, should implement the same contract so applications can switch providers without changing application-level payment functionality.

No real payment vendor integration is required for this task.

Requirements

@cellix/service-payment

Create a payment service contract following existing Cellix infrastructure service conventions.

The contract must support:

Transactions

  • Charge a payment instrument.
  • Refund a completed transaction.
  • Look up a transaction for reconciliation/status verification.
  • Return normalized transaction identifiers and status/result information.

Payment Instruments

  • Create/register a payment instrument.
  • Reference stored payment instruments through vendor-agnostic identifiers.
  • Update or replace an existing payment instrument.
  • Use stored payment instruments for transactions and subscriptions.

Payment instruments may be associated with application domain entities, such as members, but those associations remain the responsibility of the consuming application. Vendor-specific and sensitive payment details should remain encapsulated by the concrete implementation.

Subscriptions

  • Create/manage recurring payments using stored payment instruments.
  • Support fixed recurring amounts.
  • Support dynamic recurring amounts that may change between billing periods.
  • Expose normalized subscription identifiers and status information.

Business rules determining dynamic subscription amounts belong to the consuming application. For example, OCOM may calculate an amount based on the number of members in a community; the payment service is responsible for processing the resulting amount.

The contract should remain vendor-agnostic and must not expose vendor SDK types or implementation-specific concepts.

@cellix/service-payment-mock

Create an in-memory implementation of the @cellix/service-payment contract that:

  • Implements all supported transaction, refund, lookup, payment instrument, and subscription capabilities.
  • Maintains relevant payment state in memory for the lifetime of the service.
  • Generates stable identifiers for mock payment resources.
  • Supports fixed and dynamic subscription amounts.
  • Provides realistic success and invalid-operation behavior.
  • Returns the same Cellix-level types expected from future vendor implementations.

The mock should function as a drop-in payment service implementation rather than exposing a separate testing-specific API.

OCOM Integration

Add @ocom/service-payment as the application-level payment service, initially backed by @cellix/service-payment-mock.

Wire the service into the existing OCOM API startup/context patterns so it is initialized and available for future application functionality.

No OCOM payment workflows should consume the service as part of this task. Future tasks can replace the mock with any compatible @cellix/service-payment-* implementation without changing application consumers.

Testing

Add tests covering:

  • Charges, refunds, and transaction lookup.
  • Payment instrument creation and updates.
  • Transactions using stored payment instruments.
  • Fixed and dynamic subscriptions.
  • Relevant invalid operations.
  • Successful initialization and availability of the payment service within OCOM.

Tests should exercise behavior through the @cellix/service-payment contract where practical.

Out of Scope

  • Integration with CyberSource or any other real payment vendor.
  • Vendor SDK dependencies.
  • OCOM-specific payment workflows or domain associations.
  • Business rules for calculating dynamic subscription amounts.
  • Payment-related GraphQL/API or UI functionality.

Subsequent OCOM tasks will consume the initialized payment service for application-specific payment functionality.

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Labels

No labels
No labels

Projects

  • Status
    No status

Milestone

No milestone

Relationships

None yet

Development

No branches or pull requests

Issue actions