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

 

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 

 

Channels

Find the most up-to-date information about the channels available to communicate with your clients.

SMS

Enable any application, website or system to facilitate local or international one- or two-way SMS communication via an easy one-step integration with our HTTP API.

Documentation
One API

Communicate with your mobile customers via multiple communication channels with a single integration. You can send and receive messages on both WhatsApp and SMS without the overhead of programming individual channels.

Documentation
WhatsApp

As an authorized WhatsApp Business Solution Provider, we assist you in applying for a WhatsApp Business account and number. Integrate with other powerful features available on our platform via our One API.

Documentation

Products

Find the most up-to-date information about the products we offer and how to elevate your engagement with customers.

Chat 2 Pay

Send payment requests to customers via chat for secure, contactless payment experiences.

Documentation
Chat Desk

An easy-to-use web-based application that enables real-time communication with your customers via a single web interface.

Documentation
Chat Flow

A web-based application that allows you to quickly and collaboratively design and deploy conversational experiences across multiple chat applications and connect it to your organization's core functional APIs.

Documentation
Campaign Manager

An online tool that allows you to create a custom SMS campaign within minutes - no coding or developers required.

Documentation

Marketplace

Find the most up-to-date information about Clickatell's Marketplace and how you can utilize it for the distribution and payment acceptance of digital products.

Bank Interfaces API

An explanation of the way Clickatell and banks interact with one another when dealing with purchases. 

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

Documentation
Reserve and Transact API

Initiates a purchase and fund reservation request to Clickatell.

Documentation
Security Service API

Request authentication tokens to use in all other Clickatell API calls.

Documentation
Transact

A cloud-based platform that allows for the distribution and payment acceptance of multiple digital products.

Documentation
Product Lookup API

Confirm a product's configuration and attributes.

Documentation
In-Flight Transaction Check API

Used prior to a purchase instruction to confirm that no similar transaction is in progress.

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

Documentation
Customer Account Validation API

Validate a customer's bill payment account number prior to submitting the bill payment purchase request to the vendor.

Documentation
MNO Lookup API

Derive the specific mobile network operator (MNO) for the specified MSISDN.

Documentation
Token Lookup API

Look up tokens/vouchers to present back to the buyer/customer who purchased token-related products via Clickatell's platform.

Documentation
Notifications API

Send notifications to buyer/recipient using different channels.

Documentation
Transaction Lookup API

Used after a purchase to confirm the transaction status.

Documentation
Financial Terms Lookup API

Display the correct fee and settlement amounts as per the contractual agreement for the SKU being purchased.

Documentation
Transact API

Initiates a purchase request to Clickatell.

Documentation

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