Kiosk

Use Voucherly's Kiosk integration to process payments directly through self-service kiosks.

Hardware requirements

The kiosk must have:

• An internet connection.
• A display toward the user.

If the kiosk is offline but communicates via a local server refer to the Online Payment use case.

Incoming internet connections

If the kiosk allows incoming internet connections refer to the Online Payment use case.

Quick Guide

Let’s walk through a simple example of integrating the payment flow for a kiosk.

info

This integration is designed to dynamically generate a QR code, enabling users to effortlessly scan it with their mobile devices and complete the payment process seamlessly.

1. Display QR Code

You can use Voucherly as an intermediary to manage all your payments or integrate it as an additional payment method alongside your existing ones.

Add a checkout button to your kiosk and create a Payment in Voucherly.

info

Refer to the Create Payment API for detailed functionality and usage.

You can also create a Payment for an existing customer, allowing you to prefill the checkout form with their contact details and unify their purchase history. A Payment represents the experience your customer sees when redirected to the payment form. You can configure it with options such as:

• Lines. Specify the items to charge for. For each item, the isFood field determines whether it can be paid with vouchers.
• Discounts. Define the discounts applied to cart.

Ensure you set redirectOkUrl to the URL where the customer is redirected after successful payment. You can also provide a redirectKoUrl where the customer is redirected if they cancel the payment process.

info

Payments expire 24 hours after creation by default.

Example request

{
    "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,
            "productName": "Muffin al Cioccolato",
            "productImage": "https://cdn.trovaricetta.com/photo/2016/10/07/1771032/b/muffin-al-cioccolato-facilissimi.jpg",
            "isFood": true
        }
    ],
    "discounts": [
        {
            "discountName": "Coupon",
            "discountDescription": "",
            "amount": 200
        }
    ]
}

After creating the Payment, display the checkoutUrl returned in the response as a QR code on the kiosk screen. Customers can scan the QR code using their mobile devices to access the payment page and complete the transaction.

tip

You can use a library like qrcode.js or a server-side QR code generator to create and display the QR code.

Example response

{
    "id": "my-payment-id-1",
    "tenant": "live",
    "mode": "Payment",
    "customerId": "my-customer-id-1",
    [...]
    "checkoutUrl": "https://example.voucherly.it/checkout",
    "status": "Requested",
    [...]
}

2. Wait for payment completion

Since the kiosk doesn't allow incoming internet connections, the Callback S2S mechanism may not be practical.

Instead, you can use Get Payment API with the Voucherly-Wait-Time header for long polling. Once the payment is closed, any additional operations should be handled:

• Print receipts.
• Update local databases.
• Enable hardware (e.g. Open a locker).

tip

A Payment should not be considered closed if its status is REQUESTED.

Please refer to the Understanding payment resource for more information about payment statuses.

warning

After 10 minutes, it is recommended to stop the process and consider the payment cancelled. Continuing indefinitely may lead to unnecessary resource usage and delays in handling the transaction.

3. Show a success page

Mobile device

It’s important for your customers to see a success or error page after submitting the payment form.

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

• If the payment is successful, the customer is redirected to the redirectOkUrl.
• If the payment fails, the customer is redirected to the redirectKoUrl.

Payment information is passed via the query string:

• success. Indicates the Payment result (OK for success, KO for failure).
• status. The status of the Payment.
• paymentId. The unique Voucherly identifier for the Payment.
• referenceId. The merchant's custom reference ID.
• amount. The total paid amount in cents.
• voucherAmount. The portion of the paid amount covered by vouchers in cents.
• walletAmount. The portion of the paid amount covered by wallet credit in cents.
• transactions. The number of transactions involved in the Payment.
• customerId. The unique Voucherly identifier for the customer.
• customerEmail. The customer's email address.
• customerFirstName. The customer's first name.
• customerLastName. The customer's last name.
• tenant. live or sand.

Kiosk

After the customer completes the payment on the Voucherly Checkout page, they can close their mobile device and seamlessly continue their order experience directly at the kiosk.

You are free to manage this phase independently, aligning with the best practices of your company.

Next steps

Optional

Prefill customer data

Optional

Display payment gateways