Getting started

This guide is an easy-to-read introduction to the way Clickatell and banks interact with one another when dealing with purchases. 

For a step-by-step walkthrough of all the stages involved in the purchasing process, and where this API fits in, see the Transact Overview page. 

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 be the bank that operates their own platform managing user menus and flows (and would, therefore, need to utilize additional APIs) or delegated to Clickatell who manages the user menus and flows on the bank’s behalf. Contact Clickatell for further information on Chat Flow and related APIs.

Participating parties

• Buyer 
• Clickatell
• Client
• Bank 
• Supplier
• Recipient

For definitions of each, see the Transact Overview page.

Interfaces 

Interfaces refer to the points in the process where Clickatell and the Bank exchange information.

There are two main functions that the bank is expected to do. Each of these functions has its own interface where Clickatell and the bank exchange information and the outcomes of the respective functions.

1. Reserve Funds
   • Receive request to reserve funds from Clickatell
   • Process request internally 
   • Respond with reservation status to Clickatell
2. Transaction Result
   • Receive dispensing outcome from Clickatell
   • Process request internally
   • Confirm receipt of outcome with Clickatell

Walkthrough of Interfaces 

Reserve Funds API

The Reserve Funds API is the first point of communication between Clickatell and the bank, where Clickatell requests the reservation of funds for a purchase from the client, and the bank replies with the outcome of this reservation.

1.1. Receive request to reserve funds 

• The bank receives a request from Clickatell to see whether it can reserve funds on one of its account holders’ accounts, who is trying to purchase something through Clickatell.
  • Note: the bank must internally log receipt of each received request. 
• The request contains the following information:
  • A unique identifier for the request, as assigned by Clickatell
  • A unique identifier for the buyer that can be recognized by the bank to find the buyer’s account (this is typically also the buyers mobile phone number, or MSISDN, but not necessarily)
  • The price of the product, i.e. purchase amount
  • The fee amount if applicable to the product
  • The amount that needs to be reserved against the account holder’s account, i.e. reserve amount
  • The portion of the total purchase value (TPV) due to the client, i.e. client share amount
  • The amount settled to Clickatell by the client, i.e. settlement amount
  • Information about the product being purchased
  • Information about the channel through which the buyer requested the purchase (e.g. the internet, USSD, WhatsApp, etc.)
  • The timestamp of when the request was sent to the bank
• The request can also contain further details such as:
  • An authentication code (a PIN known only by the buyer) that will assist in preventing fraud (if required by the bank)
  • The buyer’s mobile service provider
  • Information about the recipient (the person to whom the product will be dispensed to, which could be the buyer or another party)

1.2. Process request 

The bank processes the request in the three steps: 

1. Validate purchase
   • The bank must validate the purchase internally. Some examples of errors that typically occur during validation are listed below:
     • Reserve amount – The bank must confirm that the reserve amount (the purchase amount plus the fee amount of the product) is within any internally purchase amount limits.
       •  If the reserve amount falls either below or above the set limit, the request fails with the respective error: “Below minimum amount” or “Maximum amount exceeded”
     • Find buyer’s bank account – The bank uses the unique identifier of the buyer (for instance the buyer’s mobile phone number) to look up the buyer’s account from where the payment must be made
       •  If an account was not found, the request fails with the error: “Consumer Account not mapped”
     • Authentication code – If an authentication code was requested from the buyer, the bank needs to validate that the correct code was provided
       •  If an incorrect authentication code was provided, the request fails with the following error: “Invalid authentication code”
     • Buyer’s bank account status – The bank must confirm the status of the buyer’s bank account
       •  If the account is either inactive or blacklisted, the request fails with the respective error: “Consumer Account inactive” or “Blacklisted Consumer Account”
     • Available funds – Once the account status was validated, the bank needs to confirm that the buyer has sufficient funds available in the account to purchase the product
       •  If there are insufficient funds available in the account, the request fails with the following error: “Insufficient funds”
     • Response time
       •  If, for any reason, the bank experienced an internal delay and is unable to confirm an outcome fast enough (preferably under 2 seconds), the request must fail with the following error: “Time-out”
2. Reserve the funds
   • If validation was passed in the previous steps, the following is required from the bank:
     • Reserve funds on the buyer’s account
     • Generate universal, unique transaction reference for the fund reservation (the identifier must be unique from references that may be generated by other banks over time)
3. Respond to Clickatell
   • The bank is now ready to respond back to Clickatell with the outcome of the funds reservation exercise.
     •  If the bank encountered an issue during the validation or reservation steps and is unable to confirm an outcome, the request must fail with the corresponding error.
     •  If there were no validation or other errors and the funds were successfully reserved, the request will succeed with the following status: “Success“

1.3. Respond with reservation status 

• The outcome of the previous step is now communicated to Clickatell. The following information is provided:
  • The outcome of the funds reservation exercise (this status is either successful or a specific error as encountered during the previous step)
  • If the outcome was successful, the unique transaction reference that was generated when the fund reservation was done
• If the bank did not respond within five seconds after Clickatell sent the request, Clickatell will cancel the request and notify the bank as part of the Transaction Result interface (see below).
• If the bank confirms the reservation status as successful, Clickatell continues by facilitating the dispensing of the product that the buyer purchased

Transact Result API

The Transact Result API is the second point of interaction between Clickatell and the bank, where Clickatell confirms the outcome of the dispensing of the product with the bank, and the bank can either proceed with the payment or cancel the fund reservation. 

2.1 Receive dispensing outcome

• To conclude the purchase request, Clickatell must confirm with the bank whether the requested product was successfully dispensed.
• Although this outcome is typically received shortly after the bank has confirmed the fund reservation, if the bank has not received any outcome within seven business days after the bank’s fund reservation confirmation, the bank must contact Clickatell’s Support Desk with an exception report that contains the details of these unconfirmed requests.

2.2 Process request

•  In the case of an unsuccessful dispensing outcome, the bank must cancel the fund reservation on the buyer’s account by releasing the funds.
•  In the case of a successful dispensing outcome, the bank will finalize the fund reservation by debiting the buyer’s account.

2.3 Confirm receipt of outcome

• After receiving the dispensing outcome from Clickatell, the bank only needs to confirm receipt of the message with Clickatell, no other information is exchanged.
• In the event of a network connection failure or timeout, Clickatell will make several attempts to resend the confirmation request to the Funding Source.
• If the Funding source is not able to match the confirmation with a previous fund reservation, then they need to reply with a HTTP 404.

Getting started with Banking Interfaces

To interface with Clickatell, the following needs to be set up, configured and tested: 

Step 1: Internal buyer identifier to account mapping 

• Create a mapping between buyer identifiers (typically MSISDNs) and bank accounts (one per buyer, the so-called “default” account) from which payment must be attempted

Step 2: Configure Reserve Funds connectivity

• Receive a fund reservation request from Clickatell
• Look up a buyer’s bank account using the received buyer’s unique identifier
• Validate the request on:
  • Reserve Amount
  • Buyer’s bank account status
  • Available funds
  • Authentication Code (if applicable)
• If validation passes, reserve the requested funds and generate a universally unique reference for this action
• Respond to Clickatell with the reservation outcome and, if it was successful, the unique reference

Step 3:  Configure Transact Result connectivity

• Receive and confirm receipt of a dispensing outcome result from Clickatell
• Match the result to a previous fund reservation request and take appropriate action based on the dispensing outcome (debit account or cancel reservation)

Notes

The following API calls are not discussed in this document as they form part of the respective API’s documentation as indicated below:

• Financial Terms Lookup API quick-start guide
  • financial terms lookup Request
  • financial terms lookup Response
• Reserve and Transact API quick-start guide
  • reserveAndTransact Request
  • reserveAndTransact Response

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

For a list of all roles-players/stakeholders involved in the purchasing process, see the Transact Overview page. 

Read more:

• Bank Interfaces references
• Financial Terms Lookup API
• Reserve and Transact API 
• Transact Result API 
• Overview
• Getting started