Design considerations

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 online transaction switching and back-office processing. For further details of the product features and available options, read the Product Overview page.

Important

Once the design decisions have been made, these need to be documented and shared with Electrum in a Business Requirements Document.

Note

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.

Online Transaction Processing

The table below summarises the choices that determine how the Electrum Switch is configured for processing requests from an originating system in real time.

Feature	Options	Decisions and Actions
Service providers	Mobile Mart Huge Lesaka Blue Label Telecoms SwitchOne	Decide which service providers you wish to transact with. Discuss commercial agreements directly with the selected service providers.
Channels	Point of sale (POS) Digital	Decide which transaction initiation channels you will be supporting. Ensure your channel development teams are familiar with the Electrum Airtime Service Interface and implementation guidelines.
Product list (catalogue)	You can maintain your list of available products through Electrum's catalogue management feature or you can use your own catalogue system.	Decide on whether you want to manage your product list via Electrum's catalogue management feature. If you decide to use Electrum's catalogue then you will need to implement list product transactions.
Purchase confirmations	The originating system sends a purchase confirmation message to finalise each transaction. The originating system does not send a purchase confirmation, and the transaction is considered final after the purchase leg has been completed.	Decide if your business processes require that the originating system finalises transactions with a purchase confirmation.
Routing	Routing via product ID Routing via the Mobile Network Operator (MNO)	Decide on at least one routing strategy which best suits your business needs. If more than one routing rule is chosen, then specify the order of preference in which they should be applied.
Connectivity and security	HTTPS using basic authentication or OAuth2 HTTPS using basic authentication or OAuth2 with mTLS1.2+ Connection via VPN	Decide on which method you wish to use for securing communication between the originating system and the Electrum API.

Electrum's Catalogue Management

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.

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.

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.

In order for you to retrieve your built-in list of products, you will need to perform a listProducts call. This can be done frequently or infrequently depending on circumstances:

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.
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.
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.

Electrum Finance

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:

Input file specifications for transaction matching
Transaction matching rules
Reporting requirements
Details of the parties involved in each process
Time-based rules (e.g., reconciliation period, automatic exception resolution, transaction expiry)
Settlement posting requirements to finance system

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 here.

Potential Financial Risks

Important

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.

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.