Single Use Voucher Service Interface Release Notes
v1.23.0 - 18 November 2022
New Features
Added
ChannelProductListing
model.
Add the following fields to the
product
model:
isFixedValue
channelProductListings
receiver
v1.22.0 - 19 October 2022
New Features
Added
LIMIT_EXCEEDED
as an error type to use in
ErrorDetail
responses.
v1.21.0 - 03 October 2022
New Features
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
New Features
The
Product
model has been updated to include optional
LedgerAmount
fields:
minAmount
and
maxAmount
.
v1.19.0 - 11 August 2022
Breaking Changes
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 - see V1.19.0) - 13 July 2022
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
RewardPaymentPaymentMethod
.
Added
AccountPaymentMethod
.
Added
amounts
field to the
BasicAdvice
model to support partial reversals and partial confirmations.
v1.10.0 (Deprecated - see V1.11.0) - 19 June 2020
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 - see V1.11.0) - 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) - 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
.
v1.7.0 (Deprecated - see V1.11.0) - 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 - 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