Advanced Topics

Request ID Construction And Handling

Generation of UUIDs for request 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 the 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 on the type of message. The Money Transfer Retailer Interface provides numerous ways to ensure any message other than a request message can be matched to the original request message.

UUID Matching

The Money Transfer Retailer 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 Money Transfer Retailer Interface. Within any implementation of the Money Transfer Retailer 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 Money Transfer Retailer 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 Money Transfer Retailer Interface and the identifiers assigned by these entities may need to be persisted in messages. Thus the Money Transfer Retailer 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.

Reversals vs Refunds

Reversal messages pertain specifically to 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 request to be reversed. 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 request has been approved and confirmed. At the time of a refund the originator may not have knowledge of the original identifiers used in the request or confirmation operations. Refunds are beyond the scope of the Money Transfer Retailer Interface.


To ensure that loss of transactional data is minimized, the Money Transfer Retailer 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 Money Transfer Retailer Interface 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