API Reference
This describes the two main interfaces where Clickatell and a bank interact when dealing with a purchase.
Reserve funds endpoint implemented by bank
The reserveFunds 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.
The reserveFunds 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 Signature Checksum Calculation
This is an "optional" hash calculated using a shared secret between Clickatell and the client
Unique client reference to the transaction
seo8w3-3wsf8cffdd34-f58lUnique Clickatell reference to the transaction
ffdd34-3wsf8c-seo8w3-f58lID of the product requested to be purchased. A list of products will be supplied by Clickatell
110Unique reference to the product type (classification, group or line) that was purchased, for instance pre-purchased airtime or data
3The value of the SKU that the customer wishes to receive, in the lowest denomination (e.g. cents or pennies), for instance, $250.00 would equate to the value 25000. This amount excludes the fee amount charged for the product
10000The amount to be reserved by the funding source. Typically, the same as the TPV (Total Purchase Value). In the lowest denomination (e.g. cents or pennies), for instance $250.00 would equate to the value 25000. May differ from the purchase amount and vend amount if a fee has been added on top of the purchase amount.
110A fixed transaction fee that Clickatell charges on top of the requested purchase value of a product. Please note a zero amount needs to be specified if there is no fee applicable. If the fee amount is not correct the request validation will fail
0The portion of the TPV due to the client, stated as an amount. In the lowest denomination (e.g. cents or pennies), for instance $250.00 would equate to the value 25000
487The amount settled to Clickatell by the client. In the lowest denomination (e.g. cents or pennies), for instance $250.00 would equate to the value 25000
14513The unique identifier for the source, as recognized by the bank. This is typically the mobile phone number (MSISDN) but can be another unique identifier recognized by the bank.
2341234567899The unique identifier for the intended recipient (or target/destination) of the product being purchased. This may be the buyer (“Self”) or someone else (a so-called “3rd party purchase”)
2348012345555The channel is the user interface, platform or service that the buyer used to initiate a purchase from
7This is the specific name of the channel used to initiate a purchase
USSDThis is a unique reference to the channel-specific engagement when the purchase was initiated (for example USSD Session ID, if the purchase was over USSD)
144974973281An authentication code provided by the buyer that the bank can use to verify the buyer’s identity. Used in the reserveFunds request if supplied
1234The timestamp of when an API request or response was sent, in ISO-8601 format
2017-06-29T16:39:42.735ZThe account that will be deducted from. Only mandatory if there is no concept of a default account for the buyer at the funding source
3745******0762successful response
POST /reserveFunds HTTP/1.1
Host: client_server_hostname/
Content-Type: application/json
Accept: */*
Content-Length: 453
{
"clientTxnRef": "seo8w3-3wsf8cffdd34-f58l",
"raasTxnRef": "ffdd34-3wsf8c-seo8w3-f58l",
"productId": 110,
"productType": 3,
"purchaseAmount": 10000,
"reserveAmount": 110,
"feeAmount": 0,
"clientShareAmount": 487,
"settlementAmount": 14513,
"sourceIdentifier": "2341234567899",
"targetIdentifier": "2348012345555",
"channelId": 7,
"channelName": "USSD",
"channelSessionId": "144974973281",
"authCode": 1234,
"timestamp": "2017-06-29T16:39:42.735Z",
"accountIdentifier": "3745******0762"
}successful response
{
"responseCode": "0000",
"reserveFundsTxnRef": "ffdd34-3wsf8c-seo8w3-f58l"
}Endpoint that informs the client of the outcome of a transaction
The transactResult 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.
The transactResult 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 Signature Checksum Calculation
This is a hash calculated using a shared secret between Clickatell and the client
Unique client reference to the transaction
seo8w3-3wsf8cffdd34-f58lUnique Clickatell reference to the transaction
ffdd34-3wsf8c-seo8w3-f58lThis is the universally unique identifier that the bank must generate when it reserves funds on a buyer’s account
f58l-3wsf8c-seo8w3-ffdd34The response code used on the reserveFunds Response indicates the result of attempting to reserve funds on a buyer’s account. Note that all response codes other than 0000 will be treated as a failed funds reservation (and consequently,not followed by a Transact Result confirmation)
0The amount to be reserved by the funding source. In the lowest denomination (e.g. cents or pennies), for instance $250.00 would equate to the value 25000. Typically,the same as the TPV (Total Purchase Value). May differ from the purchase amount and vend amount if a fee has been added on top of the purchase amount.
110A fixed transaction fee that Clickatell charges on top of the requested purchase value of a product. Please Note a zero amount needs to be specified if there is no fee applicable. If the fee amount is not correct the request validation willfail
0The portion of the TPV due to the client, stated as an amount. In the lowest denomination (e.g. cents or pennies), for instance $250.00 would equate to the value 25000
487The amount settled to Clickatell by the Client. In the lowest denomination (e.g. cents or pennies), for instance $250.00 would equate to the value 25000
14513The timestamp of when an API request or response was sent, in ISO-8601 format
2017-06-29T16:39:42.735ZSome product types return a recharge PIN/Token which consumers use to redeem the value of the purchase (e.g. PIN/Token entered in a Pre-Paid meter). The Clickatell platform will deliver this PIN/Token to the consumer via SMS.The PIN/Token will only be returned via the API when the Clients/Funding sources are configured on the Clickatell platform to receive it
XYZsuccessful response
No content
POST /transactResult HTTP/1.1
Host: client_server_hostname/
Content-Type: application/json
Accept: */*
Content-Length: 286
{
"clientTxnRef": "seo8w3-3wsf8cffdd34-f58l",
"raasTxnRef": "ffdd34-3wsf8c-seo8w3-f58l",
"reserveFundsTxnRef": "f58l-3wsf8c-seo8w3-ffdd34",
"responseCode": 0,
"reserveAmount": 110,
"feeAmount": 0,
"clientShareAmount": 487,
"settlementAmount": 14513,
"timestamp": "2017-06-29T16:39:42.735Z",
"token": "XYZ"
}successful response
No content
Last updated