Skip to main content

Voucherly pay-at-table authentication and SSO integration guide

Introduction​

This guide explains how to connect your authentication system with Voucherly’s pay-at-table experience.
When a customer opens a Voucherly link (typically by scanning a QR code on the table), Voucherly may need to verify their identity before proceeding. Instead of handling authentication directly, Voucherly delegates the process to your system allowing you to manage sessions, user data, and login methods as you prefer.

You’ll need to expose a login endpoint (required) and optionally a logout endpoint, which Voucherly will call whenever authentication or session termination is required. These endpoints will exchange a set of signed parameters to ensure data integrity and trust between your system and Voucherly.

By the end of this guide, you’ll know how to:

  • Set up your authentication endpoints
  • Generate and verify digital signatures
  • Configure everything in the Voucherly dashboard
  • (Optionally) handle user logout

Prerequisites​

Overview​

Voucherly requires your system to expose two endpoints:

  • Endpoint login – standard SSO-style login page that receives authentication requests from Voucherly and, after verifying the user, redirects them back to Voucherly with the required customer information.
  • Endpoint logout (optional) – if implemented, handles logout requests from Voucherly to terminate customer sessions in your system.

Your system is responsible for verifying user identity, optionally allowing guest access, and securely communicating customer data back to Voucherly via signed query parameters.

Integration​

Login endpoint​

This endpoint works like a typical SSO login page:

  1. Voucherly calls your authentication endpoint with a returnUrl query parameter.
  2. Your system verifies the user’s identity.
    • Unauthenticated users: optionally allow guest access by redirecting back to returnUrl without query parameters.
    • Authenticated users: redirect back to returnUrl with the following query parameters.
ParameterDescription
customerIdUnique identifier of the customer in your system (required)
emailCustomer's email address
friendlyNameDisplay name that Voucherly will use to address the customer
firstNameCustomer's first name
lastNameCustomer's last name
timestampUnix timestamp in seconds (generated by your system at the moment of redirect)
signatureDigital signature to verify authenticity

Signature calculation​

The signature parameter ensures the integrity and authenticity of the redirect. Use your 2048-bit RSA private key (PKCS#8) to sign the parameters.

  1. Concatenate the following parameters in the exact order:
customerId + email + friendlyName + firstName + lastName + timestamp
  1. Compute the SHA-256 hash of the concatenated string.
  2. Sign the hash using RSA PKCS#1 v1.5 with your private key.
  3. Encode the signature in base64.
  4. Append it to the redirect URL as signature.
var concatenation = new StringBuilder()
    .Append(customerId)
    .Append(email)
    .Append(friendlyName)
    .Append(firstName)
    .Append(lastName)
    .Append(timestamp)
    .ToString();

var dataBytes = Encoding.UTF8.GetBytes(concatenation);

var privateKey = ReadPrivateKeyPem(); // your PKCS#8 private key

using var rsa = RSA.Create();
rsa.ImportFromPem(privateKey);

var signature = rsa.SignData(dataBytes, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);

// Append to returnUrl as query parameter

Generating a 2048-bit RSA Key Pair (PKCS#8)​

To sign authentication requests, you need an asymmetric RSA key pair:

  1. Generate the private key in PKCS#8 format (2048-bit).
  2. Export the public key to share with Voucherly for signature verification.
# Generate a 2048-bit private key in PKCS#8 PEM format
openssl genpkey -algorithm RSA -out private_key.pem -pkeyopt rsa_keygen_bits:2048

# Extract the corresponding public key
openssl rsa -pubout -in private_key.pem -out public_key.pem
warning
  • Keep the private key secure. Do not expose it in client-side code.

Logout endpoint (optional)​

This endpoint is optional and works like a standard SSO logout page:

  1. Voucherly calls your logout endpoint and provides a returnUrl query parameter.
  2. Your system terminates the customer session (e.g., clears cookies, ends server-side session).
  3. Redirect the user back to the returnUrl.
info

If not implemented, the user will not see a logout button in Voucherly.

Configuration​

  1. Sign in to your Voucherly dashboard.
  2. Go to Impostazioni > Pagamento al tavolo.
    • Select Redirect as the authentication type.
    • Enter your login endpoint URL.
    • (Optional) Enter your logout endpoint URL.
    • Upload your RSA public key in PEM (PKCS#8) format.
    • Save the configuration.
tip

You can include placeholders in the endpoint URLs will populate at redirect time:

  • {ExternalTableId}
  • {ExternalShopId}
  • {OrderId}

These placeholders can be used, for example, to perform checks on shops or tables before redirecting the user.

Test the integration​

Once you’ve configured your login/logout endpoints and uploaded your RSA key, you can test the pay-at-table flow directly from the Voucherly dashboard.

  1. Sign in to your Voucherly dashboard.
  2. Go to Impostazioni > Sedi and create a new location (if not already present).
  3. Navigate to Tavoli > Sedi e tavoli.
    • Select the location you just created.
    • If needed, create a room first, then add a table.
    • Now you’ll see a populated table with your rooms and tables. In the QR code column, you’ll find three icons:
      • Clicking the first two icons will copy the pay-at-table URL to your clipboard.
      • Clicking the third icon will open the pay-at-table page in a new browser tab.
  4. Open the pay-at-table URL in a browser.
    • Verify that authentication works correctly.
    • Check that the signed parameters are passed and the user is redirected back to Voucherly.
tip

Make sure you are in the sandbox environment so you always have an active order on the table.
Otherwise, you’ll need to manage the presence of orders in your POS system manually.

support