Advanced Topics

Message ID Construction And Handling

Generation of UUIDs for gift card messages is an important step in the request process. The “id” field of a request is the single field guaranteed to always allow an entity to locate all messages pertaining to a gift card 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 request are associated with the original request is dependent the exact nature of the matching required. The Giftcard 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 Giftcard 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 Giftcard Service Interface. Within any implementation of the Giftcard 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 Giftcard 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 Giftcard Service Interface and the identifiers assigned by these entities may need to be persisted in messages. Thus the Giftcard 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.

Store-and-forward

To ensure that loss of transactional data is minimized, the Giftcard 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 gift card 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:

• confirmations
• reversals

Balance vs Available Balance

The Giftcard Service Interface recognises that a gift card issuer may not permit a customer to redeem the full balance of funds associated with a gift card until all requests to load funds have been finalised. Due to the nature of store-and-forward messaging it is expected that while load and redemption requests are immediately processed their associated confirmations and reversals may only become apparent to the gift card issuer some time later - perhaps after other load and redemption requests have had to be processed. Thus the Giftcard Service Interface makes provision for two balances to be associated with a gift card: - The available balance representing the total sum of funds associated with the gift card which the customer may redeem. - The book balance representing the anticipated sum of funds associated with the gift card which will be available once all outstanding requests have been finalised. The difference between these two balances becomes apparent when considering the effect of loads and redemptions upon these balances. A load request would reflect immediately upon the book balance but will only be applied to the available balance once the associated confirmation has been processed. This prevents a customer from redeeming funds which have been loaded but may still be reversed. A redemption request would immediately diminish both the available balance and the book balance. Thus a customer cannot redeem against funds which have already been used in another redemption.