Loader

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 manging user menus and flows (and would therefore need to utilize additional APIs) or delegate it to Clickatell whom manages the user menus and flows on the client’s behalf. Contact Clickatell for further information on Flow and related APIs.

 

Icon

Stakeholder

Definition

Buyer This is the person who initiates and pays for the purchase ​

Client The party whose particulars are fully set out in the master service agreement (MSA) and who consumes Clickatell’s interfaces

Supplier This is the party who dispenses the digital product on request from Clickatell

Recipient This is the party who will receive the product (this could be the buyer or another person)

Clickatell This consists of all the interfaces and functions between Clickatell and all the other parties 

Bank This is the banking facility/funding source that holds the buyer’s account
 

APIs involved

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

API name
Why use the API?
Security Service API Request authentication tokens to use in all other Clickatell API calls.
Financial Terms Lookup API Display the correct fee and settlement amounts as per the contractual agreement for the SKU being purchased.
Transact API Initiates a purchase request to Clickatell.
Reserve and Transact API Initiates a purchase and fund reservation request to Clickatell.
Transact Result API Initiates the delivery of the transaction result for a purchase that was made through Clickatell after Clickatell facilitated the dispensing of the product.
Transaction Lookup API Used after a purchase to confirm the transaction status.
Notification API Send notifications to buyer/recipient using different channels.
Token Lookup API Look up tokens/vouchers to present back to the buyer/customer who purchased token-related products via Clickatell’s platform.
MNO Lookup API Derive the specific mobile network operator (MNO) for the specified MSISDN.
Customer Account Validation API Validate a customer’s bill payment account number prior to submitting the bill payment purchase request to the vendor.
User Transaction Lookup API Identify if a new transaction is similar to one of the user’s recent transactions so the response details can be used to pre-emptively complete the current transaction details.
In-Flight Transaction Check API Used prior to a purchase instruction to confirm that no similar transaction is in progress.
Product Lookup API Confirm a product’s configuration and attributes.
Bank Interfaces A collection of APIs used between Clickatell and banks/funding sources when dealing with purchases.
 

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 

 

Did you find this information informative?

Other Resources

Ask the Community

Visit Stack Overflow to join our community of developers and find the answer you need

Contact Support

Contact our support team and one of our agents will be in touch with you to answer any questions you have