Advanced Topics

Request ID Construction And Handling

Generation of UUIDs for voucher provision request messages is an important step in the request process. The id field of a VoucherRequest is the single field guaranteed to always allow an entity to locate all messages pertaining to a voucher request (as well as subsequent related messages). It is therefore important that the ID value generated by a client is unique for that client. If you are developing a client implementation, please take note to generate IDs as random UUID’s, as defined for a variant 4 UUID by RFC 4122. These request identifiers must uniquely identify a request within your own client implementation. If possible, the client should check that the UUID generated for a message has not been previously generated. If the UUID has been used previously then the client should generate a new UUID. This process should be repeated as necessary until a unique UUID has been generated.

This specification acknowledges that since clients produce random UUIDs, there is a possibility that a client might repeat an ID for two independent messages of the same type if the client is unable to perform the above checks. Furthermore, independent clients may submit two distinct requests with the same UUIDs. Therefore, if you are developing a server implementation, take care to verify that a request to create a resource does not contain an ID that already exists in the system. All such requests must be declined with a status code of 400 and an ErrorType of DUPLICATE_RECORD.

Finally, if a client receives an HTTP 400 response with an ErrorType of DUPLICATE_RECORD, it is suggested that the client simply generate a new UUID for the request and resubmit the request with the new UUID.

Request Matching

The manner in which messages created after an initial voucher provision request are associated with the original voucher provision request is dependent on the type of message. The Single Use Voucher Service Interface provides numerous ways to ensure any message other than a request message can be matched to the original request message.

UUID Matching

The Single Use Voucher Service Interface matches related messages primarily through the use of UUIDs. UUIDs are intended to uniquely identify a message across all client and server implementations of the Single Use Voucher Service Interface. Within any implementation of the Single Use Voucher Service Interface a given request UUID must be unique. This enables certainty that any subsequent response or advice message with the same request UUID does indeed refer to the prior request with that UUID.

Third Party Identifiers

The Single Use Voucher Service Interface recognises that while UUIDs uniquely identify a message within an implementation, an entity may choose to use a different value as a transaction identifier which is unsuitable as a UUID. Furthermore, a transaction may be processed by entities not implementing the Single Use Voucher Service Interface and the identifiers assigned by these entities may need to be persisted in messages. Thus the Single Use Voucher Service Interface defines a ThirdPartyIdentifer model which allows an entity to associate a value of its own choosing with the transaction. The collection of such values is persisted in messages pertaining to a single transaction.

This collection of ThirdPartyIdentifiers is intended to be used by entities to match any message containing a given identifier to any other message containing the same identifier within the entity’s own system. It is important to note that the sending of ThirdPartyIdentifiers does not supersede the use of UUIDs to match messages.


Matching of messages using vouchers specifically pertains to voucher confirmations. In such situations a confirmation of a voucher will directly indicate the voucher to be confirmed. This is possible since a voucher cannot be confirmed unless the originator is aware of the voucher to be confirmed. It is important to note that the use of vouchers for matching does not preclude the use of UUIDs or ThirdPartyIdentifiers for matching of messages.

Reversals vs Refunds

Reversal messages pertain specifically to voucher provision requests for which the client did not receive a final response or was not able to complete the processing of the response. Thus the client has direct knowledge of the voucher provision request to be reversed but not of the possible voucher which may have been provisioned. The client must include the original request in the reversal message. A reversal takes place immediately after a failed provision.

Refunds may take place at any time after a voucher has been provisioned and confirmed. At the time of a refund the originator may not have knowledge of the original identifiers used in the voucher provision or confirmation operations. Refunds are beyond the scope of the Single Use Voucher Service Interface.


To ensure that loss of transactional data is minimised, the Single Use Voucher Service Interface requires clients to store advice messages in persistent storage and keep them queued until a final status type is received. A final response is one of either the successful or failed status types. If the single use voucher service is not responding, or responding with an unknown status type, advice messages shall be queued and the message at the head of the queue repeated regularly until a final status type is received. For high throughput systems it shall be acceptable to send several messages in parallel. Client and server systems in high throughput environments should therefore be prepared to process advice and advice response messages in any order.

The above applies to the following operations:

  • Confirmation
  • Reversal