Gift card provider integration
Day-to-day workflows for selling, redeeming, checking the balance of, voiding, and refunding external gift cards at the point of sale, for centers connected to an external gift card provider (for example, an SVS-based program). Built-in Zenoti gift cards are not covered here β only cards that live on the external provider's network.
On this page
- Before you begin
- Network and external-system dependencies
- Check a gift card balance
- Sell a gift card
- Redeem a gift card at checkout
- Refund or void a gift card transaction
- Edit or adjust across states
- Reconciliation
- Failure paths
- Tips
- Related articles
Before you begin
Permission: Front-desk billing permissions to process gift card payments. No additional permission beyond POS (Point of Sale) access once the provider is configured for the center.
- The external gift card provider must be configured for this center. See Configure gift card provider.
- Have the guest's gift card available (physical or digital card number).
- Know whether the card belongs to the external provider or Zenoti's built-in program. The card number range or prefix typically distinguishes them. If unsure, run a balance check β it will route correctly based on card number pattern.
Network and external-system dependencies
Every operation is a live call to the provider's API. There is no offline mode for external gift cards.
- Zenoti to provider API over HTTPS (port 443) is required for every transaction.
- Provider merchant account must be active. A suspended merchant causes every card operation to fail.
- Provider clock and Zenoti clock must be reasonably synchronised β large skew can cause signed-message rejection.
Check a gift card balance
- In the POS or guest profile, select Check Gift Card Balance.
- Scan the card barcode or enter the card number manually.
- Zenoti queries the provider and displays the current balance.
Balance checks are read-only β they don't lock or modify the card. Use a balance check to confirm provider connectivity before starting a sale or redemption.
Sell a gift card
If the external provider supports Zenoti-initiated card sales:
- In the POS, open the gift card sale flow.
- Enter the card number (or activate a pre-printed card from inventory).
- Enter the sale amount (loading value).
- Complete the payment via any standard payment method.
- Zenoti sends an activation request to the provider β the card becomes live on the provider network with the specified balance.
- Hand the activated card to the guest, and provide a receipt showing the card number and activated value.
If activation fails after the payment has been taken, see Failure paths β you will need to void the pending activation on the provider side before retrying.
Redeem a gift card at checkout
- Open the invoice at the POS.
- In the Collect Payment section, select Gift Card.
- Scan or enter the card number.
- Zenoti queries the provider and displays the available balance.
- Enter the amount to apply from the card (up to balance or invoice total, whichever is lower).
- Zenoti sends a redemption request to the provider.
- The provider decrements the card balance and returns confirmation.
- Apply any remaining amount via another payment method and close the invoice.
Partial redemption is supported. Guests may split a single card across multiple invoices on different dates β each redemption is a separate call to the provider.
Refund or void a gift card transaction
Refunds and voids on external gift cards require dual-perspective action: Zenoti posts the reversal and the provider updates the card balance.
Void same-day (before batch close)
- Open the invoice at the POS.
- Select Void.
- Zenoti sends a void request to the provider.
- The provider credits the card balance back.
- The invoice shows voided status in Zenoti.
Voids generally succeed when the provider has not yet batch-closed the day's transactions. Confirm with your provider's batch-close timing.
Refund after batch close
- Open the closed invoice.
- Select Refund.
- Select the gift card payment line as the refund target.
- Zenoti sends a refund request to the provider.
- The provider credits the amount back to the same card (or issues it to a new card, depending on provider policy).
- Zenoti records a refund entry.
Provider-side behaviour (dual perspective)
| Zenoti action | What Zenoti sends | Provider records | Is manual reconciliation needed? |
|---|---|---|---|
| Void same-day | Reversal request | Cancels the redemption; card balance returns to pre-redemption value | No β provider lists transaction as voided |
| Refund post-batch | Refund request | Credits the card with a new positive adjustment entry | No, if the provider auto-confirms; yes if provider requires admin approval |
| Partial refund | Partial refund request | Credits partial value; original redemption stays in history with a refund reference | No β reflected in both systems |
| Card sale void (activation reversal) | Activation reversal | Card is deactivated on provider side; balance set to zero | Yes β confirm deactivation in the provider portal before reselling the card |
If the Zenoti reversal succeeds but the provider side does not reflect it (network failure after provider commit, for example), the two systems are out of sync. Use the provider portal to fix the card manually and log the discrepancy.
Edit or adjust across states
Invoices with gift card payments behave differently based on state:
| Invoice state | Edit action supported | Notes |
|---|---|---|
| Open invoice, gift card pending | Remove gift card line, change amount | No provider call is made until close β safe to edit freely. |
| Closed invoice, same-day | Void | Cancels gift card redemption at the provider. |
| Closed invoice, next-day or later | Refund | Creates a new refund transaction; original redemption stays in history with a linked reversal. |
| Card sale invoice (activation) | Void same-day to cancel activation; after batch close, you typically cannot un-activate | Work with the provider if a sold card must be voided after batch close. |
There is no hidden "edit in place" for closed invoices β closed state is immutable at the provider level, and Zenoti enforces the same. All adjustments after close are reverse-and-new, not edit-in-place.
Reconciliation
| Item | Zenoti side | Provider side | Match key | Cadence |
|---|---|---|---|---|
| Card sales / activations | Invoice report filtered by gift card sales | Provider activation ledger | Card number + activation timestamp | Weekly |
| Redemptions | Payment report filtered by gift card method | Provider redemption ledger | Card number + redemption timestamp | Weekly |
| Voids and refunds | POS void/refund report | Provider reversal ledger | Card number + reversal timestamp | Weekly |
| Outstanding card liability | Not directly available in Zenoti | Provider portal β outstanding balance report | Aggregate by provider | Monthly |
If the provider's report name or view differs, ask the provider merchant services team for the equivalent β provider portals vary by network.
Failure paths
| Failure mode | User-visible symptom | Resolution |
|---|---|---|
| Card balance not found | POS shows "card not recognised". | Confirm card number. If still not found, the card may be on a different network. Check with the provider. |
| Insufficient balance | POS shows "insufficient funds". | Apply available balance; collect remainder via another method. |
| Provider unreachable | POS spinner hangs, then times out. | Fail back to an alternative payment method. Do not charge the same card repeatedly. Log the attempt and reconcile later. |
| Activation failed after payment | Guest paid for a card that was not activated. | Void the payment on the payment-processor side, void the invoice, investigate the provider side. Never hand over a card without confirming activation. |
| Refund rejected by provider | Refund fails with provider error. | Check provider-side reason β expired card, wrong card number, card deactivated. Resolve with provider merchant services. |
| Card deactivated on provider side | Balance check returns error for a card guests believe is active. | Confirm card status in provider portal. Guests may need to contact provider customer service. |
| Batch-close timing mismatch | Same-day void rejected as "past batch close". | Process as refund instead. Coordinate with provider on batch-close timing to avoid recurrence. |
| Currency mismatch | Provider rejects transaction with currency error. | Check the center's currency configuration matches the provider-side configuration. |
| Network outage mid-sale | Zenoti recorded sale but provider did not activate card, or vice versa. | Use provider portal as source of truth. Manually correct Zenoti records β do not retry activation on a card that may already be live. |
Tips
- Always verify the balance before accepting a gift card payment; avoids partial failures at close.
- If the provider is unreachable, process the invoice with an alternative payment method and apply the gift card redemption through the provider's own portal later.
- Retain physical cards and receipts for voids β some providers require the card in hand to accept a refund reversal.
- Reconcile weekly during the first month after rollout; monthly thereafter.