Choose the path that fits your team
Product teams can use @payops/sdk to create invoices, issue checkout links, inspect status, and consume typed API responses from a PayOps deployment. This keeps payment truth behind a service boundary and gives frontend and backend code a small integration surface.
Platform teams that operate Solana ingestion, PostgreSQL, and workers use @payops/ingestion and @payops/reconciliation for the durable pipeline. Use @payops/core separately when you need offline transaction parsing, fixture verification, or conformance checks.
# Service boundary
npm install @payops/sdk @payops/contracts
# Operated backend
npm install @payops/ingestion @payops/reconciliation @payops/webhooks
# Offline verification
npm install @payops/coreVerify canonical payment evidence offline
@payops/core parses canonical Solana transaction fixtures and verifies the selected transfer against the fixture expectation. This is the right boundary for deterministic evidence checks and conformance, not durable invoice allocation.
Parse the fixture and transfer through the package's public helpers, then call verifyPayment with the fixture, selected transfer, and all parsed transfers. The report contains the complete ordered checks and a single verified result.
import { verifyPayment } from "@payops/core";
const report = verifyPayment(fixture, selectedTransfer, allTransfers);
if (!report.verified) throw new Error("payment evidence did not verify");Record exact payment expectations
Create each invoice with its token mint, settlement wallet, exact base-unit amount, customer reference, and expiry. Those values become the immutable comparison boundary.
Do not derive an expected amount from a rounded UI value at reconciliation time. Persist the integer amount that was shown to the payer, and preserve a stable invoice ID separately from any human-readable reference.
Connect read-only chain ingestion
Give the ingestion worker public settlement addresses and read-only RPC access. It should observe finalized Mainnet transactions, extract supported token transfers, and store their canonical representation with an explicit parser version.
PayOps never needs transaction-signing authority. Keeping observation separate from wallet control reduces the blast radius of the reconciliation service and makes historical replay possible.
Persist the decision before side effects
Treat the reconciliation decision, its evidence, the lifecycle event, and the first delivery record as one transactional boundary. Your invoice should not be marked paid while the evidence or event is missing.
Repeated processing of the same canonical invoice and transfer is idempotent. A conflicting payload for an already reserved source identity fails closed instead of replacing history.
Verify before parsing
Webhook consumers must verify the HMAC against the raw request body before JSON parsing. Accept the current and previous secret during rotation, then deduplicate by event ID.
Validate the complete lifecycle envelope after signature verification. Unknown event types, malformed identifiers, unsupported schema versions, extra fields, and timestamps outside your accepted tolerance should be rejected before business logic runs.
const verified = verifyWebhook({ rawBody, signature, secret });
if (!verified) return new Response(null, { status: 401 });Roll out and operate the integration
Begin with historical replay, then staging, then a bounded production cohort. Track paid decisions, exceptions, webhook latency, retry exhaustion, and the age of the oldest unreviewed exception.
Assign an owner for exception review and an owner for webhook delivery. Document how to rotate secrets, replay one event, pause delivery during an incident, and export an evidence pack when finance disputes a payment state.