Vouchers
Overview
A voucher is a single-use discount instrument generated from member accumulated balance. Vouchers are the redemption mechanism in Otonum. They convert stored reward value (points or cashback) into a checkout discount.
Lifecycle
-
Balance accumulated. Member earns points or cashback across purchases.
-
Voucher created. Member chooses redemption. Otonum creates voucher and moves corresponding amount from
balancetototalReserved. -
Voucher validated at checkout. Your system calls validation endpoint to confirm voucher is still active and retrieve final cash discount value.
-
Purchase submitted with redemption. Your system submits purchase including voucher reference. Otonum marks voucher as consumed and updates balance.
-
Expiration (if unused). If voucher is not used within 30 days, it expires automatically and reserved amount returns to
balance.
Residual Amount
If a voucher is partially consumed (purchase amount is less than voucher value), the residual amount automatically generates a new voucher that inherits the expiration date of the original voucher.
You do not need to manage residual amounts manually. Otonum creates the follow-up voucher automatically. The purchase response includes the new voucher reference when applicable.
Validate / Reserve / Redeem Flow
Redemption requires three sequential steps to prevent double-spend in concurrent request scenarios:
- Validate. Confirm voucher is active and retrieve final
cashValue. - Reserve. Lock voucher for your transaction context. A reserved voucher cannot be used by a concurrent request.
- Redeem. Submit purchase with voucher reference. Otonum marks it as consumed.
Never redeem without confirmed reservation. Skipping reservation exposes integration to race conditions (TOCTOU), where two concurrent checkouts may attempt to consume the same voucher.
When to Create a Voucher
Create vouchers on demand at checkout, only when member explicitly chooses redemption. Avoid creating vouchers in advance (during enrollment or on schedule), because it unnecessarily locks member balance for 30 days and can block other redemption opportunities.
Key Points
- A voucher is always tenant-scoped. It cannot be redeemed with a different partner.
- Minimum balance required to create a voucher is defined in your program settings.
- A consumed or expired voucher cannot be reactivated.