🎟️ Smart Voucher (SMART_VOUCHER)
SMART_VOUCHER)Overview
SMART_VOUCHER enables payments using prepaid codes, gift vouchers, or printed PINs, often popular in:
- Unbanked regions
- Retail-to-online transitions
- Gaming and top-up services
This method abstracts integrations with various voucher providers, allowing merchants to support multiple voucher systems through a single, unified API.
🧾 Use Cases
- Gift card redemption
- Retail-issued top-up codes
- Government subsidy vouchers
- Offline-to-online bridging (e.g., kiosk to digital)
📨 Request: SmartVoucherPayload
SmartVoucherPayload| Field | Type | Required? | Description |
|---|---|---|---|
paymentMethod | ApmMethod | Yes | Always SMART_VOUCHER |
paymentType | ApmFlowType | Yes | Always VOUCHER |
voucherCode | String? | ✅ Required | Unique code printed on or associated with voucher |
voucherExpirationDate | String? | Optional | Expiration in ISO 8601 format (e.g., 2025-12-31) |
You must provide a validvoucherCodeissued by a supported provider.
📥 Response: SmartVoucherResponseData
SmartVoucherResponseData| Field | Type | Required? | Description |
|---|---|---|---|
paymentMethod | ApmMethod | Yes | Always SMART_VOUCHER |
paymentType | ApmFlowType | Yes | Always VOUCHER |
redirectUrl | String? | Optional | If needed, URL to complete redemption on provider site |
iframeUrl | String? | Optional | Iframe-embeddable version of the redemption flow (if supported) |
providerTransactionId | String | ✅ Required | Transaction reference returned by voucher provider |
voucherBalance | String? | Optional | Remaining or redeemed value of the voucher |
sessionToken | String? | Optional | Token to track session or enable polling |
voucherMetadata | Map<String, String>? | Optional | Extra provider data (e.g., currency, channel, issuer) |
voucherCode | String? | Optional | Echoed voucher code |
voucherExpirationDate | String? | Optional | Expiration date from provider |
✅ Best Practices
- 🔑 Always validate the voucher code format before submission.
- 📆 Use
voucherExpirationDateto guide user experience or fallback prompts. - 💳 Surface
voucherBalancein the UI if top-up or multi-use vouchers are supported. - 🧾 Use
voucherMetadatafor reconciliation, UX hints (e.g., issuer logo), or reporting. - 📡 Prefer iframe integration (
iframeUrl) for smoother embedded experiences.