{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-vas/vas.sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Design considerations","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":"design-considerations"},"children":["Design considerations"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["A number of business and technical decisions must be made before integrating with the Electrum Direct Top-Up Airtime Service. The outcome of these decisions will impact the design of the originating system, and how the Electrum platform needs to be configured. The following sections outline various items that need to be considered with respect to ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"#online-transaction-processing"},"children":["online transaction switching"]}," and ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/vas/public/electrum-console/electrum-finance/electrum-finance-overview-ec"},"children":["back-office processing"]},". For further details of the product features and available options, read the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/vas/public/airtime-direct-top-up/direct-top-up-airtime-overview"},"children":["Product Overview"]}," page."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once the design decisions have been made, these need to be documented and shared with Electrum in a Business Requirements Document."]}]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Your design may require support for an option that is not specified here, for example, an additional service provider, payment provider, or routing rule. If this is the case, then raise a feature request with Electrum to facilitate the necessary development."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"online-transaction-processing"},"children":["Online Transaction Processing"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["The table below summarises the choices that determine how the Electrum Switch is configured for processing requests from an originating system in real time."]},{"$$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":"Feature"},"children":["Feature"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Options"},"children":["Options"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Decisions and Actions"},"children":["Decisions and Actions"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Service providers"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Mobile Mart"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Huge"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Lesaka"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Blue Label Telecoms"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["SwitchOne"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Decide which service providers you wish to transact with."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Discuss commercial agreements directly with the selected service providers."]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Channels"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Point of sale (POS)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Digital"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Decide which transaction initiation channels you will be supporting."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Ensure your channel development teams are familiar with the ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/schema"},"children":["Electrum Airtime Service Interface"]}," and ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/vas/public/airtime-direct-top-up/implementing-your-direct-top-up-airtime-solution"},"children":["implementation guidelines"]},"."]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Product list (catalogue)"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["You can maintain your list of available products through Electrum's catalogue management feature or you can use your own catalogue system."]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Decide on whether you want to manage your product list via Electrum's catalogue management feature."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If you decide to use Electrum's catalogue then you will need to implement list product transactions."]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Purchase confirmations"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The originating system sends a purchase confirmation message to finalise each transaction."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["The originating system does not send a purchase confirmation, and the transaction is considered final after the purchase leg has been completed."]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Decide if your business processes require that the originating system finalises transactions with a purchase confirmation."]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Routing"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Routing via product ID"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Routing via the Mobile Network Operator (MNO)"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Decide on at least one routing strategy which best suits your business needs."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If more than one routing rule is chosen, then specify the order of preference in which they should be applied."]}]}]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Connectivity and security"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HTTPS using basic authentication or OAuth2"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["HTTPS using basic authentication or OAuth2 with mTLS1.2+"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Connection via VPN"]}]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Decide on which method you wish to use for securing communication between the originating system and the Electrum API."]}]}]}]}]}]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"electrums-catalogue-management"},"children":["Electrum's Catalogue Management"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["It is important to maintain an up-to-date catalogue listing the full array of airtime products offered, especially where there are many products offered by one or more service providers."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Electrum can help you set up your initial product catalogue. The catalogue lists the full range of airtime products and their associated codes, and also indicates the mappings where a single product has different client and service provider product codes."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["If there are changes to the product list (e.g., a service provider adds additional products to their offering and you want to offer these to your customers) the service provider can notify you. You can access your catalogue via the Electrum Console and make changes as required."]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["In order for you to retrieve your built-in list of products, you will need to perform a ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"https://docs.electrumsoftware.com/openapi/airtime/swagger/other/listproducts"},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["listProducts"]}]}," call. This can be done frequently or infrequently depending on circumstances:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If your system is not able to save the catalogue, then you will need to perform the call each time you need to access the catalogue."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If there are frequent updates to the product list then you will need to perform this call frequently to ensure you have the latest product list."]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["If the product list has not changed and your system is able to save the catalogue then you do not need to perform this call again – you can simply refer to the stored catalogue."]}]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"electrum-finance"},"children":["Electrum Finance"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Processes that happen after transactions have been completed in real time include reconciliation, reporting, and settlement. The items below need to be considered to inform how Electrum Finance is configured for handling these processes:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Input file specifications for transaction matching"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Transaction matching rules"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Reporting requirements"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Details of the parties involved in each process"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Time-based rules (e.g., reconciliation period, automatic exception resolution, transaction expiry)"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":["Settlement posting requirements to finance system"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Ensure that the requirements for the above have been agreed upon with Electrum before proceeding with your implementation. Read more about the Electrum Finance processes ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/vas/public/electrum-console/electrum-finance/electrum-finance-overview-ec"},"children":["here"]},"."]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"potential-financial-risks"},"children":["Potential Financial Risks"]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"warning","name":"Important"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Electrum's APIs, and those of many providers, are not idempotent. This means that provision or purchase (financially impacting) transactions that fail or time out cannot be repeated without potentially incurring further financial obligations."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Once airtime is sent directly to the consumer’s mobile device, this cannot be reversed. Therefore we advise that you only initiate direct top-up airtime transactions after the consumer has provided tender."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Note"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Purchase status ",{"$$mdtype":"Tag","name":"a","attributes":{"href":"/vas/public/advanced-topics/reversals-and-refunds#lookups"},"children":["lookup"]}," transactions are helpful in a scenario where there is a timeout on the response. Lookups allow the originator to determine what has happened to the transaction. It can functionally be used as a retry or a lookup."]}]}]},"headings":[{"value":"Design considerations","id":"design-considerations","depth":1},{"value":"Online Transaction Processing","id":"online-transaction-processing","depth":2},{"value":"Electrum's Catalogue Management","id":"electrums-catalogue-management","depth":2},{"value":"Electrum Finance","id":"electrum-finance","depth":2},{"value":"Potential Financial Risks","id":"potential-financial-risks","depth":2}],"frontmatter":{"seo":{"title":"Design considerations"}},"lastModified":"2026-03-20T11:47:57.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/vas/public/airtime-direct-top-up/design-considerations","userData":{"isAuthenticated":false,"teams":["anonymous"]}}