Before you begin
PayOps is for teams that already receive USDC or USDT on Solana and need a dependable answer to a business question: which finalized transfer paid which invoice? It is reconciliation infrastructure, not a wallet, checkout processor, or custody service.
For the safest first integration, use a copy of historical invoice expectations and finalized transfers. You can prove that PayOps reaches the same decisions as your team before any result is allowed to change production invoice state.
Install the packages
Use the SDK when your product calls a deployed PayOps merchant API. Use reconciliation when your operations backend imports invoice expectations, allocates finalized transfer evidence, and persists decisions in PostgreSQL. Contracts gives event producers and consumers one shared lifecycle envelope.
Core is the offline parser and verifier for canonical Solana payment fixtures. It is useful for conformance and evidence checks, but it does not schedule RPC requests or persist invoices.
# Product/API integration
npm install @payops/sdk @payops/contracts
# Operated reconciliation backend
npm install @payops/ingestion @payops/reconciliation @payops/webhooksDefine the invoice
Store the expected mint, recipient, exact amount, and invoice reference before asking PayOps to reconcile a transfer.
Amounts are compared in integer base units, not floating-point display values. The supported mint and settlement recipient are explicit, and the invoice expectation is treated as immutable evidence after issue.
invoice_id,customer_id,expected_mint,destination_token_account,amount_base_units,reference_address,issued_at,due_at
inv-0421,customer-acme,<USDC_MINT>,<TOKEN_ACCOUNT>,1250000000,<REFERENCE>,<ISSUED_AT>,<DUE_AT>Record finalized transfer facts
Ingestion observes a finalized Solana transaction and records the transfer signature, instruction coordinates, mint, source, destination, exact amount, reference, slot, and parser version. PayOps keeps the canonical representation that the decision used.
Finality is part of the eligibility rule. A processed or merely confirmed transaction is not promoted to an authoritative payment decision.
Reconcile and keep the evidence
Reconciliation compares the finalized transfer with the invoice expectation. A paid decision requires the supported mint, settlement recipient, exact amount, reference, and network scope to agree. The decision and its evidence are persisted atomically before a lifecycle event is queued.
Missing, conflicting, duplicated, or ambiguous facts do not become a guessed match. They become an explicit payment exception that an operator can investigate without silently changing the invoice.
npx payops-reconciliation migrate
npx payops-reconciliation invoice import --file ./invoices.csv
npx payops-reconciliation reconcile run
npx payops-reconciliation report --format jsonMove from replay to production
Run the reference fixtures and a representative historical replay first. Compare paid decisions, exceptions, and evidence with your existing records. Investigate every difference instead of tuning the system to force a match.
Then connect signed lifecycle events to a staging consumer, verify the raw request body before parsing, deduplicate by event ID, and acknowledge only after durable acceptance. Promote one settlement wallet or merchant cohort at a time and monitor exceptions before expanding scope.