WiFi Vouchers & POS Integration

Overview

CaptiFi's WiFi Voucher system allows you to control guest WiFi access by requiring voucher codes before guests can connect. Combined with the POS (Point of Sale) API integration, venues can automatically generate voucher codes directly from their POS terminal, receipt printer, or ordering system — creating a seamless guest WiFi experience tied to purchases.

WiFi Access Modes
Configuring Voucher Mode
Managing Vouchers
Creating Vouchers Manually
Voucher Statuses
POS API Integration
API Reference
Bulk Actions & Export
Troubleshooting

WiFi Access Modes

The Voucher & POS Setup page (VoucherAndPosSetup) contains two main configuration sections. The first controls how guests connect to your WiFi network.

Section 1: WiFi Access Mode Toggle

Mode	Description
Open Access (default)	Any guest can connect to your WiFi network through the captive portal without a code. The standard splash page flow applies.
Voucher Required	Guests must enter a valid voucher code on the captive portal before they can access WiFi. Without a code, access is denied.

⚠️ Warning: Enabling Voucher Required mode means that only guests with valid voucher codes will be able to connect to your WiFi network. Make sure you have a process in place to distribute codes (e.g., printed on receipts, handed out by staff, or generated via POS integration) before enabling this mode.

Step-by-Step: Switching to Voucher Mode

Navigate to Dashboard → Voucher & POS Setup.
In the WiFi Access Mode section, toggle from Open Access to Voucher Required.
Read and acknowledge the warning message that appears.
Click Save to apply the change.
Your captive portal will now display a voucher code input field to all guests.

Step-by-Step: Switching Back to Open Access

Navigate to Dashboard → Voucher & POS Setup.
Toggle the WiFi Access Mode back to Open Access.
Click Save.
Guests can now connect without a voucher code. Existing unused vouchers remain in the system but are not required.

Configuring Voucher Mode

Once Voucher Required mode is enabled, you need to ensure vouchers are available for your guests. There are two ways to generate vouchers:

Manually — through the CaptiFi dashboard (see Creating Vouchers Manually)
Automatically — via the POS API integration (see POS API Integration)

Managing Vouchers

The WiFi Vouchers resource page displays all vouchers across your sites in a searchable, sortable table.

Voucher Table Columns

Column	Description
Code	The unique voucher code (e.g., `ABCD1234`) that guests enter on the captive portal.
Site	The site (venue/location) the voucher is assigned to (`site.name`).
Duration (Hours)	How long the WiFi session lasts once the voucher is redeemed (e.g., 2 hours, 24 hours).
Max Uses	Maximum number of times the voucher code can be used (default: 1).
Times Used	How many times the voucher has been redeemed so far.
Status	Current status badge — see Voucher Statuses below.
Expires At	The date/time after which the voucher can no longer be redeemed, regardless of use count.
Notes	Optional notes (e.g., "Table 5", "VIP Guest", "Staff lunch").
Created At	Timestamp when the voucher was generated.

Available Actions (Per Voucher)

Action	Condition	Description
Revoke	Voucher status is Active	Immediately invalidates the voucher so it can no longer be used.
Copy Code	Always available	Copies the voucher code to your clipboard for easy sharing.

Creating Vouchers Manually

You can create vouchers directly from the CaptiFi dashboard using the Create button on the WiFi Vouchers page.

Create Form Fields

Field	Type	Required	Details
Site	Select dropdown (`site_id`)	✅ Yes	Choose which site/venue this voucher is for.
Quantity	Number (1–100)	✅ Yes	Number of voucher codes to generate in a single batch.
Duration (Hours)	Select dropdown	✅ Yes	Session length options: 1hr, 2hr, 4hr, 8hr, 12hr, 24hr, 48hr, 72hr, 168hr (7 days).
Max Uses	Number	✅ Yes	Maximum redemptions per code. Default: 1.
Expires At	Datetime picker	❌ No	Optional expiration date/time. If not set, vouchers remain valid until used or manually revoked.
Notes	Text	❌ No	Optional freeform notes for internal reference.

Step-by-Step: Creating a Batch of Vouchers

Navigate to Dashboard → WiFi Vouchers.
Click the Create button (top right).
Select the Site the vouchers are for.
Set the Quantity (e.g., 10 to generate 10 codes at once).
Choose the Duration (e.g., 4 hours).
Set Max Uses (leave as 1 for single-use codes).
Optionally set an Expires At date if the vouchers should expire by a certain time.
Optionally add Notes (e.g., "Friday evening event").
Click Create.
Your new voucher codes will appear in the table immediately.

💡 Tip: Use the Copy Code action to quickly copy individual codes, or use Bulk Export to download all codes for printing.

Voucher Statuses

Each voucher displays a color-coded status badge:

Status	Badge Color	Meaning
Active	🟢 Green	Voucher is valid and available for use.
Used	🔵 Blue	Voucher has been redeemed the maximum number of times.
Expired	🟡 Yellow/Amber	The voucher's `expires_at` date has passed.
Revoked	🔴 Red	The voucher was manually invalidated by an administrator.

Status Lifecycle

Created → Active → Used (max_uses reached)
                 → Expired (expires_at passed)
                 → Revoked (manually invalidated)

POS API Integration

Section 2: POS API Setup

The second section of the Voucher & POS Setup page allows you to connect your Point of Sale system to CaptiFi for automatic voucher generation.

Configuration Fields

Field	Description
Enable POS API	Toggle to enable/disable the POS API integration.
API Key	Auto-generated API key for authenticating POS requests. Includes a Copy button and a Regenerate button.
API Endpoint	The endpoint URL your POS system should call (shown on screen).

Step-by-Step: Setting Up POS Integration

Navigate to Dashboard → Voucher & POS Setup.
In the POS API Integration section, toggle Enable POS API to on.
An API Key will be auto-generated and displayed.
Click the Copy button to copy the API key.
Note the API Endpoint URL shown: POST https://app.captifi.io/api/pos/voucher/generate.
Provide the API key and endpoint to your POS system administrator or configure it in your POS software.
Click Save.

⚠️ Security Note: Your API key provides access to generate vouchers on your account. Keep it secure and never expose it in client-side code. If you suspect your key has been compromised, click Regenerate to create a new key (the old key will immediately stop working).

API Reference

Generate Vouchers

Creates one or more WiFi voucher codes programmatically.

Endpoint:

POST https://app.captifi.io/api/pos/voucher/generate

Headers:

Content-Type: application/json

Request Body:

json

{
  "api_key": "your-api-key-here",
  "duration_hours": 2,
  "quantity": 1,
  "notes": "Table 5"
}

Parameter	Type	Required	Description
`api_key`	string	✅ Yes	Your POS API key from the dashboard.
`duration_hours`	integer	✅ Yes	WiFi session duration in hours (e.g., `1`, `2`, `4`, `8`, `12`, `24`, `48`, `72`, `168`).
`quantity`	integer	❌ No	Number of voucher codes to generate. Default: `1`. Max: `100`.
`notes`	string	❌ No	Optional note attached to the voucher(s) (e.g., table number, order ID).

Success Response (200):

json

{
  "success": true,
  "vouchers": [
    {
      "code": "ABCD1234",
      "duration_hours": 2,
      "expires_at": "2025-01-15T14:30:00Z",
      "max_uses": 1
    }
  ]
}

Response Field	Type	Description
`success`	boolean	`true` if voucher(s) were created successfully.
`vouchers`	array	Array of generated voucher objects.
`vouchers[].code`	string	The voucher code to give to the guest.
`vouchers[].duration_hours`	integer	WiFi session duration in hours.
`vouchers[].expires_at`	string (ISO 8601)	When the voucher expires.
`vouchers[].max_uses`	integer	Maximum number of times the code can be redeemed.

Error Responses:

Status Code	Meaning
`401`	Invalid or missing API key.
`403`	POS API is not enabled for this account.
`422`	Validation error (e.g., invalid `duration_hours` value).
`429`	Rate limit exceeded.

Validate Voucher

Check whether a voucher code is currently valid without redeeming it.

Endpoint:

POST https://app.captifi.io/api/pos/voucher/validate

Request Body:

json

{
  "api_key": "your-api-key-here",
  "code": "ABCD1234"
}

Parameter	Type	Required	Description
`api_key`	string	✅ Yes	Your POS API key.
`code`	string	✅ Yes	The voucher code to validate.

Success Response (200):

json

{
  "valid": true,
  "voucher": {
    "code": "ABCD1234",
    "status": "active",
    "duration_hours": 2,
    "max_uses": 1,
    "times_used": 0,
    "expires_at": "2025-01-15T14:30:00Z"
  }
}

Invalid Voucher Response (200):

json

{
  "valid": false,
  "reason": "expired"
}

Possible `reason` Values	Description
`not_found`	Code does not exist.
`expired`	Voucher has passed its expiration date.
`used`	Voucher has reached its max uses.
`revoked`	Voucher was manually revoked.

Bulk Actions & Export

The WiFi Vouchers table supports bulk operations:

Bulk Action	Description
Revoke Selected	Select multiple active vouchers and revoke them all at once. Useful for invalidating a batch of unused codes.
Export	Download selected or all vouchers as a file for printing, record-keeping, or import into other systems.

Step-by-Step: Bulk Revoking Vouchers

On the WiFi Vouchers page, use the checkboxes to select the vouchers you want to revoke.
Click the Bulk Actions dropdown.
Select Revoke Selected.
Confirm the action.
All selected vouchers will be marked as Revoked.

Step-by-Step: Exporting Vouchers

On the WiFi Vouchers page, optionally filter or select specific vouchers.
Click the Bulk Actions dropdown.
Select Export.
A file will be downloaded containing the voucher codes and their details.

Troubleshooting

Common Issues

Issue	Possible Cause	Solution
Guests can't connect to WiFi	Voucher mode is enabled but no vouchers have been created or distributed.	Create vouchers via the dashboard or POS API, then distribute codes to guests.
Voucher code not working	Code may be expired, already used, or revoked.	Check the voucher's status in the dashboard. If expired/used, generate a new code.
POS API returning `401`	Invalid API key.	Verify the API key in your POS configuration matches the key shown on the Voucher & POS Setup page. Regenerate if needed.
POS API returning `403`	POS API not enabled.	Go to Voucher & POS Setup and toggle Enable POS API to on.
POS API returning `422`	Invalid request parameters.	Check that `duration_hours` is a valid value and `quantity` is between 1 and 100.
API key stopped working	Key was regenerated.	If someone regenerated the key in the dashboard, the old key is immediately invalidated. Copy the new key and update your POS configuration.
Bulk revoke not working	No vouchers selected, or selected vouchers are not in Active status.	Ensure you've selected vouchers with an Active status. Already used, expired, or revoked vouchers cannot be revoked again.
Vouchers appear but portal still open	WiFi Access Mode may still be set to Open Access.	Navigate to Voucher & POS Setup and ensure the mode is set to Voucher Required.

POS Integration Testing

To test your POS integration before going live:

Enable the POS API and copy your API key.
Use a tool like curl, Postman, or your POS system's test mode.
Send a test request:

bash

curl -X POST https://app.captifi.io/api/pos/voucher/generate \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "duration_hours": 1,
    "quantity": 1,
    "notes": "Test voucher"
  }'

Verify the response contains a valid voucher code.
Check the WiFi Vouchers page in the dashboard to confirm the voucher appears.
Optionally validate the code:

bash

curl -X POST https://app.captifi.io/api/pos/voucher/validate \
  -H "Content-Type: application/json" \
  -d '{
    "api_key": "YOUR_API_KEY",
    "code": "ABCD1234"
  }'

Best Practices

Set expiration dates on event-specific vouchers to automatically clean up unused codes.
Use notes to track where/why vouchers were generated (e.g., table numbers, event names).
Monitor the Times Used column to identify if codes are being shared.
Regenerate your API key periodically for security.
Start with single-use vouchers (max_uses: 1) for maximum control, then adjust as needed.
Use batch generation (quantity > 1) to pre-generate codes for busy periods.

WiFi Vouchers & POS Integration ​

Overview ​

Table of Contents ​

WiFi Access Modes ​

Section 1: WiFi Access Mode Toggle ​

Step-by-Step: Switching to Voucher Mode ​

Step-by-Step: Switching Back to Open Access ​

Configuring Voucher Mode ​

Managing Vouchers ​

Voucher Table Columns ​

Available Actions (Per Voucher) ​

Creating Vouchers Manually ​

Create Form Fields ​

Step-by-Step: Creating a Batch of Vouchers ​

Voucher Statuses ​

Status Lifecycle ​

POS API Integration ​

Section 2: POS API Setup ​

Configuration Fields ​

Step-by-Step: Setting Up POS Integration ​

API Reference ​

Generate Vouchers ​

Validate Voucher ​

Bulk Actions & Export ​

Step-by-Step: Bulk Revoking Vouchers ​

Step-by-Step: Exporting Vouchers ​

Troubleshooting ​

Common Issues ​

POS Integration Testing ​

Best Practices ​

WiFi Vouchers & POS Integration

Overview

Table of Contents

WiFi Access Modes

Section 1: WiFi Access Mode Toggle

Step-by-Step: Switching to Voucher Mode

Step-by-Step: Switching Back to Open Access

Configuring Voucher Mode

Managing Vouchers

Voucher Table Columns

Available Actions (Per Voucher)

Creating Vouchers Manually

Create Form Fields

Step-by-Step: Creating a Batch of Vouchers

Voucher Statuses

Status Lifecycle

POS API Integration

Section 2: POS API Setup

Configuration Fields

Step-by-Step: Setting Up POS Integration

API Reference

Generate Vouchers

Validate Voucher

Bulk Actions & Export

Step-by-Step: Bulk Revoking Vouchers

Step-by-Step: Exporting Vouchers

Troubleshooting

Common Issues

POS Integration Testing

Best Practices