{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-vas/vas.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Purchase","llmstxt":{"hide":false,"sections":[{"title":"Table of contents","includeFiles":["**/*"],"excludeFiles":[]}],"excludeFiles":[]}},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The purchase phase of a direct top-up purchase follows the validation phase."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":1,"id":"purchase"},"children":["Purchase"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Before a purchase request can be made, a successful payment for the requested product must be tendered. This is because reversals are not supported for direct top-up purchases and hence any airtime products issued cannot be reversed in the case of a failed tender."]}]},{"$$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":"Opedration"},"children":["Opedration"]},{"$$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"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/other/purchase"},"children":["purchase"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["POST /purchases"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Request payload: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/purchaserequest"},"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":["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":["ErrorDetail"]}]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Purchase status lookup"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/other/purchasestatus"},"children":["purchaseStatus"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET /purchases/status"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Response payload: ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/purchaseresponse"},"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":["ErrorDetail"]}]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["You should not attempt transaction lookups until after the initial processing period concludes (after Electrum has received and processed the transaction outcome)."]}]},{"$$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 and possible error scenarios. The table of error types lists the full set of possible error types and the action required should they occur."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If the error indicates a permanent failure, then the consumer should be informed via the relevant channel (i.e., mobile, web, or point of sale), and tender should be reversed."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"successful-airtime-purchase"},"children":["Successful Airtime Purchase"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Refer to 'Purchase Phase' in the diagram below."]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After a purchase trial transaction, the consumer tenders for a purchase transaction (no Electrum involvement)."]},{"$$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"]}," API endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The API responds with an HTTP status of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["201"]}," and a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/purchaseresponse"},"children":["PurchaseResponse"]}," message payload."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The consumer receives the airtime top-up directly to their cellphone."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/successful-dta-purchase-1.998d1c99d693f8a037d35a25b49740cd544b4abacb593ddbf2e2e11554b7673a.25fce2f6.png","alt":"alt text"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-upstream-purchase-failed"},"children":["Error Upstream: Purchase Failed"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After a purchase trial transaction, the consumer tenders for a purchase transaction (no Electrum involvement)."]},{"$$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"]}," API endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An error occurs at Electrum or the service provider."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Electrum returns an ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/errordetail"},"children":["ErrorDetail"]}," payload indicating that the purchase has failed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The consumer is notified of the error and the tender is reversed."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/error-upstream-during-purchase.03e1040ac99e8d34c545dfb5869f3d7cf0cc5b58b875676f4d0284c475a793fd.25fce2f6.png","alt":"alt text"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-upstream-unknown-outcome"},"children":["Error Upstream: Unknown Outcome"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After a purchase trial transaction, the consumer tenders for a purchase transaction (no Electrum involvement)."]},{"$$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"]}," API endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An error occurs when Electrum does not receive a response or receives a response that the transaction is still being processed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Electrum returns an error of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPSTREAM_UNAVAILABLE"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OUTCOME_UNKNOWN"]}," to the originating system."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The originating system requests the status of the original transaction by sending a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," call to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/purchases/status"]}," endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If Electrum receives a response regarding the transaction status from the service provider, then Electrum will return a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/purchaseresponse"},"children":["PurchaseResponse"]}," (approved) or ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/errordetail"},"children":["ErrorDetail"]}," (declined) response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The consumer is informed of the transaction outcome. Tender is reversed in the event of a failed transaction."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/unknown-outcome-during-dta-purchase.93111ca7c4aa1721acb98ea6a60e367c54ac8ec2c657a7cec46e9e32a821ccde.25fce2f6.png","alt":"alt text"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-upstream-unknown-outcome-and-lookups-fail"},"children":["Error Upstream: Unknown Outcome and Lookups Fail"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After a purchase trial transaction, the consumer tenders for a purchase transaction (no Electrum involvement)."]},{"$$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"]}," API endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An error occurs when Electrum does not receive a response or receives a response that the transaction is still being processed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Electrum returns an error of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPSTREAM_UNAVAILABLE"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OUTCOME_UNKNOWN"]}," to the originating system."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The originating system requests the status of the original transaction by sending a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," call to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/purchases/status"]}," endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Electrum still does not receive a response or receives a response that the transaction is still being processed."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Electrum returns an error of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPSTREAM_UNAVAILABLE"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OUTCOME_UNKNOWN"]}," to the originating system."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The originating system can choose to initiate another purchase status lookup or abort the transaction."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/unknown-outcome-lookups-fail-during-dta-purchase.47d3e9bbaf85c184d44b7e92cc12a00f4e040d9345819b9152182368aa6bdff1.25fce2f6.png","alt":"alt text"},"children":[]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"error-or-timeout-at-originating-system"},"children":["Error or Timeout at Originating System"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["After a purchase trial transaction, the consumer tenders for a purchase transaction (no Electrum involvement)."]},{"$$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"]}," API endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["An error occurs at the originating system, or a timeout error occurs when the originating system does not receive a response."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The originating system requests the status of the original transaction by sending a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["GET"]}," call to the ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/purchases/status"]}," endpoint."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If Electrum receives a response regarding the transaction status from the service provider, then Electrum will return a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/purchaseresponse"},"children":["PurchaseResponse"]}," (approved) or ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema/errordetail"},"children":["ErrorDetail"]}," (declined) response. The consumer is informed of the transaction outcome and tender is reversed in the event of a failed transaction."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If Electrum does not receive a response, or receives a response that the transaction is still being processed, then Electrum will return an error of ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["UPSTREAM_UNAVAILABLE"]}," or ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["OUTCOME_UNKNOWN"]}," to the originating system. The originating system can choose to initiate another purchase status lookup or abort the transaction."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"img","attributes":{"src":"/assets/error-or-timeout-at-os-during-dta-purchase.7b7bfe74c50ee4194fb7eced695bd74fe2396747607c547f859db8958dba6447.25fce2f6.png","alt":"alt text"},"children":[]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["There is no explicit restriction on the number of purchase status lookup attempts that may be performed before the transaction should be aborted."]}]}]},"headings":[{"value":"Purchase","id":"purchase","depth":1},{"value":"Operations and Messages","id":"operations-and-messages","depth":2},{"value":"Message Flows","id":"message-flows","depth":2},{"value":"Successful Airtime Purchase","id":"successful-airtime-purchase","depth":2},{"value":"Error Upstream: Purchase Failed","id":"error-upstream-purchase-failed","depth":2},{"value":"Error Upstream: Unknown Outcome","id":"error-upstream-unknown-outcome","depth":2},{"value":"Error Upstream: Unknown Outcome and Lookups Fail","id":"error-upstream-unknown-outcome-and-lookups-fail","depth":2},{"value":"Error or Timeout at Originating System","id":"error-or-timeout-at-originating-system","depth":2}],"frontmatter":{"seo":{"title":"Purchase"}},"lastModified":"2026-01-28T10:41:29.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/vas/public/airtime-direct-top-up/purchase","userData":{"isAuthenticated":false,"teams":["anonymous"]}}