{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-vas/vas.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Puchase trial","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"puchase-trial"},"children":["Puchase trial"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A typical example would be the case of the error response ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"operations-and-messages"},"children":["Operations and Messages"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Transaction"},"children":["Transaction"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Operation"},"children":["Operation"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"API Calls"},"children":["API Calls"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Purchase trial"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/other/purchasetrial"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["purchaseTrial"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST/purchases/trials"]},":"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request payload: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/purchaserequest"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PurchaseRequest"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Response payload: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/purchaseresponse"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["PurchaseResponse"]}]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Error payload: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/errordetail"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["ErrorDetail"]}]}]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"message-flows"},"children":["Message Flows"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The sections below describe a successful purchase trial and possible error scenarios."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"successful-purchase-trial"},"children":["Successful Purchase Trial"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["See 'Validation Phase' of the diagram below."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The originating system sends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," call to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/purchases/trials"]}," API endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The API responds with an HTTP status of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," and a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/purchaseresponse"},"children":["PurchaseResponse"]}," payload."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The consumer can decide whether or not to proceed with tender and an actual purchase."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/successful-dta-purchase.5458b246603255baf90abae47309e221201ae62a6dd938b73e021341fc8f8538.25fce2f6.png","alt":"alt text"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-at-originating-system"},"children":["Error at Originating System"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The originating system sends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," call to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/purchases/trials"]}," API endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An error occurs at the originating system, or a timeout occurs when the originating system does not receive a response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["No further messaging is required."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/error-at-os-during-validation-phase-updated..2c12510a26b4a937e665126c05dcc837669e7eeca8b32d1f16b3a4afbe3cc7a6.25fce2f6.png","alt":"alt text"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-upstream"},"children":["Error Upstream"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The originating system sends a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST"]}," call to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/purchases/trials"]}," API endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An error occurs at Electrum or the service provider."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The API returns an HTTP status of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["500"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["503"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["504"]}," and an ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/errordetail"},"children":["ErrorDetail"]}," message payload."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["In general, an HTTP status ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["400"]}," indicates that the request failed permanently and cannot be retried without changing the message content."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HTTP statuses in the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["5xx"]}," range are typically temporary system or communication failures, in which case the transaction can be retried."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An error of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["TRANSACTION_NOT_SUPPORTED"]}," indicates that the service provider does not support purchase trials. The originating system can proceed to a purchase transaction."]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/error-upstream-during-validation-phase.a5b9d5390db46b26e75bb20d0cfc2c8c735daeb39df3070674fd543ca5ded9b8.25fce2f6.png","alt":"alt text"},"children":[]}]}]},"headings":[{"value":"Puchase trial","id":"puchase-trial","depth":1},{"value":"Operations and Messages","id":"operations-and-messages","depth":2},{"value":"Message Flows","id":"message-flows","depth":2},{"value":"Successful Purchase Trial","id":"successful-purchase-trial","depth":3},{"value":"Error at Originating System","id":"error-at-originating-system","depth":2},{"value":"Error Upstream","id":"error-upstream","depth":2}],"frontmatter":{"seo":{"title":"Puchase trial"}},"lastModified":"2026-01-28T10:41:29.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/vas/public/airtime-direct-top-up/purchase-trial","userData":{"isAuthenticated":false,"teams":["anonymous"]}}