Checkout (Beta)

beta voltage checkout is currently in beta availability, supported payment methods, configuration, and interfaces may change confirm that the current beta fits your implementation before launching it in production voltage checkout gives merchants a hosted lightning payment page without requiring them to build and operate the payment interface themselves how checkout works the merchant server creates a checkout session for an order voltage returns a hosted checkout url for that session the merchant browser opens the hosted checkout, preferably through the voltage checkout javascript sdk overlay the customer pays the lightning invoice the hosted page reports customer facing payment status the merchant server verifies the payment before fulfilling the order the browser experience helps the customer complete payment, but it is not the authoritative payment record order fulfilment must depend on server side verification current beta scope the currently verified checkout path uses a compatible mainnet wallet a fixed checkout amount a bolt11 lightning payment a hosted voltage checkout page the javascript sdk overlay as the preferred browser integration environment level browser origin controls server side reconciliation using the checkout session id and payment id for a usd priced checkout, use a usd backed wallet with the required line of credit do not promise other payment kinds or flexible amount flows unless they are enabled and tested for the merchant before you integrate prepare a voltage organization and environment a compatible wallet in that environment an environment api key with the required write access the organization, environment, and wallet identifiers a merchant backend that can protect the api key the exact browser origins that will open checkout configure each environment separately use an exact origin allowlist for production browser integrations and keep production configuration separate from testing amount encoding examples all identifiers, prices, timestamps, and order details in the examples below are placeholders never place an environment api key or checkout token in browser code use integer values in the smallest supported unit customer price request value usd 1 00 { "currency" "usd", "amount" 100 } usd 25 00 { "currency" "usd", "amount" 2500 } 1 satoshi { "currency" "btc", "amount" 1000 } do not send decimal major unit values in amount amount example session payload create the checkout session from merchant server code, not from browser code generate a new session uuid and an expiry time for every new checkout function buildcheckoutsession(walletid) { return { id crypto randomuuid(), wallet id walletid, payment kind 'bolt11', amount { currency 'usd', amount 2500 }, expires at new date(date now() + 15 60 1000) toisostring(), description 'order 1001', metadata { order id '1001' } }; } choose an integration path javascript sdk overlay use the sdk overlay for the primary and best tested customer experience the merchant server creates the session and sends only the returned checkout url to browser code the sdk opens the hosted checkout over the merchant page and reports customer facing completion, expiration, failure, and close events example browser integration the /api/checkout route below represents an endpoint on your merchant server it creates the checkout session without exposing your voltage api key to the browser async function startcheckout(productid) { const response = await fetch('/api/checkout', { method 'post', headers { 'content type' 'application/json' }, body json stringify({ product id productid }) }); if (!response ok) { throw new error('unable to create checkout session'); } const checkout = await response json(); window\ voltagecheckout open({ checkouturl checkout checkout url, theme 'dark', title 'pay example store', oncomplete(payload) { console info('checkout completed; verify payment on the server', payload session id); }, onexpired() { console info('checkout expired'); }, onfailed() { console info('checkout failed'); }, onclose() { console info('checkout closed'); } }); } hosted redirect use a hosted redirect only when the merchant cannot use the sdk overlay validate the merchant's navigation, order status, return, and recovery flows before launch a browser redirect or callback must not be the only payment confirmation mechanism do not build a direct iframe integration by default use it only when the sdk cannot meet a verified requirement and the integration receives a separate security review security and payment verification create checkout sessions from the merchant server, never from browser code keep the environment api key out of javascript, html, mobile applications, urls, logs, screenshots, analytics, and support tickets use the complete checkout url returned by voltage; do not construct it from identifiers or move its token into a query parameter treat the checkout token as a bearer credential and redact it from logs, analytics, screenshots, and error reports treat sdk callbacks as user interface signals only verify payment through a trusted server side payments api or webhook flow before fulfilment bind the merchant order to both the checkout session id and the generated payment id make fulfilment idempotent so repeated status delivery cannot duplicate an order action payment lifecycle a checkout can move through generating, receiving, completed, failed, or expired states the customer may also close or refresh the browser before a terminal state appears give the customer a merchant controlled order status path before creating another payment, verify whether the original order was paid example completion payload { "status" "completed", "session id" "11111111 1111 4111 8111 111111111111", "amount" { "currency" "usd", "amount" 2500, "unit" "cents" }, "btc amount" { "currency" "btc", "amount" 153790000, "unit" "msats" } } launch readiness before launch, confirm the production wallet can receive the intended currency the production origin policy uses an exact allowlist the merchant stores the checkout session id and payment id with the order the integration handles completed, failed, expired, and customer dismissed states the checkout token is redacted from logs and analytics server side payment verification controls fulfilment the overlay or redirect flow has been tested on both desktop and mobile the merchant has a recovery path for refresh, tab closure, and interrupted network sessions technical specification ask your voltage customer success team for the current internal specification documentation for your checkout solution use that specification for field level integration details, current interfaces, and implementation requirements while checkout remains in beta related guides wallet setup guide docid\ alpqa ayg179ccwgf2ija staging environment docid\ ukhb7 3ektubbv hblw1t payments access docid\ txpojpm5pxe1ksxjbt2an receiving docid uq9knquoc9sgq0kuogmy webhooks docid\ pdeh 4et9aqawca5q91na voltage payments api docid\ ee9anjjlombmff1vx4ujw