How a Lightning Network Payment Gateway Works

A Lightning payment gateway has one job: turn a scanned invoice into a completed, final sale in a few seconds, without asking the merchant to run any of the infrastructure that makes that possible. Most of what gets written about "Lightning gateways" focuses on the wallet side. The harder design questions live on the merchant side, and they are the ones a developer actually has to answer before shipping an integration.

What the gateway has to do

Underneath the QR code, a gateway is doing four things: generating a Lightning invoice for a specific amount, watching for the payment against that invoice, confirming settlement back to the calling application, and handing the merchant a completed transaction record. None of that is exotic. What makes gateways differ from each other is what happens around those four steps: how authentication works, where the funds actually land, and what the integration looks like when something goes wrong.

riverArk's answer is one API across three deployment shapes. The same invoice-creation call that powers a checkout page also powers an unattended kiosk or a machine-integrated terminal. A merchant does not choose between an e-commerce gateway and an unattended-retail gateway; they call the same endpoint either way, with a key scoped to their own account.

Authentication and integration shape

Auth is Bearer, one API key per integration. A machine integrator account can create a separate key per device, which keeps a single compromised key from exposing an entire fleet. There is no OAuth dance, no webhook secret negotiation before the first call succeeds, and no sandbox that behaves differently from production.

The public API and its documentation are live today, and self-serve signup connects a merchant's own settlement account directly. Machine integrator accounts with per-machine API key creation are also live and in production. The fastest way to answer "how much engineering work is this" is not to ask, it is to try it: a browser-based demo lets a developer drop in their own API key and transact against real Lightning in an afternoon, with nobody to schedule a call with first.

Where the money actually goes

This is usually the first question a developer's security or compliance reviewer asks, and it deserves a direct answer. riverArk is non-custodial. It never takes possession, custody, or control of a customer's or merchant's funds at any point. A Lightning payment moves directly from the payer's wallet to the merchant's own settlement account; riverArk facilitates the transaction as an agent of the payee rather than as a party the money passes through.

Practically, that means there is no float sitting anywhere between a sale and a merchant getting paid, and no separate withdrawal step to trigger. Settlement is instant and quoted in USD, so the merchant is not carrying Bitcoin price exposure on funds routed through the gateway.

Finality is a design constraint, not a footnote

Lightning payments are push-only. Once a payment clears, it is final. There is no authorization hold to reverse, no stored card credential to protect, and no chargeback window to build dispute tooling around. For a machine-initiated integration, that removes an entire category of fraud surface that a card-present or card-not-present integration has to design against from day one.

The same property cuts the other way for returns, and it deserves the same honesty a good API doc gives any hard limit. There is no native mechanism for reversing a completed Lightning payment, and riverArk has not shipped a refund flow yet. A merchant issuing a return today handles it outside the gateway, the same way they would for any other final-settlement tender. Anyone integrating for a use case with a meaningful return rate should plan around that constraint now rather than discover it at the first refund request.

Who can actually pay through it

The standing objection to any Bitcoin gateway is that too few customers hold bitcoin to make the integration worth building. That objection is getting weaker on its own. Cash App now lets a customer pay a Bitcoin invoice directly from their US dollar balance, scanning the same Lightning QR code a gateway like this one already generates, with no bitcoin holdings and no taxable event on their end. That puts roughly 59 million monthly Cash App users in a position to pay a Lightning invoice today, on hardware and habits they already have. A gateway built for Lightning does not need the payer to be a Bitcoin holder for the integration to make sense; it needs the payer to have a wallet capable of scanning a QR code, and that bar keeps getting lower.

What's live and what's still shipping

The public API, its documentation, self-serve merchant signup, and machine integrator accounts with API key creation are all live and in production today. A developer can build a working checkout or a machine integration against the public API right now.

What is still in development is the packaged, no-code layer that removes the need for a developer at all: listed plugins for existing e-commerce platforms, a web-based point of sale, platform-agnostic payment links, and a dedicated refund flow. None of that changes what the API can do today; it changes how much engineering effort a given merchant has to spend to use it.

Where to start

Read the docs, then try the demo before reading anything else about it. ark.riverark.io/demo is a browser-based test machine that takes a real API key and settles against real Lightning, and ark.riverark.io/docs has the endpoint reference. Signup and settlement-account connection happen at ark.riverark.io, and typically clears in one to two business days once the paperwork is complete.