Pick the smallest useful surface
You do not need to install the whole monorepo into an application. Start from the boundary your team owns: API consumption, deterministic domain logic, ingestion, durable reconciliation, webhook delivery, or conformance fixtures.
All packages share versioned contracts, but infrastructure packages intentionally expose lower-level responsibilities. Product applications normally need the SDK and contracts only.
Product integration
@payops/sdk is the typed merchant API client. @payops/core parses and verifies canonical Solana payment fixtures offline. @payops/contracts defines the stable shared lifecycle event contracts.
Use the SDK for merchant and checkout workflows. Use contracts when producing or consuming lifecycle events. Use core for deterministic transaction evidence and conformance checks, not invoice persistence.
npm install @payops/sdk @payops/contractsInfrastructure integration
@payops/ingestion records Solana transfer representations. @payops/reconciliation persists decisions. @payops/webhooks delivers signed events with bounded retries.
These packages assume you are operating workers and PostgreSQL. They provide migrations and explicit storage APIs so queues, leases, attempts, and evidence survive process restarts.
Package responsibilities
Keep fixture parsing and offline verification in core, chain observation in ingestion, invoice allocation plus transaction and reporting concerns in reconciliation, and endpoint delivery in webhooks. Avoid importing storage internals into product code when the SDK or public contracts provide the required boundary.
This separation makes upgrades reviewable: a parser change can be replayed, a reconciliation rule can be fixture-tested, and a delivery change cannot rewrite an earlier payment decision.
Conformance
@payops/reference provides replayable fixtures and expected outcomes so integrations can prove they interpret the same payment facts the same way.
Run conformance whenever you upgrade a package, parser, database migration, or event consumer. A release should preserve expected decisions unless the contract change is explicit and reviewed.
Version and publish safely
Pin compatible package versions together, review release notes, and test the packed artifacts rather than relying only on source-tree imports. Verify native ESM loading and generated declarations in the same Node.js range used in production.
Published PayOps packages are public and intended for normal npm installation. Production releases use provenance-aware automation and should not depend on a long-lived publishing token in application infrastructure.