integrate-onramp

name	integrate-onramp
description	Implement a ramp provider's fiat→crypto on-ramp quote — createOnrampQuote → PaymentRampQuote — and wire the handler dispatch that resolves DB state. Use when opening a PR against apps/sdp-api to add on-ramp support for a ramp provider.

Integrate on-ramp

On-ramp = a counterparty buys crypto with fiat, delivered to an SDP-known wallet. The active flow is the quote: you implement createOnrampQuote on your provider and add a case to the quote dispatch. (executeOnramp exists on the interface but isn't currently exercised — skip it for now; the quote returns the payment instructions the user acts on.)

createOnrampQuote is optional on RampProvider — implement it only if your provider has a lockable quote step.

Canonical example: createOnrampQuote in lib/ramps/providers/lightspark/client.ts + the DB helpers in routes/payments/handlers/ramps/lightspark.ts.

Contract

Input RampOnrampQuoteInput (lib/ramps/types.ts): { cryptoToken, fiatCurrency?, fiatAmount, destinationWalletAddress, externalCustomerId, customerId?, redirectUrl?, bvnkCompliance? }. The handler pre-resolves customerId / externalCustomerId from the DB — your method never reads the database.

PaymentRampQuote is a discriminated union on deliveryMode (packages/sdp-types/src/payments.ts) — return the arm that matches your product:

• deliveryMode: "manual_instructions" — return paymentInstructions (bank/wire or on-chain funding details). Lightspark, BVNK.
• deliveryMode: "hosted" — return a hostedUrl the client renders (widget/redirect). MoonPay.

Use rampId("ramp") for ids; set id to the upstream quote id so the webhook can match the transfer later (integrate-webhook).

Handler wiring (the DB side)

Add a case "<id>" to the on-ramp quote dispatch in routes/payments/handlers/ramps.ts. The handler owns all DB work:

• resolves the counterparty + destination wallet,
• ensures any provider-side customer/account exists (DB-touching ensure* helpers live in routes/payments/handlers/ramps/<id>.ts, like ensureLightsparkCustomer),
• calls your HTTP-only createOnrampQuote with pre-resolved inputs,
• persists the transfer via persistRampQuoteTransfer (dedups by (provider, providerReference); rampQuoteTransferStatus maps a manual_instructions + pending quote to awaiting_payment).

Route: POST /v1/ramps/onramp/quote, gated by assertRampProviderAvailable + payments:write / wallets:read.

Variety

Provider	deliveryMode	On-ramp quote shape
Lightspark	manual_instructions	REALTIME_FUNDING quote; funding paymentInstructions
BVNK	manual_instructions	bank pay-in instructions built from the provisioned rule
MoonPay	hosted	signed buy.moonpay.com widget hostedUrl

Gating — throw, don't fallback

A provider that needs provisioning must fail loud when it's missing: Lightspark throws if customerId is absent; BVNK throws counterpartyNotProvisioned if the customer isn't verified or the rule isn't ready. Getting the counterparty to a ready state is counterparty-requirements — never substitute a default.

Rules + verify

Shared rules live in integrate-ramp-provider. Hot here:

• No fallbacks — missing customer/account/instructions throws; never default them.
• HTTP in the provider; DB (counterparty, wallet, customer, transfer row) in the handler.
• deliveryMode arms are a real discriminated union — return exactly one arm's fields; no any.
• Verify with tsc --noEmit + biome check; mock fetch in providers/<id>/client.test.ts (provider calls 503 without creds in the environment).