Puchase trial
A purchase trial forms the first phase of the direct-top airtime message flow. It is used to validate the originating entity, customer's MSISDN, and the selected product.
The purchase trial step exists to validate certain details to help ensure a successful purchase. However, it is not a hard requirement that this step returns a successful response in order to continue to the purchase request.
A typical example would be the case of the error response FUNCTION_NOT_SUPPORTED. This would be returned by the Electrum API in the case of a service provider not supporting a validation step. The originating system may then proceed directly to the purchase request.
Operations and Messages
| Transaction | Operation | API Calls |
|---|---|---|
| Purchase trial | purchaseTrial |
|
Message Flows
The sections below describe a successful purchase trial and possible error scenarios.
Successful Purchase Trial
See 'Validation Phase' of the diagram below.
- The originating system sends a
POSTcall to the/purchases/trialsAPI endpoint. - The API responds with an HTTP status of
200and a PurchaseResponse payload. - The consumer can decide whether or not to proceed with tender and an actual purchase.
Error at Originating System
- The originating system sends a
POSTcall to the/purchases/trialsAPI endpoint. - An error occurs at the originating system, or a timeout occurs when the originating system does not receive a response.
- No further messaging is required.
Error Upstream
- The originating system sends a
POSTcall to the/purchases/trialsAPI endpoint. - An error occurs at Electrum or the service provider.
- The API returns an HTTP status of
400,500,503or504and an ErrorDetail message payload. - No further messaging is required. Depending on the nature of the error, the originating system can retry the trial purchase, abort the transaction, or proceed to an airtime purchase after tender by the consumer.
- In general, an HTTP status
400indicates that the request failed permanently and cannot be retried without changing the message content. - HTTP statuses in the
5xxrange are typically temporary system or communication failures, in which case the transaction can be retried. - An error of
TRANSACTION_NOT_SUPPORTEDindicates that the service provider does not support purchase trials. The originating system can proceed to a purchase transaction.
