Skip to main content

Charge Wallet

As previously mentioned, customers can charge their wallet during a payment. Voucherly also provides a dedicated flow specifically for recharging the wallet.

warning

This use case is available only if the wallet feature is enabled from the Dashboard.

Wallet Recharge Lifecycle​

The process is similar to a regular payment, with minor differences in the parameters passed to the Create Payment API.

  1. When the customer wants to charge their wallet, you must create a new payment via the Create Payment API, setting mode to Wallet.

    • You can specify an amount to charge by including a single line with the desired amount and setting the quantity to 1.
    • If no line is passed, Voucherly will prompt the customer to input the amount.

  2. The API response will include the URL of the Voucherly Checkout page to which the customer must be redirected.

  3. The customer can complete the recharge using a voucher payment gateway, a non-voucher payment gateway, or a combination of both.

  4. After the recharge is completed, if the callbackUrl field was provided in the Create Payment API request, a Server-to-Server (S2S) notification will be sent to the specified URL. The customer will then be redirected to the merchant's website URL provided in the request.

warning

Once the customer exits the checkout page, the transaction will already be in the CONFIRMED state. You do not need to confirm it via API, and wallet recharges cannot be refunded.

Quick Guide​

Below is a detailed example of how to integrate the wallet recharge flow from scratch.

1. Create Payment​

info

Refer to the Create Payment API for full functionality and details.

When the customer is ready to recharge their wallet, the merchant's site must make an HTTP call to the Create Payment API.

In the request:

  • Set mode to Wallet.
  • Include customer data or customerId (if returning).
  • Provide redirectOkUrl and redirectKoUrl for post-checkout redirection.

If you want Voucherly to prompt the customer for the amount they wish to recharge, do not include any lines. Otherwise, populate a single payment line with:

  • A quantity of 1.
  • The amount to be recharged.

The referenceId is optional and allows the merchant to include a custom identifier (e.g., cart ID or order ID) for reconciliation with their internal system.

It is highly recommended to set up a Server-to-Server (S2S) endpoint that Voucherly can call to notify the merchant of the payment outcome. The URL for this endpoint should be included in the callbackUrl field.

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"
}

The Voucherly API returns the newly created Payment object. The key field to focus on is CheckoutUrl, which contains the URL of the Voucherly Checkout system. The merchant's website must redirect the user to this URL to proceed with the payment.

{
    "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. Configurare 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 or sand.

3. Configurare 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.

warning

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.