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. |
buyer-email | No | Email address | Where to send a digital download. Set this when your site already knows the buyer, like a members area or a logged-in app, and the button will not ask them for an email. When it is not set, the button asks the buyer for one at checkout if the product is a download on a provider that does not return the email itself. We use the address only to send the download and then delete it. We never store it. |
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. |
disabled | No | Attributo presente/assente, o la proprietà el.disabled | Il contratto standard dei pulsanti: mentre presente, il pulsante appare attenuato e ignora i clic. Impostalo nel tuo HTML o cambia la proprietà dal codice proprio come faresti su un pulsante nativo. Separato da questo, il pulsante si blocca sempre mentre un clic viene elaborato per evitare che un doppio clic avvii due checkout; quel blocco interno non tocca mai un valore che hai impostato qui. |
spinner | No | true o false | Lo spinner di caricamento integrato mostrato sul pulsante durante l'avvio del checkout. Attivato per impostazione predefinita. Imposta spinner="false" per disattivarlo e gestire la tua UI di caricamento dagli eventi cm-busy e cm-idle. Disattivarlo non disattiva mai la protezione dal doppio clic. Lo spinner viene disegnato nel colore e nella dimensione del testo del pulsante, quindi corrisponde automaticamente al tuo stile; ristyizza con ::part(spinner) o sostituiscilo completamente con <span slot="spinner">il tuo markup</span>. |
Un solo metodo di pagamento? Nessun popup.
Quando un prodotto ha esattamente un metodo di pagamento abilitato e un prezzo fisso, il pulsante salta il selettore: il cliente clicca e accede direttamente a quel flusso di pagamento. I checkout ospitati si navigano immediatamente senza popup, mentre i pagamenti per posta, le monete in-page, e i prompt di download-email aprono comunque il popup al loro primo step. I prodotti con due o più metodi, e i prodotti a prezzo deciso dal cliente (mance, donazioni), mostrano sempre il selettore. Non c'è nulla da configurare; il pulsante decide dalle impostazioni del tuo prodotto, per ogni prodotto, così un prodotto con due metodi e uno con un metodo sulla stessa pagina fanno la cosa giusta. Se un checkout fallisce sul percorso diretto, una breve riga di errore appare sotto il pulsante (stilizzabile tramite ::part(error)).
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.