Overview

This guide is an easy-to-read introduction on the way Clickatell and clients interact with one another when dealing with purchase requests. It has step-by-step walkthrough of all the stages involved in the purchasing process with a specific focus on the transaction request of the purchase. Each step explains what is expected from both Clickatell and the client-side to make sure buyers have a safe and positive experience.

The “purchasing process” is when a buyer purchases a digital product through Clickatell, and Clickatell facilitates the payment and dispensing of the product.​ 

Role-players / stakeholders

The following parties are involved in the purchasing process.

Note: A party may perform more than one role in the purchase process. For example, in the end-to-end diagrammatic view illustrated shortly, the client could either operate their own platform managing user menus and flows (and would therefore need to utilize additional APIs) or delegate it to Clickatell who manages the user menus and flows on the client’s behalf. Contact Clickatell for further information on Chat Flow and related APIs.

 

 

APIs involved

The following APIs can be used as part of the purchasing process to perform the actions as stipulated in the table below.

 

End-to-end view of the purchase process – Main steps

Clients can either do the fund reservation themselves prior to sending Clickatell the purchase request, or they can require Clickatell to do the fund reservation prior to a purchase request. Both these scenarios are described in detail below.

1. Client does reservation of funds prior to sending purchase request to Clickatell

In this scenario, the main actions are:

1. Confirmation of financial terms 
2. Client sends purchase request to Clickatell 
3. Transaction is finalized based on the dispensing outcome: 
   • payment or
   • cancellation of the funds reservation

A high-level view of the end-to-end process is illustrated below: 

Step-by-step walkthrough (Client fund reservation)

This section provides a step-by-step walkthrough of the end-to-end process shown above.

Step 1:

• A buyer requests a purchase for a digitally dispensed product (e.g., airtime, electricity, lotto ticket).
• Clickatell receives a financial terms request from the client.
• The client uses the response information to ensure they reserve the correct funds on the buyer’s account prior to submitting the purchase request to Clickatell.

Also see: Financial Terms Lookup API

 

Step 2:

• Once Clickatell receives the purchase request (Step 1) from the client (who reserved the buyer’s funds upfront), Clickatell validates the request and gets ready to pass the request along to the supplier.

Also see Transact API

Step 3:

• If the validation (Step 2) passed, Clickatell responds to the client with the message “Processing Request”.
  • If it doesn’t pass validation, translation will fail with an appropriate error response.
•  The client then passes this message to the buyer.
• Clickatell continues with the purchase and facilitates the dispensing of the product from its supplier (e.g. a mobile network operator, a municipality, or a lottery ticket dispenser).

Step 4: 

• The supplier confirms with Clickatell on whether the product was successfully dispensed or not.
• Clickatell must now inform the client of this dispensing outcome (Step 5).

Step 5:

• Clickatell connects with the client and communicates the dispensing outcome.
  • If the product was not successfully dispensed, the client cancels the reservation on the funds.
  • However, if the product was successfully dispensed, the client deducts the reserved funds from the buyer’s account.

Also see: Transact Result API

 

2. Client requests Clickatell to do the reservation of funds

In this scenario, the main actions are:

1. Confirmation of financial terms
2. Client sends purchase request to Clickatell 
3. Clickatell requests reservation of funds from the buyer’s bank account
4. Transaction is finalized based on the dispensing outcome:
   • payment or
   • cancellation of the funds reservation

 

A high-level view of the end-to-end process is illustrated below:

 

Step-by-step walkthrough (Clickatell fund reservation)

This section provides a step-by-step walkthrough of the end-to-end process shown above.

 

Step 1:

• A buyer requests a purchase for a digitally dispensed product (e.g. airtime, electricity, lotto ticket).
• Clickatell receives a financial terms request from the client.
• The client uses the response information to ensure that the buyer is presented with the correct product fee amount prior to submitting the purchase request to Clickatell.

Also see Financial Terms Lookup API

Step 2:

• Clickatell receives this purchase request from the client, validates the request, and gets ready to pass it to the buyer’s bank.

Also see: Reserve and Transact API

Step 3:

• Clickatell interfaces with the buyer’s bank to request a reservation of funds on the buyer’s bank account for the purchase amount.
  • Note: In instances where the bank takes longer to respond than the allowed USSD timeout limit, Clickatell will respond to the client with the message, “Processing request”. The client will pass this message to the buyer.
• The bank confirms that the buyer has funds available to purchase the product and, if so, reserves the funds.
• The bank then confirms with Clickatell whether it was able to reserve the funds or not.
• Clickatell receives the bank’s response message regarding the reservation of the required funds.
• If the funds were not successfully reserved, the purchase is canceled at this point and an appropriate response is sent via Clickatell and the client to the buyer.

Also see Bank Interfaces 

Step 4:

• However, if the funds were successfully reserved, Clickatell continues with the purchase and facilitates the dispensing of the product from its supplier (for instance a mobile network operator, a municipality, or a lottery ticket dispenser).

Step 5: 

• The supplier confirms with Clickatell on whether the product was successfully dispensed or not.
• Clickatell must now inform the bank of this dispensing outcome.

 

Step 6:

• Clickatell connects with the bank and communicates the dispensing outcome
  • If the product was not successfully dispensed, the bank cancels the reservation of the funds
  • However, if the product was successfully dispensed, the bank deducts the reserved funds from the buyer’s account

Also see Bank Interfaces