Payments / Onramp·Solana
Helio (MoonPay Commerce)
Solana-native crypto checkout, paylinks, and subscriptions (acquired by MoonPay and rebranded MoonPay Commerce). Accept SOL, USDC, and SPL tokens with embeddable widgets and a paylink API.
- 01Solana paylinks (one-click crypto checkout)
- 02SPL-token subscriptions / streams
- 03creator tipping and digital-goods sales
- 04embedded checkout widget
- 05low-fee on-chain settlement
- pnpm add @heliofi/checkout-react
- pnpm add @heliofi/sdk
| Variable | Scope | Description |
|---|---|---|
| NEXT_PUBLIC_HELIO_PAYLINK_ID | Client | Public id of the paylink created in the Helio dashboard. Drives the `<HelioCheckout>` widget configuration. |
| HELIO_API_KEY | Server | Server-side public API key from the Helio dashboard. Sent as `Authorization: Bearer ...`. |
| HELIO_API_SECRET | Server | Server-side secret key. Required as a query string `apiSecret=` parameter on management endpoints (paylink CRUD, subscription state). |
| HELIO_WEBHOOK_SHARED_TOKEN | Server | Shared token returned when you create a webhook via `POST /v1/webhook/paylink/transaction`; Helio includes it in webhook payloads so you can verify origin. |
Use Helio (MoonPay Commerce) for Solana checkout. Create a paylink in the dashboard or via `POST https://api.hel.io/v1/paylink/create` (auth: `Bearer HELIO_API_KEY` + `?apiSecret=...`) with the recipient wallet, currency (e.g. `USDC`), and price. On the client mount `<HelioCheckout config={{ paylinkId: NEXT_PUBLIC_HELIO_PAYLINK_ID, theme: { themeMode: 'dark' }, onSuccess: ({ transaction }) => ... }} />` from `@heliofi/checkout-react`. Register a webhook with `POST /v1/webhook/paylink/transaction { paylinkId, targetUrl, events: ['CREATED'] }`; the response returns a `sharedToken` that Helio echoes in every delivery — check it server-side before crediting. For subscriptions use the `/v1/subscription/...` endpoints which mint an SPL delegate authority on-chain.
- ⚑Helio is Solana-only — there is no EVM, Bitcoin, or Lightning path. Pair with another provider if you need multi-chain checkout.
- ⚑Authentication mixes a Bearer header (`HELIO_API_KEY`) with an `apiSecret` query param on most endpoints — sending one without the other returns a generic 401.
- ⚑Webhooks are not HMAC-signed; verification relies on the `sharedToken` echoed back in the body. Treat it like a bearer token (constant-time compare, never log) and rotate if exposed.
- ⚑Paylink prices set in fiat (USD) are quoted at create-time but settled at the on-chain spot rate at confirmation — communicate the conversion to users or expect support tickets on small differences.
- ⚑Subscriptions require the payer's wallet to grant an SPL token delegate authority; users who later revoke the delegate (via Phantom/Solflare) silently break renewals — handle `SUBSCRIPTION_RENEWAL_FAILED` events.
- ⚑Sandbox uses `https://api.dev.hel.io/v1` and a separate dashboard; live paylink ids do not resolve in sandbox and vice versa. Pair env across SDK + API calls.
- ⚑Solana network congestion can cause `transaction.status = 'PENDING'` for minutes — do not assume widget close == success; wait for the `CREATED` webhook.