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 VoucherReqeust or PurchaseRequest 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 linked messages created after an initial request are associated with the original request is dependent on the type of message. The Airtime 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 Airtime 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 Airtime Service Interface. Within any implementation of the Airtime 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 Airtime 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 Airtime Service Interface and the identifiers assigned by these entities may need to be persisted in messages. Thus the Airtime 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 may 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 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 original request to be reversed but not of the possible airtime product which may have been provided. The client must include the UUID of the original request in the reversal message. A reversal takes place immediately after a failed request.

Refunds may take place at any time after an airtime product has been successfully sold and confirmed. At the time of a refund the originator may not have knowledge of the original identifiers used in the sale or confirmation operations. Refunds are beyond the scope of the Airtime Service Interface.


To ensure that loss of transactional data is minimized, the Airtime 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 airtime 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

Purchase Status Checks

It is highly recommended that a reversal mechanism is implemented to allow failed airtime purchases to be successfully reversed. However, if a reversal cannot be implemented then a purchase status check mechanism must be provided. This allows the status of a prior purchase to be queried so that the merchant may determine the outcome of the airtime purchase.