Kiosk
Usa l'integrazione Kiosk di Voucherly per elaborare i pagamenti direttamente tramite chioschi self-service.
Il chiosco deve disporre di:
- Una connessione a internet.
- Un display rivolto verso l'utente.
Guida rapida
Vediamo un semplice esempio di integrazione del flusso di pagamento per un chiosco.
Questa integrazione è progettata per generare dinamicamente un QR code, consentendo agli utenti di scansionarlo facilmente con i propri dispositivi mobili e completare il processo di pagamento senza intoppi.
1. Mostra il QR code
Puoi utilizzare Voucherly come intermediario per gestire tutti i tuoi pagamenti oppure integrarlo come metodo di pagamento aggiuntivo insieme a quelli esistenti.
Aggiungi un pulsante di checkout al tuo chiosco e crea un pagamento in Voucherly.
Consulta la Create Payment API per il funzionamento e l'utilizzo dettagliati.
Puoi anche creare un pagamento per un cliente esistente, così da precompilare il modulo di checkout con i suoi dati di contatto e unificarne lo storico degli acquisti. Un pagamento rappresenta l'esperienza che il cliente vede quando viene reindirizzato al modulo di pagamento. Puoi configurarlo con opzioni come:
- Lines. Specifica gli articoli da addebitare. Per ogni articolo, il campo
product.isFooddetermina se può essere pagato con i buoni. - Discounts. Definisci gli sconti applicati al carrello.
Assicurati di impostare redirectOkUrl sull'URL a cui il cliente viene reindirizzato dopo un pagamento riuscito. Puoi anche fornire un redirectKoUrl a cui il cliente viene reindirizzato se annulla il processo di pagamento.
Per impostazione predefinita, i pagamenti scadono 24 ore dopo la creazione.
Esempio di richiesta
{
"mode": "Payment",
"customerEmail": "mario.rossi@voucherly.it",
"customerFirstName": "Mario",
"customerLastName": "Rossi",
"redirectOkUrl": "https://{{redirect_host}}/payment/success",
"redirectKoUrl": "https://{{redirect_host}}/payment/error",
"country": "IT",
"lines": [
{
"quantity": 2,
"unitAmount": 250,
"unitDiscountAmount": 10,
"discountAmount": 0,
"product": {
"externalId": "SKU-MUFFIN-001",
"name": "Muffin al Cioccolato",
"image": "https://cdn.trovaricetta.com/photo/2016/10/07/1771032/b/muffin-al-cioccolato-facilissimi.jpg",
"isFood": true
}
}
],
"discounts": [
{
"discountName": "Coupon",
"discountDescription": "",
"amount": 200
}
]
}
Dopo aver creato il pagamento, mostra il checkoutUrl restituito nella risposta come QR code sullo schermo del chiosco.
I clienti possono scansionare il QR code con i propri dispositivi mobili per accedere alla pagina di pagamento e completare la transazione.
Puoi utilizzare una libreria come qrcode.js o un generatore di QR code lato server per creare e mostrare il QR code.
Esempio di risposta
{
"id": "my-payment-id-1",
"tenant": "live",
"mode": "Payment",
"customerId": "my-customer-id-1",
[...]
"checkoutUrl": "https://example.voucherly.it/checkout",
"status": "Requested",
[...]
}
2. Attendi il completamento del pagamento
Poiché il chiosco non consente connessioni internet in ingresso, il meccanismo Callback S2S potrebbe non essere pratico.
In alternativa, puoi utilizzare la Get Payment API con l'header Voucherly-Wait-Time per il long polling.
Se il chiosco è offline ma comunica tramite un server, è consigliabile utilizzare il meccanismo Callback S2S. Il long polling rimane un approccio valido per aggiornare l'interfaccia del chiosco.
Una volta chiuso il pagamento, è necessario gestire eventuali operazioni aggiuntive:
- Stampare le ricevute.
- Aggiornare i database locali.
- Abilitare l'hardware (ad es. aprire un locker).
Un pagamento non deve essere considerato chiuso se il suo stato è REQUESTED.
Consulta Come funzionano i pagamenti per maggiori informazioni sugli stati dei pagamenti.
Dopo 10 minuti, è consigliabile interrompere il processo e considerare il pagamento annullato. Continuare all'infinito può comportare un utilizzo inutile di risorse e ritardi nella gestione della transazione.
3. Mostra una pagina di successo
Dispositivo mobile
È importante che i tuoi clienti vedano una pagina di successo o di errore dopo aver inviato il modulo di pagamento.
Quando un cliente completa il pagamento sulla pagina di Voucherly Checkout, viene reindirizzato agli URL specificati nella richiesta Create Payment API:
- Se il pagamento va a buon fine, il cliente viene reindirizzato al
redirectOkUrl. - Se il pagamento fallisce, il cliente viene reindirizzato al
redirectKoUrl.
Le informazioni sul pagamento vengono passate tramite la query string:
- success. Indica l'esito del pagamento (
OKper successo,KOper fallimento). - status. Lo stato del pagamento.
- paymentId. L'identificativo Voucherly univoco del pagamento.
- referenceId. L'ID di riferimento personalizzato del merchant.
- amount. L'importo totale pagato in centesimi.
- customerId. L'identificativo Voucherly univoco del cliente.
- tenant. live o sand.
Chiosco
Dopo che il cliente ha completato il pagamento sulla pagina di Voucherly Checkout, può chiudere il proprio dispositivo mobile e proseguire senza interruzioni l'esperienza d'ordine direttamente al chiosco.
Sei libero di gestire questa fase in autonomia, in linea con le best practice della tua azienda.