Overview of Marketplace
beforeThis guide is an easy-to-read introduction to how Clickatell and clients interact when dealing with purchase requests. It includes a step-by-step walkthrough of all the stages involved in the purchasing process with a specific focus on the transaction request. Each step explains what is expected from both Clickatell and the client to ensure buyers have a safe and positive experience.
The “purchasing process” refers to 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.
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.
Request authentication tokens to use in all other Clickatell API calls.
Display the correct fee and settlement amounts as per the contractual agreement for the SKU being purchased.
Initiates a purchase request to Clickatell.
Initiates a purchase and fund reservation request to Clickatell.
Initiates the delivery of the transaction result for a purchase that was made through Clickatell after Clickatell facilitated the dispensing of the product.
Used after a purchase to confirm the transaction status.
Send notifications to buyer/recipient using different channels.
Look up tokens/vouchers to present back to the buyer/customer who purchased token-related products via Clickatell’s platform.
Derive the specific mobile network operator (MNO) for the specified MSISDN.
Validate a customer’s bill payment account number before submitting the bill payment purchase request to the vendor.
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.
Used before a purchase instruction to confirm that no similar transaction is in progress.
Confirm a product’s configuration and attributes.
A collection of APIs used between Clickatell and banks/funding sources when dealing with purchases.
End-to-end view of the purchase process
Clients can either do the fund reservation themselves before sending Clickatell the purchase request, or they can require Clickatell to do the fund reservation before a purchase request. Both these scenarios are described in detail below.
Client does reservation of funds before sending purchase request to Clickatell
In this scenario, the main actions are:
Confirmation of financial terms
Client sends purchase request to Clickatell
Transaction is finalized based on the dispensing outcome:
Payment or
Cancellation of the funds reservation
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 the buyer is presented with the correct product fee amount before submitting the purchase request to Clickatell.
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 prepares to pass the request to the supplier.
Step 3:
If the validation (Step 2) passes, 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 whether the product was successfully dispensed.
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 is 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.
Client requests Clickatell to do the reservation of funds
In this scenario, the main actions are:
Confirmation of financial terms
Client sends purchase request to Clickatell
Clickatell requests reservation of funds from the buyer’s bank account
Transaction is finalized based on the dispensing outcome:
Payment or
Cancellation of the funds reservation
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 before submitting the purchase request to Clickatell.
Step 2:
Clickatell receives this purchase request from the client, validates the request, and prepares to pass it to the buyer’s bank.
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.
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.
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 6:
Clickatell connects with the bank and communicates the dispensing outcome
If the product is not successfully dispensed, the bank cancels the reservation of the funds.
However, if the product is dispensed successfully, the bank deducts the reserved funds from the buyer’s account.
