Single Use Voucher Service Interface Release Notes

v1.24.0 - 01 October 2024

  • Added a customer field to RedemptionRequest and RedemptionResponse class.

v1.23.0 - 18 November 2022

  • Added ChannelProductListing model.
  • Add the following fields to the product model:
    • isFixedValue
    • channelProductListings
    • receiver

v1.22.0 - 19 October 2022

  • Added LIMIT_EXCEEDED as an error type to use in ErrorDetail responses.

v1.21.0 - 03 October 2022

  • Validation for description property of the Product model has been changed to permit all characters up to a length of 250. Previously, it was validated to only include alphanumeric characters and the "-" character up to 100 characters.

v1.20.0 - 05 September 2022

  • The Product model has been updated to include optional LedgerAmount fields: minAmount and maxAmount .

v1.19.0 - 11 August 2022

  • The retryProvisionRequest operation has been updated to have a ProvisionRequest payload. The previously used RetryProvisionRequest model is now unneeded and has been removed.
  • v1.18.0 was not in use anywhere at the time of its deprecation and so backwards compatibility need not be maintained.

v1.18.0 (Deprecated) - 13 July 2022

Deprecated, see v1.19.0.

  • The Product model now includes a String description field.
  • The following enums were added to the ErrorDetail model in order to carry through possible errors encountered on the payment leg. The purpose of these error types are to provide more suitable mappings for error types found in the payments service interface:
    • INSUFFICIENT_FUNDS
    • INVALID_ACCOUNT
    • TRANSACTION_DECLINED
  • Added the concept of a recipient to the ProvisionRequest and ProvisionResponse that consists of a Customer object. See the description below:
    • Details of the customer who will receive and make use of the voucher requested. In cases where the customer provisioning the request is doing so on another’s behalf, it may be necessary to capture the relevant personal details of the voucher recipient.
  • Added a new operation retryProvisionRequest and associated model RetryProvisionRequest that contains the following fields:
    • retryId
    • originalRequest

v1.17.0 - 03 May 2022

  • Non-functional refactoring.

v1.16.0 - 27 January 2022

  • Added a new Products resource to manage products. It currently supports the following operation:
    • listProducts ( HTTP GET /products ). This returns a list of available products.
  • Added an amount field to the Product model.
  • Increased the length of productId to 40
  • Updated the ProvisionRequest to include a customer fields of type Customer which will include details regarding the customer provisioning the voucher.

v1.15.0 - 27 September 2021

  • Updated ErrorDetail.ErrorType to include the following new values:
    • OUT_OF_STOCK
    • INVALID_PRODUCT
  • Updated the VoucherLookupResponse model to include the rrn and thirdPartyIdentifiers fields.

v1.14.0 - 22 April 2021

  • Updated the following models to include a posInfo field of type PosInfo which describes the circumstances of the terminal or device where the transaction was initiated:
    • ProvisionRequest
    • ProvisionResponse
    • RedemptionRequest
    • RedemptionResponse
    • RefundRequest
    • RefundResponse

v1.13.0 - 07 December 2020

  • Updated the RefundRequest model to support refunds of non-unique vouchers by including redemption transaction references in the model.
  • Added operatorId field to the Originator model.

v1.12.0 - 19 August 2020

  • Updated ErrorDetail.ErrorType to include the following new value:
    • VOUCHER_STATUS_UNKNOWN - This errorType is shown when upstream has indicated that they cannot resolve the exact status of a requested voucher.

v1.11.0 - 03 August 2020

  • Added a RewardPayment PaymentMethod .
  • Added Account PaymentMethod .
  • Added amounts field to the BasicAdvice model to support partial reversals and partial confirmations.

v1.10.0 (Deprecated) - 19 June 2020

Deprecated, see v1.11.0.

  • Added support for hashed PINs (via a new sub-type of Pin named HashedPin ).
  • Added new field region to BankAccount model for scenarios where the routingCode is not sufficient to uniquely identify a bank account.
  • Added new field emailAddress to Customer model.

v1.9.0 (Deprecated) - 22 May 2020

Deprecated, see v1.11.0.

  • Added a new lookupRedemption operation ( HTTP GET /redemptions/{requestId} ) which allows a caller to receive the result of a prior redemption request.

v1.8.0 (Deprecated) - 13 May 2020

Deprecated, see v1.11.0.

  • Updated the Voucher model with the following new, optional, fields:
    • pin which is a secret value that is required to be provided by a customer when redeeming the voucher using the code. Use of a PIN in addition to the voucher code adds security to the voucher redemption process.
    • serialNumber which can be used to identify the voucher in the vendor's system but cannot be used to redeem the voucher.
  • The restrictions on the Voucher.code field have been relaxed to allow any String up to a length of 40 characters. This allows support for a wider range of voucher codes.
  • Updated the lookupVoucher operation to accept a new optional query parameter: voucherSerialNumber .

v1.7.0 (Deprecated) - 06 May 2020

Deprecated, see v1.11.0.

  • Updated the lookupVoucher operation with the following changes:
    • Added a new provisionRequestId query parameter. This will allow a voucher to be looked up using the original provisionVoucher request ID that was used to provision that voucher.
    • Made the voucherCode query parameter optional. This was done as a voucher can now also be looked up using the provisionRequestId parameter hence the voucherCode does not always need to be sent for lookupVoucher calls.

v1.6.0 - 11 March 2020

  • Dropped a trailing forward slash from operation paths. The trailing forward slash implied operations were performed against groups of resources when they were intended to act on a single resource within the group.

v1.5.0 - 13 September 2019

  • Corrected repetition of API base path.
    • Note This is breaking change to the API but is not treated as such. Previously the API defined paths to operations as /suv/v1/suv/v1/{operation} when they should have been of the more simple form /suv/v1/{operation} . Changing the API base path in this manner would typically be a breaking change and would be reflected as such by bumping the major version number in the URL from v1 to v2 . However, all known projects depending on the Single Use Voucher Service Interface are already implemented using the simpler base path of /suv/v1/{operation} . Thus the decision was made to transparently fix the base path repetition bug as a minor version update as this was deemed to be a less disruptive change to all known projects.
  • Added new lookupVoucher operation.
  • Added Product field to ProvisionRequest and ProvisionResponse models.
  • Added new field emailAddress to Customer model.
  • Added new Account.AccountType value CASH_PICKUP for cash pickup scenarios.
  • Changed masking of CardPayment.pan field to partial masking instead of full masking.
  • Added new models:
    • Pin a base PIN model
      • PinClear for PINs in the clear
      • PinEncrypted for encrypted PIN blocks with the PIN block format, accountNumber and the key index
  • Pin was added to CardPayment , taking precedence over the existing encyptedPin field
  • Added new models:
    • ExchangeRate to describe the exchange rate between two currencies.
    • Account to describe more varied accounts in a consistent manner. This has the following sub-types defined:
    • BankAccount
    • IbanAccount
    • IfsAccount
    • SwiftAccount
    • MobileWalletAccount
  • The limitations on the id field of the Institution model have been removed to make the field suitable for a wider range of applications. The values in this field need no longer be defined by Electrum and similar values as recognised at third parties may now be carried in this field. However, care should be taken during implementation to ensure that different parties agree on the values which will be present in these fields.
  • Added explicit fields for STAN and RRN values to BasicAdvice and Transaction models.

v1.4.0 - 17 January 2019

  • Added stan to Transaction and BasicAdvice models
  • Added rrn to Transaction and BasicAdvice models

v1.3.0 - 07 January 2019

  • Updated ErrorDetail.ErrorType to include more specific values:
    • Added INSUFFICIENT_AMOUNT

v1.2.0 - 11 December 2018

  • Updated ErrorDetail.ErrorType to include more specific values:
    • Added VOUCHER_ALREADY_CONFIRMED
    • Added VOUCHER_ALREADY_REVERSED
    • Added VOUCHER_ALREADY_REFUNDED
    • Added VOUCHER_NOT_REFUNDED
    • Added VOUCHER_NOT_REDEEMED
    • Added REDEMPTION_ALREADY_CONFIRMED
    • Added REDEMPTION_NOT_CONFIRMED
    • Added REDEMPTION_ALREADY_REVERSED
    • Added REFUND_ALREADY_CONFIRMED
    • Added REFUND_ALREADY_REVERSED

v1.1.1 - 28 November 2018

  • Non-functional refactoring.

v1.1.0 - 24 October 2018

  • Added PosConditionCode and included it in PosInfo
  • Added msisdn to Customer
  • Added PaymentMethod subtype CardPayment
  • Added PaymentMethod subtype An32TokenPayment
  • Added dateOfBirth and status field to Customer model
  • Added EncryptedPin class
  • Added CARD_HOLDER_INQUIRY and POINTS_INQUIRY to TranType

v1.0.0 - 16 May 2018

  • Initial release
Copyright © Electrum Payments (Pty) Ltd. 2025. All rights reserved.