Passa al contenuto principale

Ricarica del Wallet

Come già accennato, i clienti possono ricaricare il proprio wallet durante un pagamento. Voucherly mette inoltre a disposizione un flusso dedicato specificamente alla ricarica del wallet.

avvertenza

Questo caso d'uso è disponibile solo se la funzionalità wallet è abilitata dalla Dashboard.

Ciclo di vita della ricarica del wallet​

Il processo è simile a un normale pagamento, con lievi differenze nei parametri passati alla Create Payment API.

  1. Quando il cliente vuole ricaricare il proprio wallet, devi creare un nuovo pagamento tramite la Create Payment API, impostando mode su Wallet.

    • Puoi specificare un importo da ricaricare includendo una singola line con l'importo desiderato e impostando la quantità a 1.
    • Se non viene passata alcuna line, Voucherly chiederà al cliente di inserire l'importo.

  2. La risposta dell'API includerà l'URL della pagina di Voucherly Checkout a cui il cliente deve essere reindirizzato.

  3. Il cliente può completare la ricarica utilizzando un gateway di pagamento con buoni, un gateway di pagamento non basato su buoni, oppure una combinazione di entrambi.

  4. Una volta completata la ricarica, se nel corpo della richiesta Create Payment API è stato fornito il campo callbackUrl, verrà inviata una notifica Server-to-Server (S2S) all'URL specificato. Il cliente verrà quindi reindirizzato all'URL del sito del merchant fornito nella richiesta.

avvertenza

Una volta che il cliente esce dalla pagina di checkout, la transazione sarà già nello stato Confirmed. Non è necessario confermarla tramite API e le ricariche del wallet non possono essere rimborsate.

Guida rapida​

Di seguito un esempio dettagliato di come integrare da zero il flusso di ricarica del wallet.

1. Crea un pagamento​

informazioni

Consulta la Create Payment API per tutte le funzionalità e i dettagli.

Quando il cliente è pronto a ricaricare il proprio wallet, il sito del merchant deve effettuare una chiamata HTTP alla Create Payment API.

Nella richiesta:

  • Imposta mode su Wallet.
  • Includi i dati del cliente o il customerId (se cliente di ritorno).
  • Fornisci redirectOkUrl e redirectKoUrl per il reindirizzamento dopo il checkout.

Se vuoi che Voucherly chieda al cliente l'importo che desidera ricaricare, non includere alcuna lines. Altrimenti, popola una singola riga di pagamento con:

  • Una quantità pari a 1.
  • L'importo da ricaricare.

Il referenceId è opzionale e consente al merchant di includere un identificativo personalizzato (ad es. l'ID del carrello o dell'ordine) per la riconciliazione con il proprio sistema interno.

Si consiglia vivamente di configurare un endpoint Server-to-Server (S2S) che Voucherly possa contattare per notificare al merchant l'esito del pagamento. L'URL di questo endpoint deve essere incluso nel campo callbackUrl.

POST /v1/payments HTTP/1.1
Host: api-stg.voucherly.it
X-API-Key: sk_test_kXbJtcgYV8hvdKqWS3iWEPZME20zgF6yC4YZp0m9rEbPJGxdf7GZY3nl
Content-Length: 900

{
    "referenceId": "eb8f57f8-241b-4142-b7b0-d308d724541a",
    "customerId": "cs_XBEKOB7mJLM",
    "customerFirstName": "Mario",
    "customerLastName": "Rossi",
    "customerEmail": "mario.rossi@email.com",
    "redirectOkUrl": "https://www.myecommerce.com/success",
    "redirectKoUrl": "https://www.myecommerce.com/error",
    "callbackUrl": "https://api.myecommerce.com/webhook/payment",
    "mode": "Wallet"
}

L'API di Voucherly restituisce l'oggetto Payment appena creato. Il campo chiave a cui prestare attenzione è CheckoutUrl, che contiene l'URL del sistema Voucherly Checkout. Il sito del merchant deve reindirizzare l'utente a questo URL per procedere con il pagamento.

{
    "id": "pay_wxNPzBQ4P5o",
    "referenceId": "eb8f57f8-241b-4142-b7b0-d308d724541a",
    "mode": "Wallet",
    "customerId": "cs_XBEKOB7mJLM",
    "customerFirstName": "Mario",
    "customerLastName": "Rossi",
    "customerEmail": "mario.rossi@email.com",
    "paymentGateways": [],
    "checkoutUrl": "https://checkout-stg.voucherly.it/pay?Id=pay_wxNPzBQ4P5o",
    "redirectOkUrl": "https://www.myecommerce.com/success",
    "redirectKoUrl": "https://www.myecommerce.com/error",
    "callbackUrl": "https://api.myecommerce.com/webhook/payment",
    "totalAmount": 476,
    "discountAmount": 200,
    "finalAmount": 276,
    "paidAmount": 0,
    "paidVoucherAmount": 0,
    "amount": 276,
    "hasWallet": true,
    "status": "Requested",
    "lines": [],
    "discounts": []
}

2. Configura una pagina di callback per il checkout​

Quando il cliente completa la ricarica del wallet sulla pagina di Checkout di Voucherly, viene reindirizzato agli URL specificati nella richiesta Create Payment API:

  • Se il pagamento è stato completato con successo, l'utente verrà reindirizzato a redirectOkUrl.
  • In caso di errore, l'utente verrà reindirizzato a redirectKoUrl.

Il merchant deve configurare due rotte sul proprio sito per gestire il risultato del pagamento e accettare i parametri della query string inviati con il reindirizzamento:

  • success: Può essere OK in caso di successo del pagamento, altrimenti KO.
  • status: Lo stato del pagamento.
  • paymentId: L'ID del pagamento, nel formato pay_XXXXXXXXXXX.
  • referenceId: L'ID di riferimento personalizzato del merchant inviato durante la creazione del pagamento.
  • amount: L'importo pagato in centesimi.
  • voucherAmount: L'importo pagato con buoni pasto in centesimi.
  • walletAmount: L'importo pagato con il wallet in centesimi.
  • transactions: Il numero di transazioni.
  • customerId: L'identificativo Voucherly del cliente nel formato cs_XXXXXXXXXXX. Deve essere memorizzato nel sistema del merchant per pagamenti futuri.
  • customerFirstName: Il nome del cliente.
  • customerLastName: Il cognome del cliente.
  • customerEmail: L'indirizzo email del cliente.
  • tenant: live o sand.

3. Configura un endpoint Server-to-Server (opzionale)​

Si consiglia di definire un endpoint che verrà contattato da Voucherly tramite S2S per notificare il risultato di un pagamento prima del reindirizzamento al sito del merchant. Consulta qui per ulteriori dettagli su come implementare un endpoint S2S e il suo comportamento.

avvertenza

Come descritto nella sezione Server-to-Server, assicurati che il tuo endpoint risponda correttamente alle notifiche S2S. In caso contrario, il pagamento verrà annullato e gli importi rimborsati.