Ramp providers
MoonPay, Lightspark, BVNK, MoneyGram, Coinbase, Mural, and Stripe — capability matrix, configuration, and per-provider notes.
SDP currently integrates seven ramp providers. They are configured at the organization level via environment variables on the SDP API deployment; the same provider string on POST /v1/payments/ramps/onramp/quote and POST /v1/payments/ramps/offramp/quote selects between them.
Sandbox vs production selection
The sandbox/production mode is chosen per request, not at deployment time:
- Non-production SDP deployments (
ENVIRONMENT !== "production") always use sandbox credentials. - In production deployments, the calling API key's environment picks the mode —
sk_test_keys use sandbox,sk_live_use production.
Configure both credential pairs for any provider you want to expose to test and live traffic on the same deployment — MoonPay, Lightspark, BVNK, and Mural read separate sandbox and production credentials this way. Coinbase and Stripe use a single credential pair regardless of the resolved mode (see their sections below); MoneyGram only has sandbox credentials today.
Capability matrix
| Provider | Onramp | Offramp | Sandbox | Delivery mode | Notes |
|---|---|---|---|---|---|
| MoonPay | ✓ | ✓ | ✓ | hosted | Sandbox vs production is selected per request (see Sandbox vs production). |
| Lightspark | ✓ | ✓ | ✓ | manual_instructions | Grid API. Same per-request sandbox/production selection as MoonPay. |
| BVNK | ✓ | ✓ | ✓ | manual_instructions | Hawk auth. Compliance party details are built from the Counterparty record, not passed on the request. |
| MoneyGram | ✓ | ✓ | ✓ | session_widget | Sandbox-only pilot integration — there is no production credential path yet. |
| Coinbase | ✓ (sandbox only) | ✗ | ✓ | hosted | Rate estimates work in production; order creation is sandbox-only. Onramp only. |
| Mural | ✓ | ✗ (estimate only) | ✓ | manual_instructions | Off-ramp rate estimate works; off-ramp quote creation is not implemented yet. |
| Stripe | ✓ | ✗ | ✓ (shared credentials) | session_widget | No separate sandbox credentials — supply a Stripe test-mode secret key. Onramp only. |
MoonPay
| Variable | Required | Notes |
|---|---|---|
MOONPAY_API_KEY | conditional | Production API key. Required when the request resolves to production. |
MOONPAY_SECRET_KEY | conditional | Production secret used to sign onramp / offramp URLs. Paired with MOONPAY_API_KEY. |
MOONPAY_SANDBOX_API_KEY | conditional | Sandbox API key. Required when the request resolves to sandbox. |
MOONPAY_SANDBOX_SECRET_KEY | conditional | Sandbox secret. Paired with MOONPAY_SANDBOX_API_KEY. |
MOONPAY_ONRAMP_URL | no | Override the onramp host. Defaults to MoonPay's standard URLs; the sandbox/production choice follows the per-request rule. |
MOONPAY_OFFRAMP_URL | no | Same idea for offramp. |
MoonPay normalizes token symbols internally — USDC is mapped to usdc_sol, USDT to usdt_sol — so you pass plain symbols on the request and SDP handles the mapping.
Lightspark
| Variable | Required | Notes |
|---|---|---|
LIGHTSPARK_GRID_CLIENT_ID | conditional | Production Grid API client identifier. Required when the request resolves to production. |
LIGHTSPARK_GRID_CLIENT_SECRET | conditional | Production Grid API client secret. |
LIGHTSPARK_GRID_SANDBOX_CLIENT_ID | conditional | Sandbox Grid API client identifier. Required when the request resolves to sandbox. |
LIGHTSPARK_GRID_SANDBOX_CLIENT_SECRET | conditional | Sandbox Grid API client secret. |
Lightspark is integrated against the Grid API (https://api.lightspark.com/grid/2025-10-13); the sandbox/production choice follows the per-request rule. destinationWallet / sourceWallet are your own custody wallet, same as every other provider — Lightspark's customer id and payout account are resolved server-side from the counterparty's Provider Requirements, not passed on the quote request.
Counterparties no longer store identity or email fields. Existing Lightspark customers continue to resolve from provider data, but first-time customer creation currently fails with a clear error until just-in-time identity collection is connected.
Lightspark quotes always return deliveryMode: "manual_instructions" — the response carries funding instructions to display to the payer, not a redirect URL.
BVNK
| Variable | Required | Notes |
|---|---|---|
BVNK_WALLET_ID | conditional | Production BVNK-side wallet used for settlement. |
BVNK_HAWK_AUTH_ID | conditional | Production Hawk auth id. Paired with BVNK_HAWK_SECRET_KEY. |
BVNK_HAWK_SECRET_KEY | conditional | Production Hawk secret key. |
BVNK_SANDBOX_WALLET_ID | conditional | Sandbox BVNK wallet. Required when the request resolves to sandbox. |
BVNK_SANDBOX_HAWK_AUTH_ID | conditional | Sandbox Hawk auth id. |
BVNK_SANDBOX_HAWK_SECRET_KEY | conditional | Sandbox Hawk secret key. |
BVNK_API_BASE_URL | no | Override the default BVNK host. Defaults to https://api.bvnk.com for production and https://api.sandbox.bvnk.com for sandbox; the sandbox/production choice follows the per-request rule. |
BVNK uses Hawk authentication. Bearer-token auth is not currently supported.
BVNK is a travel-rule / compliance-sharing provider and requires party details such as name and address. Counterparties no longer store those fields, so customer creation, payment-rule creation, and off-ramp compliance payloads currently fail with a clear error at the pending just-in-time collection seam.
BVNK quotes always return deliveryMode: "manual_instructions" — the response carries funding-account details to display to the payer.
MoneyGram
| Variable | Required | Notes |
|---|---|---|
MONEYGRAM_SANDBOX_PUBLIC_KEY | conditional | Sandbox public key, sent as x-api-key on the rail-discovery (currency list) call. |
MONEYGRAM_SANDBOX_SECRET_KEY | conditional | Sandbox secret key, sent as x-api-key on estimate, quote, and session calls. |
MoneyGram is a sandbox-only pilot integration today — the client always calls MoneyGram's sandbox host and throws if a request resolves to production; there is no production credential pair to configure yet.
MoneyGram quotes always return deliveryMode: "session_widget": both onramp and offramp create a session against the same endpoint and return a widgetUrl (with mode=on-ramp or mode=off-ramp) plus a short-lived sessionToken to mount. It requires no Provider Requirements collection — every counterparty is treated as ready.
Coinbase
| Variable | Required | Notes |
|---|---|---|
COINBASE_CDP_API_KEY_ID | conditional | CDP Secret API Key id. Same key is used for sandbox and production — sandbox is flagged per-request, not by a separate credential. |
COINBASE_CDP_API_KEY_SECRET | conditional | CDP Secret API Key secret. Paired with COINBASE_CDP_API_KEY_ID; used to sign a per-request JWT. |
Coinbase is onramp-only — both estimateOfframp and createOfframpQuote reject with "Coinbase Onramp does not support off-ramp." Onramp quotes always return deliveryMode: "hosted": SDP creates a guest-checkout Apple Pay order and returns its payment link as hostedUrl.
Order creation (the quote step) is sandbox-only today — it requires buyer agreement and phone-OTP attestation timestamps that SDP's production flow does not yet collect, so a non-sandbox request fails loudly instead of sending a false attestation. Rate estimates have no such restriction and work in both modes. Coinbase also requires email and phone values; quote creation currently fails at the pending just-in-time collection seam.
Mural
| Variable | Required | Notes |
|---|---|---|
MURAL_PAY_API_KEY | conditional | Production API key for organization, account, and payin calls. |
MURAL_PAY_SANDBOX_API_KEY | conditional | Sandbox equivalent. Required when the request resolves to sandbox. |
MURAL_PAY_TRANSFER_API_KEY | conditional | Production transfer-scoped key, sent as a separate header on payout-execute calls. |
MURAL_PAY_SANDBOX_TRANSFER_API_KEY | conditional | Sandbox equivalent of the transfer key. |
Mural onramp is business-counterparty only (no individual entity type). A quote requires the counterparty's Mural organization and payin account already provisioned — through Provider Requirements onboarding (organization creation, terms-of-service acceptance, verification) — and returns deliveryMode: "manual_instructions" built from that account's active payin method; the quote step itself makes no live Mural call.
Existing Mural organizations continue to resolve from provider data. First-time organization creation currently fails with a clear error until just-in-time identity collection is connected.
Off-ramp rate estimates work today (a real call to Mural's fees endpoint), but off-ramp quote creation always throws — it is not implemented yet.
Stripe
| Variable | Required | Notes |
|---|---|---|
STRIPE_SECRET_KEY | conditional | Secret key, sent as the username on HTTP Basic auth. A single key serves both modes — use a sk_test_… key to sandbox it, sk_live_… for production. |
STRIPE_PUBLISHABLE_KEY | conditional | Publishable key, echoed back on the quote for the client to mount the onramp session. |
Stripe is onramp-only — both estimateOfframp and createOfframpQuote reject as unsupported. Onramp is also limited to usdc.solana and sol.solana as destination assets. Quotes always return deliveryMode: "session_widget": a clientSecret and publishableKey to mount Stripe's crypto onramp session, plus an optional redirectUrl.
Provider gating
Even when all seven providers' env vars are populated, an org can be restricted to a subset. This is Provider Availability: a provider must be configured for the deployment and either generally available or manually activated for the organization. SDP checks this on every ramp call — if the org lacks availability for the requested provider, the call returns an error. To activate or change provider availability for a deployment, see Provider onboarding.
Choosing a provider
| Need | Lean towards |
|---|---|
| Fastest sandbox iteration | MoonPay or BVNK. |
| Travel-rule / compliance party metadata | BVNK. |
| Lightning-aware fiat settlement | Lightspark. |
| Broadest payment-method coverage | MoonPay (corridor-dependent). |
| Business-entity onramp counterparties | Mural (its only supported entity type). |
| Widget/session-embedded onramp UI | MoneyGram or Stripe. |
| Onramp only, no off-ramp needed | Coinbase or Stripe. |
For self-hosted deployments where only a subset of providers will ever be configured, see Providers optional for self-hosted SDP — SDP supports running with any single provider active.
Related
- Ramps — onramp and offramp endpoints and request shape.
- Provider onboarding — activation flow.