Release Notes

This page describes changes to the Single Use Voucher Service Interface implemented across different releases of the interface.

v1.13.0

Released 07 December 2020

  • Updated the RefundRequest model to support refunds of non-unique vouchers by including redemption transaction references in the model.
  • Updated base service interface version from v3.27.0 to v3.28.0:
    • Added operatorId field to the Originator model.

v1.12.0

Released 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

Released 03 August 2020

  • Corrects breaking changes introduced in v1.7.0 and v1.8.0 of the API.
    • Summary: newer implementations of the lookupVoucher operation will call the previous implementation of the lookupVoucher operation by default.
    • These changes (the original breaking changes as well as the corrections) only affect the Java implementation of the API as provided by Electrum. They do not affect the API as defined by the supplied swagger.
    • v1.7.0 and v1.8.0 introduced changes to the lookupVoucher operation. By default, these changes would return error responses when attempting to call the updated implementation of the lookupVoucher operation.
    • However, the updated implementation also became the default implementation used when performing the lookupVoucher operation.
    • This was because the updated implementation assumed ownership of the JAX-RS properties.
    • Thus, existing implementations of the API would unexpectedly use the newest implementation of the lookupVoucher operation which returns error responses.
    • The Java implementation has been corrected to use the prior implementation of the lookupVoucher operation as the default behaviour of the newer implementations.
  • Updated base service interface version from v3.24.0 to v3.27.0:
    • Added a RewardPayment PaymentMethod.
    • Provided testing utilities to aid API development in the Java implementation provided by Electrum.
    • Added Account PaymentMethod.
    • Added HasAmounts and HasPaymentMethods interfaces. These can be used for creating shared utilities across API implementations.
    • Added amounts field to the BasicAdvice model to support partial reversals and partial confirmations.

v1.10.0 (Deprecated - see V1.11.0)

Released 19 June 2020

  • Updated base service interface version from v3.21.0 to v3.24.0.
    • Added support for hashed PINs (via a new sub-type of Pin named HashedPin).
    • Added utility methods to JsonUtil class to assist in reading the contents of a file as a string and deserialising JSON objects from files.
    • 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 - see V1.11.0)

Released 22 May 2020

  • 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 - see V1.11.0)

Released 13 May 2020

  • 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.
  • Fixed a break to the Java implementation introduced in v1.7.0:
    • A new method was introduced in the IVouchersResource class with no default implementation. A default implementation has been provided which will throw a java.lang.UnsupportedOperationException.

v1.7.0 (Deprecated - see V1.11.0)

Released 06 May 2020

  • 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

Released 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.
    • Note, this change is a breaking change for the Java implementation of the API provided by Electrum:
    • The RELATIVE_PATH and FULL_PATH constants for the following operations have changed and no longer end with a trailing forward slash:
      • lookupVoucher
      • provisionVoucher
      • redeemVoucher
      • refundVoucher
  • The Jetty Server dependency was deemed unnecessary and removed. The Javax Servlet API (v3.1.0) is instead required to be available in the runtime environment.

v1.5.0

Released 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.
  • Updated base service interface version from v3.17.0 to v3.21.0
    • 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

Released 17 January 2019

  • Update base service interface version from v3.16.0 to v3.17.0
    • Added stan to Transaction and BasicAdvice models
    • Added rrn to Transaction and BasicAdvice models

v1.3.0

Released 07 January 2019

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

v1.2.0

Released 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

Released 28 November 2018

  • Added @Valid and @NotNull annotations to resources, which allows the object to be recursively validated.

v1.1.0

Released 24 October 2018

  • Added VoucherTransaction interface and implemented it in all provision, redemption and refund models
  • Update base service interface version from v3.8.1 to v3.16.0.
    • 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 utility for HTTP authentication
    • Added JAVA 8 Times
    • Added VasMessage interface such that Transaction and BasicAdvice implement.
    • Added utility for serialising and deserialing JSON objects
    • Added EncryptedPin class
    • Added CARD_HOLDER_INQUIRY and POINTS_INQUIRY to TranType

v1.0.0

Released 16 May 2018

Initial release