Connetti SumUp a WebBlocks Commerce

Questa guida consente di far funzionare il primo pagamento sandbox SumUp senza addebitare denaro reale. E' scritto per proprietari di negozi e operatori del sito. Non è necessario creare un modulo di pagamento: i clienti entrano i dettagli della loro carta sulla pagina di pagamento ospitato di SumUp.

Cosa ti serve

  • an installato e abilitato il plugin WebBlocks Commerce
  • accesso alla dashboard di SumUp
  • autorizzazione per gestire le impostazioni commerciali o un amministratore di hosting che può aggiungere protezione la variabile d'ambiente esegue l'override
  • un indirizzo HTTPS pubblico per il negozio
  • circa dieci minuti per la configurazione iniziale del sandbox

I pagamenti Sandbox sono simulazioni. Non muovono soldi veri.

Prima di iniziare

WebBlocks Commerce accetta credenziali di pagamento tramite il modulo protetto Impostazioni Commerce. Il i valori vengono crittografati quando sono inattivi, i campi sono di sola scrittura e i segreti salvati non vengono mai più visualizzati. Non devono mai essere inseriti in una pagina CMS, in un blocco, in un prodotto o in un campo di impostazioni pubbliche.

Le variabili di ambiente gestite dall'hosting rimangono disponibili come sostituzioni facoltative. Non inviare l'API inserisci un'e-mail normale, una chat, uno screenshot o un ticket di supporto. Inseriscilo direttamente nell'area protetta modulo o utilizzare il gestore segreto della piattaforma di hosting o un altro canale sicuro approvato.

Passaggio 1: creare un commerciante Sandbox SumUp

  1. Accedi a Dashboard SumUp.
  2. Apri Impostazioni sviluppatore.
  3. Apri la scheda Sandbox.
  4. Crea un commerciante sandbox se non ne esiste nessuno.
  5. Utilizza il commutatore di account per selezionare il commerciante sandbox.

L'account selezionato deve essere chiaramente contrassegnato come sandbox. Non utilizzare mai un commerciante dal vivo per questo primo test.

Ie il tuo account SumUp non ha impostazioni sviluppatore o opzioni sandbox, crea un account sviluppatore da il collegamento nella guida ufficiale al test dei pagamenti online di SumUp.

Passaggio 2: copiare il codice commerciante Sandbox

Con il commerciante sandbox selezionato, guarda l'area in alto a sinistra della dashboard di SumUp. Spettacoli di riepilogo lì il nome dell'account e ID commerciante. WebBlocks Commerce chiama questo valore codice commerciante. Normalmente è simile a MXXXXXXX.

Copia questo valore per il passaggio 4. Non utilizzare l'ID commerciante del tuo account live.

Passo 3: creare una chiave API di prova

Mantieni selezionato il commerciante sandbox, quindi:

  1. Espandi il tuo profilo e apri Impostazioni.
  2. Vai a Per sviluppatori → Toolkit.
  3. Apri Chiavi API.
  4. Seleziona Crea e assegna alla chiave un nome riconoscibile, ad esempio WebBlocks Commerce sandbox.
  5. Copia o scarica la chiave segreta quando SumUp la mostra.

Non utilizzare la chiave pubblica SumUp. WebBlocks Commerce necessita della chiave API segreta lato server. A la chiave segreta di prova normalmente inizia con sk_test_. SumUp non mostra più il segreto completo, quindi conservarlo immediatamente in un gestore segreto approvato.

L'attuale integrazione diretta riguarda un account commerciante controllato dal proprietario del sito. OAuth lo è non richiesto per questa configurazione.

Passaggio 4: configurare WebBlocks Commerce

  1. Accedi all'amministrazione CMS.
  2. Apri Commerce → Impostazioni commercio.
  3. Seleziona gateway SumUp e modalità Sandbox.
  4. Inserisci la chiave API segreta e l'ID commerciante, quindi salva.

I campi delle credenziali sono di sola scrittura. Lasciare un campo vuoto conserva il valore salvato; utilizzare il controllo chiaro esplicito solo quando si intende rimuoverlo.

Le distribuzioni gestite dall'hosting potrebbero invece aggiungere queste sostituzioni di ambiente facoltative:

Aggiungi questi valori alle impostazioni segrete o variabili di ambiente della piattaforma di hosting:

WEBBLOCKS_COMMERCE_GATEWAY=sumup
WEBBLOCKS_COMMERCE_DEFAULT_CURRENCY=EUR
WEBBLOCKS_COMMERCE_SUMUP_MODE=sandbox
WEBBLOCKS_COMMERCE_SUMUP_API_KEY=replace-with-your-sk_test-key
WEBBLOCKS_COMMERCE_SUMUP_MERCHANT_CODE=replace-with-your-sandbox-merchant-id

EI valori dell'ambiente hanno la precedenza e rendono i controlli del modulo corrispondenti di sola lettura. Se il l'installazione utilizza un file Laravel .env, aggiungi lì i valori. Quindi svuota la cache configurazione:

php artisan config:clear

Se la distribuzione normalmente memorizza nella cache la configurazione, ricostruire la cache utilizzando la sua normale distribuzione procedura. Riavvia i nodi di lavoro PHP di lunga durata quando la piattaforma di hosting lo richiede.

L'etichetta della modalità sandbox aiuta gli operatori a vedere quale ambiente è previsto. SumUp utilizza un'API nome host, quindi la chiave API e il codice commerciante devono appartenere all'account sandbox.

Passo 5: verificare che Commerce sia pronto

  1. Accedi all'amministrazione CMS.
  2. Apri Commerce → Impostazioni commercio, oppure visita /webadmin/plugins/webblocks-commerce/settings.
  3. Conferma tutto quanto segue:
    • gateway attivo: sumup
    • valuta predefinita: EUR (o un'altra valuta supportata da SumUp)
    • Modalità SommaSu: sandbox
    • Chiave API: configurata
    • codice commerciante: configurato
    • checkout: pronto
    • schema plug-in: ready

La schermata delle impostazioni dice deliberatamente solo "configurato" o "mancante". Non visualizza mai l'API chiave stessa, anche dopo un salvataggio riuscito.

Se lo schema non è pronto, apri Sistema → Plugin → WebBlocks Commerce ed esegui la configurazione del plugin o prima le migrazioni.

Passo 6: creare un prodotto di prova

  1. Apri Commerce → Prodotti.
  2. Crea o modifica un prodotto.
  3. Imposta titolo, slug, prezzo, valuta e classe fiscale.
  4. Scegli EUR per il primo test SumUp a meno che il commerciante sandbox non utilizzi un'altra opzione mostrata nel selettore di valuta.
  5. Imposta lo stato del prodotto su Attivo.
  6. Salva il prodotto.

A Impossibile estrarre il prodotto bozza o archiviato. Se lo stock tracciabile è abilitato, assicurati almeno una unità è disponibile.

Passo 7: aggiungere il blocco commercio nativo

  1. Apri la pagina CMS desiderata nel generatore di pagine.
  2. Aggiungi un blocco Commerce Buy Button a uno slot di pagina normale.
  3. Seleziona il prodotto attivo.
  4. Scegli le opzioni di etichetta, allineamento e visualizzazione del prezzo dei pulsanti.
  5. Visualizza in anteprima e pubblica la pagina tramite il normale flusso di lavoro CMS.

Non utilizzare un blocco HTML affidabile e non incollare un URL di pagamento di SumUp nel contenuto. Un URL di pagamento viene creato per ogni ordine e scade dopo circa 30 minuti.

Passaggio 8: effettuare un pagamento sandbox con esito positivo

  1. Apri la pagina pubblica del prodotto o la pagina contenente il pulsante Commercio.
  2. Aggiungi il prodotto al carrello.
  3. Verifica quantità, IVA, valuta e importo finale.
  4. Seleziona Continua per garantire il pagamento.
  5. Nella pagina ospitata da SumUp, utilizza questa scheda di test sandbox ufficiale:
Card number: 4200 0000 0000 0091
Expiry date: any future date, for example 12/30
CVV: any three digits, for example 123
Cardholder: any name
  1. Completa il pagamento e utilizza l'azione di reso per tornare al negozio.
  2. Nell'amministrazione CMS, apri Commerce → Ordini.
  3. Confermare che l'ordine cambia in paid e il tentativo di pagamento in succeeded.

La pagina di ritorno del browser non costituisce prova del pagamento. L'ordine viene pagato solo dopo WebBlocks Commerce riceve la notifica di SumUp, recupera il checkout da SumUp e verifica il file commerciante, riferimento, importo, valuta, stato finale e transazione andata a buon fine.

Non è necessaria la configurazione manuale del webhook SumUp

Per questa integrazione, non creare o incollare un URL webhook nella dashboard di SumUp. WebBlocks Commerce invia automaticamente questa richiamata come checkout return_url:

https://your-shop.example/plugins/webblocks-commerce/webhooks/sumup

Il negozio pubblico deve utilizzare HTTPS e SumUp deve essere in grado di raggiungere questo URL. Un firewall, manutenzione pagina, autenticazione HTTP o regola proxy non devono bloccare la richiesta POST di SumUp.

Test di errore opzionale

SumUp utilizza determinati totali per simulare un pagamento rifiutato. Per testare il percorso di errore, creare un prodotto temporaneo il cui totale del checkout finale sia esattamente 11.00 EUR, quindi utilizzare una sandbox scheda di prova. Confermare che l'ordine non sia contrassegnato come pagato e che lo stock riservato venga rilasciato dopo il l'errore viene elaborato.

Non modificare il prezzo del prodotto reale per questo test.

Passare ai pagamenti in tempo reale

Cambia solo dopo che il flusso sandbox completo ha esito positivo:

  1. Seleziona il conto commerciante reale nella dashboard di SumUp.
  2. Completa qualsiasi verifica aziendale e configurazione dei pagamenti richiesta da SumUp.
  3. Copia l'ID commerciante attivo.
  4. Crea una chiave API segreta live separata. Una chiave live normalmente inizia con sk_live_.
  5. Sostituisci i valori sandbox salvati in Impostazioni commercio, cambia la modalità in Live e salva. Le distribuzioni gestite dall'hosting possono invece sostituire le sostituzioni dell'ambiente:
WEBBLOCKS_COMMERCE_GATEWAY=sumup
WEBBLOCKS_COMMERCE_SUMUP_MODE=live
WEBBLOCKS_COMMERCE_SUMUP_API_KEY=replace-with-your-sk_live-key
WEBBLOCKS_COMMERCE_SUMUP_MERCHANT_CODE=replace-with-your-live-merchant-id
  1. Se vengono utilizzate le sostituzioni dell'ambiente, aggiornare la configurazione dell'applicazione utilizzando la normale procedura di distribuzione.
  2. Ricontrolla Impostazioni commercio.
  3. Effettua un acquisto reale accettabile di basso valore e verifica l'ordine e il pagamento in entrambi i sistemi.

Non combinare mai una chiave di prova con un ID commerciante attivo né riutilizzare la chiave sandbox in produzione.

Risoluzione dei problemi

Le Impostazioni commerciali dicono "Chiave API mancante"

  • Reinserisci la chiave API nel campo di sola scrittura e salva.
  • Se viene visualizzata una sostituzione dell'ambiente, controllarne l'ortografia e verificare che la distribuzione o il processo PHP sia stato aggiornato.
  • Se la configurazione è memorizzata nella cache, cancellarla e ricostruirla utilizzando la normale procedura di distribuzione.

Le impostazioni commerciali indicano pronto, ma il checkout non riesce

  • Conferma che la chiave e l'ID commerciante appartengono allo stesso account sandbox.
  • Conferma che la chiave è la chiave API segreta, non la chiave pubblica.
  • Conferma che il prodotto è attivo, ha un prezzo positivo e ha scorte disponibili.
  • Confermare che la valuta del prodotto corrisponda alla valuta supportata dal commerciante.

Il cliente ha pagato, ma l'ordine rimane in sospeso

  • Conferma che https://your-shop.example/plugins/webblocks-commerce/webhooks/sumup è raggiungibile pubblicamente tramite POST su HTTPS.
  • Verificare che un firewall, una pagina di manutenzione o una password HTTP non blocchino la richiamata.
  • Conferma che la chiave API può ancora recuperare il checkout e appartiene al commerciante configurato.
  • Confirm SumUp segnala il checkout come PAID con una transazione riuscita.

Il checkout ospitato indica scaduto o non trovato

Riavvia il pagamento dal carrello. Le sessioni di pagamento ospitate scadono dopo circa 30 minuti. Non farlo aggiungi ai segnalibri o riutilizza un vecchio URL di pagamento ospitato.

Regole di sicurezza

  • Non inserire mai la chiave API in un blocco, pagina, prodotto, script del browser, repository, screenshot o supporto log.
  • Non incollare mai una vera chiave API nella chat.
  • Mantieni sandbox e credenziali live separate.
  • Revocare e sostituire immediatamente la chiave se potrebbe essere stata esposta.
  • Considera lo stato dell'ordine CMS, non la schermata di successo del browser, come segnale di evasione.

Per architettura, verifica del webhook, stati degli ordini e risoluzione avanzata dei problemi, continuare con la Guida per l'operatore WebBlocks Commerce.

Oriferimenti ufficiali SumUp: