Cosa puoi ricevere
Lightning riceve BTC, non stablecoin o trasferimenti on-chain. Ogni richiesta ha importo, hash e scadenza propri. Il cliente paga l'intera fattura Lightning.
Pagamenti Bitcoin on-chainConfigura il tuo negozio
In Impostazioni → Connessioni di rete aggiungi LND via HTTPS o NWC via WSS, poi attivalo nel negozio. Servono endpoint pubblici; indirizzi solo LAN o Tor non funzionano direttamente.
Credenziali e custodia
Usa credenziali di ricezione limitate, mai macaroon LND admin o di spesa. NWC descrive la connessione, non la custodia: controlla chi conserva le chiavi.
Dove arrivano i pagamenti
Il QR contiene una fattura BOLT11, non un indirizzo Bitcoin. Non pagarla on-chain. Se scade, crea una nuova fattura: non basta estendere la scadenza.
Quando è completo il pagamento?
Wholly Crypto verifica il saldo ricevuto segnalato dal wallet. Fatture aperte o HTLC bloccati non sono pagamenti. Lightning non ha conferme di blocco o link pubblici alla transazione.
Sposta i fondi quando vuoi
Usa wallet o nodo esterno per invii, liquidità e backup. Gli sweep on-chain non spostano Lightning. L'export del wallet di progetto non salva quello esterno.
Guida al wallet LightningProblemi con i pagamenti
Se manca una rotta, controlla liquidità in entrata, wallet e scadenza. Un'API sana non garantisce la rotta. Se l'esito è incerto, verifica il pagamento prima di chiedere un nuovo tentativo.
Commissioni e verifica
La commissione predefinita è l'1% del valore fiat della fattura, pagata con crediti separati. Vale la tua tariffa assegnata. Rete e server hanno costi a parte.
I provider pubblici possono avere guasti o limiti. Una transazione inviata o un reindirizzamento non provano il pagamento. Usa lo stato verificato della fattura e le notifiche firmate.
Crediti di elaborazione API, IPN e webhookCalcolatore di cambio
Converti un importo
È una stima, non una quotazione di pagamento. Commissioni di rete, dell'exchange e spread del commerciante non sono inclusi.
Da dove provengono i tassi?
Le stime crypto usano i prezzi pubblici Kraken in cache, con Binance dove disponibile. Alcuni prezzi Binance usano USDT come riferimento USD. I tassi fiat provengono da Frankfurter e sono tassi di riferimento giornalieri, non quotazioni di trading in tempo reale.
L'istantanea si aggiorna automaticamente. Controlla le date delle fonti sotto il risultato. L'importo inserito resta nel tuo browser. La presenza di un asset non garantisce il supporto ai pagamenti.
Kraken · Binance · Frankfurter · Nomi e icone degli asset: CoinGecko
Crea una fattura con l'API
Esegui gli esempi sul tuo server. Sostituisci host API e ID di progetto e negozio. Tieni privata la credenziale. Gli importi sono stringhe decimali.
Attiva prima il metodo nel negozio. La selezione filtra i metodi attivi, non aggiunge asset. Senza corrispondenze valgono i predefiniti. Controlla i metodi restituiti prima di aprire il checkout.
: "${WHOLLY_TOKEN:?Set WHOLLY_TOKEN to your server-side API token}"
# Keep this key and the exact body for retries; use a new key for each new invoice.
curl --fail-with-body --max-time 30 \
--request POST \
--url "https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices" \
--header "Authorization: Bearer $WHOLLY_TOKEN" \
--header 'Idempotency-Key: order-1042-attempt-1' \
--header 'Content-Type: application/json' \
--data-raw '{
"amount": "25.00",
"currency": "EUR",
"order_id": "order-1042",
"payment_methods": [
{
"chain_slug": "bitcoin",
"payment_rail": "lightning"
}
]
}'// Node.js 18+ · run on your server, never in browser code.
const token = process.env.WHOLLY_TOKEN;
if (!token) throw new Error("Set WHOLLY_TOKEN");
// Keep this key and the exact body for retries; use a new key for each new invoice.
const body = `{
"amount": "25.00",
"currency": "EUR",
"order_id": "order-1042",
"payment_methods": [
{
"chain_slug": "bitcoin",
"payment_rail": "lightning"
}
]
}`;
const response = await fetch("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices", {
method: "POST",
headers: {
"Authorization": `Bearer ${token}`,
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
},
body,
redirect: "error",
signal: AbortSignal.timeout(30000)
});
if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
console.log(await response.json());<?php
// PHP 8+ with the cURL extension; run on your server.
$token = getenv('WHOLLY_TOKEN');
if (!$token) { throw new RuntimeException('Set WHOLLY_TOKEN'); }
// Keep this key and the exact body for retries; use a new key for each new invoice.
$body = <<<'JSON'
{
"amount": "25.00",
"currency": "EUR",
"order_id": "order-1042",
"payment_methods": [
{
"chain_slug": "bitcoin",
"payment_rail": "lightning"
}
]
}
JSON;
$ch = curl_init("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices");
curl_setopt_array($ch, [
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_RETURNTRANSFER => true,
CURLOPT_FOLLOWLOCATION => false,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . $token, "Idempotency-Key: order-1042-attempt-1", "Content-Type: application/json"],
CURLOPT_POSTFIELDS => $body,
]);
$response = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_HTTP_CODE);
if ($response === false) { throw new RuntimeException(curl_error($ch)); }
curl_close($ch);
if ($status < 200 || $status >= 300) { throw new RuntimeException("HTTP $status: $response"); }
print_r(json_decode($response, true, 512, JSON_THROW_ON_ERROR));# Python 3 · standard library; run on your server.
import json
import os
from urllib.request import Request, build_opener, HTTPRedirectHandler
class NoRedirect(HTTPRedirectHandler):
def redirect_request(self, req, fp, code, msg, headers, newurl):
return None
# Keep this key and the exact body for retries; use a new key for each new invoice.
headers = {
"Idempotency-Key": "order-1042-attempt-1",
"Content-Type": "application/json"
}
headers["Authorization"] = "Bearer " + os.environ["WHOLLY_TOKEN"]
body = """{
"amount": "25.00",
"currency": "EUR",
"order_id": "order-1042",
"payment_methods": [
{
"chain_slug": "bitcoin",
"payment_rail": "lightning"
}
]
}""".encode("utf-8")
request = Request("https://api.example.com/v1/projects/YOUR_PROJECT_ID/stores/YOUR_STORE_ID/invoices",
method="POST", headers=headers, data=body)
# Non-2xx responses raise HTTPError. Do not retry writes with a new key.
with build_opener(NoRedirect()).open(request, timeout=30) as response:
print(json.load(response))