Il pulsante di acquisto
Il pulsante di acquisto sono poche righe di HTML che incolli su qualunque pagina. Nessun framework, nessun passaggio di installazione dalla tua parte. Il pulsante viene mostrato al primo render; il selettore dei provider e gli SDK dei provider di pagamento si caricano su richiesta la prima volta che un cliente clicca. Funziona in qualsiasi sito o framework che renderizza HTML, inclusi i costruttori di siti no-code che permettono di incollare embed HTML.
Funzionamento confermato con: Angular, Hugo, Jekyll, HTML puro, Webflow (embed Custom Code), Carrd (elemento Embed), Framer (embed HTML), Squarespace (Code Block), WordPress (blocco Custom HTML), Ghost, siti Notion (widget di embed HTML). Se il tuo sito ti permette di incollare HTML su una pagina, il pulsante di acquisto funziona lì.
Riferimento agli attributi
| Attributo | Obbligatorio | Cosa accetta | Note |
|---|---|---|---|
endpoint | No | Stringa URL | Quasi sempre da omettere. Il pulsante rileva automaticamente la sua base API: https://api.coinmoebius.com in produzione, http://localhost:8787 su localhost. Impostalo solo come override per una configurazione insolita (ad esempio un proxy self-hosted davanti all'API). |
project-id | Sì | Stringa, con prefisso proj_ | Dalla pagina del tuo progetto nella dashboard. Si può esporre pubblicamente, è un identificatore, non una credenziale. |
product-id | Sì (in modalità strict) / Consigliato (in modalità ad-hoc) | Stringa, in qualsiasi formato tu scelga | Il tuo identificatore di prodotto interno. In modalità strict (il predefinito), è il modo in cui il worker recupera il prezzo dal tuo catalogo. In modalità ad-hoc, viene comunque inoltrato ai tuoi webhook in metadata.productId così puoi ricollegare le transazioni all'inventario. Vedi la sezione Modalità strict o ad-hoc qui sotto. |
amount | Solo in modalità ad-hoc | Numero decimale come stringa | Il prezzo in unità principali (ad esempio dollari, non centesimi). Deve essere positivo. Omettilo in modalità strict. Il worker legge il prezzo canonico dal tuo catalogo e ignora qualsiasi valore nell'HTML. Obbligatorio solo quando il progetto è in modalità ad-hoc e il product-id non è nel catalogo. |
currency | Solo in modalità ad-hoc | Codice ISO 4217 di tre lettere o il tuo nome di unità | USD, EUR, ecc. per i metodi carte / cripto. Il provider del pagamento per posta accetta qualsiasi stringa (ad esempio GBK) perché è il commerciante a liquidare la transazione. Stessa regola di amount: ometti in modalità strict, obbligatorio in modalità ad-hoc per i prodotti non nel catalogo. |
label | No | Stringa | Il testo del pulsante. Predefinito a Buy. Usalo per distinguere i pulsanti sulla stessa pagina. |
customer-ref | No | Stringa, in qualsiasi formato tu scelga | Un identificatore opaco per il cliente nel tuo sistema, come l'id di un utente connesso. Il pulsante lo inoltra al worker come metadata.customerRef, e il worker etichetta la transazione con esso. Più avanti puoi chiederti "quale dei miei utenti ha pagato?" usando il tuo id, senza che noi deteniamo alcun dato reale del cliente. Ometti per i checkout anonimi. |
theme | No | dark o light | Sceglie lo schema di colori integrato per il pulsante e la finestra insieme. Predefinito a dark. Imposta theme="light" per lo schema chiaro. Le tue variabili CSS prevalgono su entrambi. Vedi la guida allo stile. |
editable-amount | No | true o false | Quando è true, la finestra mostra un campo importo che il cliente compila (mance, donazioni, paga-quanto-vuoi). Predefinito a false, dove l'amount che imposti è fisso e non appare alcun campo. I pulsanti di pagamento restano disabilitati finché l'importo non è un numero positivo. |
Pulsanti multipli su una pagina
Lo script registra il pulsante una volta, poi un numero qualsiasi di istanze può essere mostrato su una pagina. Ogni istanza è indipendente. L'esempio qui sotto usa la modalità strict (il predefinito): nessun amount o currency nell'HTML, perché il worker recupera il prezzo da ogni prodotto nel tuo catalogo.
<coin-moebius-buy
project-id="proj_YOUR_ID"
product-id="t-shirt-medium"
label="T-shirt (medium)">
</coin-moebius-buy>
<coin-moebius-buy
project-id="proj_YOUR_ID"
product-id="mug-blue"
label="Blue mug">
</coin-moebius-buy>Se il tuo progetto è in modalità ad-hoc (widget di donazione, barattoli delle mance), ogni pulsante include anche amount e currency. Vedi Modalità strict o ad-hoc per il quadro completo.
Personalizzare il pulsante
Il pulsante di acquisto viene mostrato dentro uno Shadow DOM, il che significa che nessun CSS esistente della tua pagina arriva al suo interno. È voluto: mantiene il pulsante uguale su ogni sito e impedisce a una regola vagante * { box-sizing: ... } di rompere il modale del selettore. Lo personalizzi tramite due superfici dal tuo foglio di stile: proprietà CSS personalizzate per colori, font e forma, e selettori ::part() per tutto il resto. Niente JavaScript.
Ogni variabile e parte è documentata nella guida allo stile, con esempi dal vivo cliccabili e copiabili:
Apri la guida interattiva allo stile →
Gli URL di conferma e annullamento
Quando colleghi Stripe o NOWPayments nella scheda Provider della dashboard, imposti due URL:
- URL di conferma, dove arriva il cliente dopo un pagamento riuscito. Stripe e NOWPayments aggiungono un parametro di query (
?session_id=...per Stripe,?NP_id=...per NOWPayments) così la tua pagina di conferma può identificare quale transazione si è completata. La maggior parte dei siti statici mostra solo un messaggio generico "Grazie, il tuo pagamento è in elaborazione" e si affida alla dashboard come fonte di verità. - URL di annullamento, dove arriva il cliente se si tira indietro prima di pagare. Spesso lo stesso della tua pagina del carrello.
Entrambi gli URL sono configurati per provider nella dashboard, l'elemento non ha bisogno di conoscerli.