Guides
Start typing to search…

Smart Voucher Payments

The SMART_VOUCHER payment method allows customers to make payments using prepaid codes, gift vouchers, or printed PINs. This solution is widely adopted in:

  • Unbanked regions: Enables participation in digital commerce without bank accounts.
  • Retail-to-online transitions: Allows customers to use retail-purchased codes online.
  • Gaming and top-up services: Popular for in-game credits and prepaid top-ups.

This method abstracts complex integrations with multiple voucher providers, offering a single, unified API for merchants to support diverse voucher systems effortlessly.

Use Cases

  • Redeeming gift cards for online purchases.
  • Using retail-issued top-up codes for account recharges.
  • Processing government subsidy vouchers for benefits distribution.
  • Bridging offline-to-online payments, e.g., kiosk-issued PINs used in digital platforms.

Request Payload: SmartVoucherPayload

FieldTypeRequired?Description
paymentMethodApmMethodYesMust always be set to SMART_VOUCHER.
paymentTypeApmFlowTypeYesMust always be VOUCHER.
voucherCodeStringRequiredUnique alphanumeric code printed on or linked to the voucher.
voucherExpirationDateStringOptionalExpiration date of the voucher in ISO 8601 format (e.g., 2025-12-31).
💡

Note: The voucherCode must be a valid code issued by a supported voucher provider.

Response Payload: SmartVoucherResponseData

FieldTypeRequired?Description
paymentMethodApmMethodYesAlways returns SMART_VOUCHER.
paymentTypeApmFlowTypeYesAlways returns VOUCHER.
redirectUrlStringOptionalURL where the customer can complete voucher redemption on the provider’s site (if applicable).
iframeUrlStringOptionalURL for embedding the voucher redemption flow via iframe (if supported).
providerTransactionIdStringRequiredUnique reference ID for the transaction, returned by the voucher provider.
voucherBalanceStringOptionalRemaining or redeemed monetary value of the voucher.
sessionTokenStringOptionalToken for tracking session status or enabling transaction polling.
voucherMetadataMap<String, String>OptionalAdditional voucher provider data (e.g., currency, issuer info, channel).
voucherCodeStringOptionalEchoed voucher code from the provider or transaction response.
voucherExpirationDateStringOptionalExpiration date of the voucher, as returned by the provider.

Best Practices

  • Validate voucher codes: Ensure correct format and issuance before initiating payment.
  • Handle expiration dates: Use voucherExpirationDate to inform users and prompt alternative actions if expired.
  • Display remaining balance: Show voucherBalance for top-up or reusable vouchers to improve UX.
  • Leverage metadata: Use voucherMetadata for reconciliation, adding issuer branding, or generating detailed reports.
  • Embed via iframe: Prefer iframeUrl for smoother, in-app redemption experiences without redirecting users externally.

Updated 8 days ago