Parent
#1027
What to build
New @happyvertical/payments SDK package. Defines the PaymentBackend provider abstraction and ships the package scaffolding (no adapters yet — those are sibling issues).
Mirrors the shape of @happyvertical/ai — one interface, many adapter implementations. Pure provider integration; no SMRT, no DB, no opinions about persistence.
Shape
Package: packages/payments published as @happyvertical/payments.
The PaymentBackend interface must provide:
- Identity and capability declaration: stable id, settlement currency, chain identifier,
x402Capable: boolean, typical confirmation latency, supportsRefunds: boolean, settlement-shape flag (address-based vs URL-based — fiat backends return checkout URLs, not crypto addresses)
createPaymentOption(input) — given a quote id, USD amount, expiry, return a PaymentOption (unique pay-to address or checkout URL, native amount, optional memo)watchPayment(input) — emit/poll for payment status against a previously-created optiongetStatus(quoteId, payTo) — idempotent "what is the state of this quote's option"verifyX402Proof?(input) — for x402-capable backends only; given an X-Payment header and a quote, verify on-chainsendPayout(input) — send native-currency payout to a destination address (or initiate via the backend's payout API for fiat)
Conformance tests: a shared test suite that any adapter can run against to prove it satisfies the interface.
Acceptance criteria
Blocked by
None — can start immediately
Parent
#1027
What to build
New
@happyvertical/paymentsSDK package. Defines thePaymentBackendprovider abstraction and ships the package scaffolding (no adapters yet — those are sibling issues).Mirrors the shape of
@happyvertical/ai— one interface, many adapter implementations. Pure provider integration; no SMRT, no DB, no opinions about persistence.Shape
Package:
packages/paymentspublished as@happyvertical/payments.The
PaymentBackendinterface must provide:x402Capable: boolean, typical confirmation latency,supportsRefunds: boolean, settlement-shape flag (address-based vs URL-based — fiat backends return checkout URLs, not crypto addresses)createPaymentOption(input)— given a quote id, USD amount, expiry, return aPaymentOption(unique pay-to address or checkout URL, native amount, optional memo)watchPayment(input)— emit/poll for payment status against a previously-created optiongetStatus(quoteId, payTo)— idempotent "what is the state of this quote's option"verifyX402Proof?(input)— for x402-capable backends only; given anX-Paymentheader and a quote, verify on-chainsendPayout(input)— send native-currency payout to a destination address (or initiate via the backend's payout API for fiat)Conformance tests: a shared test suite that any adapter can run against to prove it satisfies the interface.
Acceptance criteria
packages/paymentsdirectory with properpackage.json,tsconfig, build configPaymentBackendinterface and associated types exported@happyvertical/paymentsBlocked by
None — can start immediately