Usalo senza il pulsante di acquisto
Il pulsante di acquisto è uno strato di comodità. Sotto, Coin Moebius è un webhook in affitto più qualche endpoint JSON. Se preferisci costruire la tua interfaccia, gestire il tuo flusso di checkout, o collegare Coin Moebius a qualcosa che il pulsante non può gestire (abbonamenti Square o Authorize.Net, un form di pagamento personalizzato, uno script lato server, un'app mobile), ogni endpoint che il pulsante usa è richiamabile da qualsiasi cosa. Nessuna modifica al codice dal nostro lato.
Autenticare le chiamate dal backend
Le chiamate che fai dal tuo server possono portare l'API key del tuo progetto come bearer token. Crea una chiave nella dashboard, sotto le API key del tuo progetto (inizia con cmk_), e inviala nell'header Authorization:
Authorization: Bearer cmk_live_xxxxxxxxxxxxxxxxxxxxxxxxLa chiave è legata a un solo progetto, e le chiamate autenticate ottengono un rate limit più alto di quelle anonime. Il pulsante di acquisto in sé è pubblico e non richiede chiave. Tieni la tua chiave sul tuo server. Non metterla mai nel browser o in altro codice lato client.
Questi endpoint vivono tutti sotto l'URL del tuo progetto. In produzione quella base è https://api.coinmoebius.com. L'URL completo per ciascuno è mostrato qui sotto (sostituisci le parti {…} con i tuoi valori).
| Endpoint | Cosa fa |
|---|---|
POST https://api.coinmoebius.com/api/checkout/{provider}/{projectId} | Avvia un checkout. POST { productId, metadata }; ricevi indietro ciò che serve al provider (un URL di reindirizzamento per Stripe, un URL di approvazione per PayPal, un token per Authorize.Net Accept Hosted). Renderizzalo come vuoi. |
POST https://api.coinmoebius.com/webhook/{provider}/{projectId} | Il provider pubblica qui. Verifichiamo la firma, normalizziamo l'evento, lo conserviamo, contiamo la quota. Punta il webhook del provider su questo URL sia che il checkout originale provenga dal nostro pulsante sia dalla tua integrazione. |
GET https://api.coinmoebius.com/status/{projectId}/{txId} | Interroga lo stato attuale di un pagamento o di un abbonamento. Restituisce la stessa forma normalizzata che ottiene il pulsante di acquisto. |
POST https://api.coinmoebius.com/api/subscriptions/{projectId}/{subscriptionId}/portal-url | Genera un URL di portale ospitato dal provider perché il cliente gestisca il proprio abbonamento. Funziona per ogni provider che ha un portale. |
Identifica il cliente nel tuo sistema passando metadata.customerRef nella chiamata di checkout. Si propaga attraverso il provider e ritorno su ogni evento webhook, così puoi unire i registri di Coin Moebius al tuo database utenti senza che noi conserviamo nulla sul cliente.
Perché qualcuno usa questo percorso: chi costruisce un sito statico e vuole scrivere il proprio pulsante per abbinarlo al design del sito e ha solo bisogno che il webhook sia gestito. Uno sviluppatore che vuole saltare del tutto il pulsante e chiamare l'API dal proprio server. Un commerciante che vuole gestire abbonamenti Square o Authorize.Net ed è a suo agio nel collegare da sé la raccolta della carta. Il pulsante è un punto di partenza. L'API è il prodotto vero.
Ascoltare gli eventi del cliente
L'elemento emette tre eventi del browser. Ascolta con addEventListener sull'elemento (o su document, gli eventi propagano). Tutti gli eventi sono annullabili, chiamare event.preventDefault() ferma il flusso predefinito.
| Evento | Quando si attiva | Payload di dettaglio |
|---|---|---|
cm-load-providers | Il modale del selettore sta per chiedere all'API la lista dei provider configurati su questo progetto. | Vuoto. |
cm-checkout-started | Il cliente ha scelto un provider e Coin Moebius sta per creare una sessione di checkout (Stripe / NOWPayments) o generare un codice di riferimento (manuale). | { provider: 'stripe' | 'nowpayments' | 'manual', ... } |
cm-error | Qualcosa è fallito: errore di rete, fallimento di firma, nessun provider configurato. | { error: Error } |
document.addEventListener('cm-error', (event) => {
console.error('Coin Moebius:', event.detail.error);
// Show your own error UI, send to your analytics, etc.
});Non c'è alcun evento cm-success nel browser del cliente. Quando il pagamento si completa davvero, il cliente è stato reindirizzato al checkout ospitato del provider (Stripe Checkout, pagina di fattura NOWPayments). Tornano al tuo sito tramite il success_url che hai configurato (vedi la prossima sezione), e il tuo server viene a sapere del pagamento dalla dashboard o interrogando l'endpoint /status.
Polling dal tuo backend
Per una fonte di verità lato server, interroga GET /status/:projectId/:txId dal tuo backend. La forma della risposta:
{
"status": "succeeded",
"amount": 29.99,
"currency": "USD",
"isTest": false,
"createdAt": "2026-05-14T01:04:21.000Z",
"updatedAt": "2026-05-14T01:04:21.000Z"
}I valori di stato seguono lo stesso enum della dashboard (vedi Stati delle transazioni). L'endpoint non è autenticato ma è limitato a 60 richieste / minuto per IP. L'id di transazione che passi è quello restituito dall'SDK nell'evento cm-checkout-started o quello mostrato nella colonna Riferimento della dashboard.
Uno schema tipico: quando la pagina del tuo success_url si carica, avvia un lavoro backend che interroga /status/:projectId/:txId ogni 15 secondi finché non vede succeeded (o failed / un timeout), poi evadi l'ordine.