Advanced Topics

Message ID Construction And Handling

Generation of UUIDs for bill payment 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 bill payment 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 Billpay 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 Billpay 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 Billpay Service Interface. Within any implementation of the Billpay 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 Billpay 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 Billpay Service Interface and the identifiers assigned by these entities may need to be persisted in messages. Thus the Billpay 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.


To ensure that loss of transactional data is minimized, the Billpay 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 bill pay 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.