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. Configure a Checkout Callback Page​

When the customer completes the wallet recharge on the Voucherly Checkout page, they are redirected to the URLs specified in the Create Payment API request:

  • If the payment was completed successfully, the user is redirected to redirectOkUrl.
  • In case of an error, the user is redirected to redirectKoUrl.

The merchant must configure two routes on their site to handle the payment result and accept the query-string parameters sent with the redirect:

  • success: Can be OK if the payment succeeded, otherwise KO.
  • status: The payment status.
  • paymentId: The payment ID, in the format pay_XXXXXXXXXXX.
  • referenceId: The merchant's custom reference ID sent when creating the payment.
  • amount: The amount paid, in cents.
  • voucherAmount: The amount paid with meal vouchers, in cents.
  • walletAmount: The amount paid with the wallet, in cents.
  • transactions: The number of transactions.
  • customerId: The Voucherly customer identifier, in the format cs_XXXXXXXXXXX. It must be stored in the merchant's system for future payments.
  • customerFirstName: The customer's first name.
  • customerLastName: The customer's last name.
  • customerEmail: The customer's email address.
  • tenant: live or sand.

3. Configure a Server-to-Server Endpoint (Optional)​

We recommend defining an endpoint that Voucherly will call via S2S to notify the payment result before redirecting to the merchant's site. See here for more details on how to implement an S2S endpoint and its behavior.

warning

As described in the Server-to-Server section, make sure your endpoint responds correctly to S2S notifications. Otherwise, the payment will be cancelled and the amounts refunded.