Cosa ti serve
| Campo | Cosa fa |
|---|---|
| Access token | Ci permette di chiamare Square per creare il link di checkout. Segreta. |
| Webhook signature key | Conferma che un webhook provenga davvero da Square. Segreta. |
| Location ID | La sede Square che riceve il pagamento. Imposta la valuta. |
| URL di conferma / URL di annullamento | Dove arriva il cliente dopo aver pagato o essersi tirato indietro. |
Perché chiediamo ogni campo
Access token
Autorizza la creazione del link di checkout, così l'addebito passa per il tuo account.
Webhook signature key
Dimostra che un webhook in arrivo provenga davvero da Square, così nessuno può falsificare un evento "pagato". È un valore separato dall'access token.
Location ID
Dice a Square quale sede riceve il denaro, e imposta la valuta del checkout. Non segreto.
URL di conferma e annullamento
Impostazioni semplici: dove arriva il cliente dopo aver pagato o essersi tirato indietro. Non segrete.
Configurazione
- Apri la dashboard Square Developer
Accedi su developer.squareup.com. Ogni applicazione ha le proprie credenziali, e insieme ad essa viene creato gratuitamente un Sandbox per i test. Questa guida segue il Sandbox; il flusso Live è identico, basta girare il toggle Sandbox / Production e usare le credenziali di produzione. Per creare una nuova app, fai clic sul riquadro + nella schermata Applications.
Square Developer → Applications - Dai un nome alla tua applicazione
Assegna all'applicazione un nome che riconoscerai (ad esempio "Coin Moebius"), poi fai clic su Next.
Square → Name your application - Copia il tuo access token
Apri l'app e vai su Credentials. Conferma che il toggle Sandbox / Production in cima corrisponda all'ambiente che stai configurando. Fai clic sull'icona di copia accanto all'Access token e mettilo da parte.
Square → Credentials L'access token è segreto, trattalo come una password. Sandbox e Production hanno token separati, quindi non mescolarli.
- Copia il tuo Location ID
Nel menu a sinistra, apri Locations. Copia il Location ID della sede che deve ricevere i pagamenti. Imposta la valuta del checkout, quindi scegli quella la cui valuta vuoi addebitare.
Square → Locations - Apri Webhooks → Subscriptions
Square chiama "subscription" un endpoint webhook. Nel menu a sinistra, espandi Webhooks, apri Subscriptions e fai clic su Add subscription.
Square → Webhooks → Subscriptions → Add subscription - Aggiungi la sottoscrizione e seleziona gli eventi
Dagli un nome (ad esempio "coin-moebius"). In Notification URL, incolla l'indirizzo del webhook Square del tuo progetto (sotto). Poi, sotto Events, cerca e spunta gli eventi che Coin Moebius ascolta, e fai clic su Save.
- Pagamenti una tantum: payment.created, payment.updated, refund.created, refund.updated, dispute.created, dispute.state.updated.
- Abbonamenti (solo se li vendi): subscription.created, subscription.updated, subscription.canceled, subscription.deactivated, invoice.payment_made, invoice.scheduled_charge_failed. Se non fatturi su base ricorrente, salta questi.
https://api.coinmoebius.com/webhook/square/<your project id>Square → Add a webhook subscription Il tuo id progetto si trova sotto il nome del progetto nella dashboard di Coin Moebius; inseriscilo nell'indirizzo sopra. Gli eventi extra sono innocui, ignoriamo tutto ciò che non usiamo. La card del provider collegato (ultimo passaggio) mostra lo stesso URL come riferimento.
- Apri la sottoscrizione appena creata
Square salva la sottoscrizione e la elenca sotto Webhooks con stato Enabled. Fai clic sul suo nome per aprire il pannello dei dettagli dove si trova la signing key.
Square → Webhooks → la tua sottoscrizione (Enabled) - Copia la Signature key
Nel pannello Properties della sottoscrizione, fai clic sull'icona di copia accanto a Signature key. Questo è il valore che Coin Moebius usa per confermare che ogni webhook provenga davvero da Square. Esiste solo dopo che la sottoscrizione è stata creata, ecco perché il webhook è venuto prima del passaggio di collegamento.
Square → la tua sottoscrizione → Signature key - Torna in Coin Moebius: Aggiungi provider → Square
Nel tuo progetto, apri la scheda Provider, fai clic su Aggiungi provider, scegli Collega un servizio e seleziona Square. Imposta il tuo URL di conferma e URL di annullamento. Nella scheda Live, incolla il tuo Access token, Webhook signature key e Location ID, poi fai clic su Salva. Vuoi configurare prima con credenziali sandbox? Incollale invece nella scheda Test, poi aggiungi le credenziali live in seguito da Modifica.
Coin Moebius → Aggiungi provider → Square - Sei collegato
Square ora appare nella scheda Provider con la data di collegamento. La card mostra lo stesso URL di webhook che hai incollato in Square, più Modifica e Scollega. Usa il toggle Modalità test per completare un ordine sandbox da capo a fondo prima di andare live.
Coin Moebius → Provider → Square (collegato) Le carte sandbox non addebitano mai una carta reale. Usa la carta 4111 1111 1111 1111, CVV 111, qualsiasi scadenza futura, qualsiasi codice postale valido (ad esempio 94103).
Dopo aver collegato
Esegui un pagamento di prova prima di andare in produzione:
- Crea un prodotto e imposta il suo Ambiente su Testing. Questo esegue il prodotto sulle tue credenziali sandbox, così puoi piazzare un ordine completo senza muovere denaro. (Se hai saltato il set sandbox, un prodotto in Testing ricade su live, quindi aggiungilo prima.)
- Metti il pulsante di acquisto su una pagina (un file HTML locale va bene) puntato sul tuo progetto.
- Completa il checkout con la carta di test sandbox di quelle sopra.
- Apri la scheda Transazioni. Appare una nuova riga, etichettata Testing. Quando il suo stato raggiunge succeeded, le tue credenziali e il webhook funzionano entrambi da capo a fondo.
Cambia l'Ambiente del prodotto su Live quando sei pronto per i pagamenti reali.
Risoluzione dei problemi
Inizia da Verifica. Nella dashboard, fai clic su Verifica (o Verifica credenziali di test) per controllare il tuo access token e la sede.
La verifica fallisce.
Ricopia l'access token e il Location ID. Production e Sandbox hanno token separati, quindi non mescolarli.
La verifica della firma fallisce, o l'ordine resta in sospeso.
Square firma sull'esatto URL di notifica più il corpo. L'URL che registri in Square deve corrispondere al tuo URL di webhook carattere per carattere, senza slash finale e senza query string extra. Poi ricopia la signature key da quello stesso endpoint.
Conferma da capo a fondo.
Square Developer Console → Webhooks → la tua sottoscrizione → Send Test Event, poi guarda l'ordine aggiornarsi.
Buono a sapersi
La valuta segue la sede. Il checkout addebita nella valuta della sede il cui id fornisci.
Ruotare i secret. Ruota l'access token o la signature key quando vuoi, poi incolla il nuovo valore. I campi segreti restano vuoti in modifica.
Domande? Join our Discord