Last updated

The purchase phase of a direct top-up purchase follows the validation phase.

Purchase

Note

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.

Operations and Messages

TransactionOpedrationAPI Calls
PurchasepurchasePOST /purchases
Purchase status lookuppurchaseStatusGET /purchases/status
Important

You should not attempt transaction lookups until after the initial processing period concludes (after Electrum has received and processed the transaction outcome).

Message Flows

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.

Note

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.

Successful Airtime Purchase

Refer to 'Purchase Phase' in the diagram below.

  1. After a purchase trial transaction, the consumer tenders for a purchase transaction (no Electrum involvement).
  2. The originating system sends a POST call to the /purchases API endpoint.
  3. The API responds with an HTTP status of 201 and a PurchaseResponse message payload.
  4. The consumer receives the airtime top-up directly to their cellphone.

alt text

Error Upstream: Purchase Failed

  1. After a purchase trial transaction, the consumer tenders for a purchase transaction (no Electrum involvement).
  2. The originating system sends a POST call to the /purchases API endpoint.
  3. An error occurs at Electrum or the service provider.
  4. Electrum returns an ErrorDetail payload indicating that the purchase has failed.
  5. The consumer is notified of the error and the tender is reversed.

alt text

Error Upstream: Unknown Outcome

  1. After a purchase trial transaction, the consumer tenders for a purchase transaction (no Electrum involvement).
  2. The originating system sends a POST call to the /purchases API endpoint.
  3. An error occurs when Electrum does not receive a response or receives a response that the transaction is still being processed.
  4. Electrum returns an error of UPSTREAM_UNAVAILABLE or OUTCOME_UNKNOWN to the originating system.
  5. The originating system requests the status of the original transaction by sending a GET call to the /purchases/status endpoint.
  6. If Electrum receives a response regarding the transaction status from the service provider, then Electrum will return a PurchaseResponse (approved) or ErrorDetail (declined) response.
  7. The consumer is informed of the transaction outcome. Tender is reversed in the event of a failed transaction.

alt text

Error Upstream: Unknown Outcome and Lookups Fail

  1. After a purchase trial transaction, the consumer tenders for a purchase transaction (no Electrum involvement).
  2. The originating system sends a POST call to the /purchases API endpoint.
  3. An error occurs when Electrum does not receive a response or receives a response that the transaction is still being processed.
  4. Electrum returns an error of UPSTREAM_UNAVAILABLE or OUTCOME_UNKNOWN to the originating system.
  5. The originating system requests the status of the original transaction by sending a GET call to the /purchases/status endpoint.
  6. Electrum still does not receive a response or receives a response that the transaction is still being processed.
  7. Electrum returns an error of UPSTREAM_UNAVAILABLE or OUTCOME_UNKNOWN to the originating system.
  8. The originating system can choose to initiate another purchase status lookup or abort the transaction.

alt text

Error or Timeout at Originating System

  1. After a purchase trial transaction, the consumer tenders for a purchase transaction (no Electrum involvement).
  2. The originating system sends a POST call to the /purchases API endpoint.
  3. An error occurs at the originating system, or a timeout error occurs when the originating system does not receive a response.
  4. The originating system requests the status of the original transaction by sending a GET call to the /purchases/status endpoint.
  5. If Electrum receives a response regarding the transaction status from the service provider, then Electrum will return a PurchaseResponse (approved) or ErrorDetail (declined) response. The consumer is informed of the transaction outcome and tender is reversed in the event of a failed transaction.
  6. 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 UPSTREAM_UNAVAILABLE or OUTCOME_UNKNOWN to the originating system. The originating system can choose to initiate another purchase status lookup or abort the transaction.

alt text

Note

There is no explicit restriction on the number of purchase status lookup attempts that may be performed before the transaction should be aborted.

Copyright 2025 | Electrum Payments (Pty) Ltd