Introduction
Welcome to the Selcom Developers!
Selcom Developer offers a set of Application Programming Interfaces (APIs) that gives you the ability to incorporate Selcom functionality into your projects. Our API's are State of Art with complete security module and structured to meet Market needs.
We are excited to work with you to innovate on the next generation of applications using Selcom proprietary APIs. Each step below outlines what it takes to get your project off the ground. From finding a use case that meets your needs, to launching that project to your customers.
To access Selcom API endpoints for services like Utility Payments, Wallet Cashin and Qwiksend. One has to get in touch with our Teams (info@selcom.net). Our Developer Zone has language bindings in PHP, Java and Shell. Code examples are on the right side of the Panel, switching to different Programming language make use of the Tabs.
Authentication
To authorize, use this code:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "Content-type: application/json"
-H "Authorization: SELCOM meowmeowmeow"
-H "Digest-Method: HS256"
-H "Digest: tW32A+O1FcpRj2o2mbWgF2r+vmILqqKwHqDryj+7lvI="
-H "Timestamp: 2019-02-26T09:30:46+03:00"
-H "Signed-Fields: utilityref,vendor,pin,transid,amount,msisdn"
-d '{"vendor":"BANKX", "pin":"3333", "utilityref":"075XXXXXXX", "transid":"T001", "amount":"1234", "msisdn":"25568XXXXXXX"}'
function sendJSONPost($url, $isPost, $json, $authorization, $digest, $signed_fields, $timestamp) {
$headers = array(
"Content-type: application/json;charset=\"utf-8\"", "Accept: application/json", "Cache-Control: no-cache",
"Authorization: SELCOM $authorization",
"Digest-Method: HS256",
"Digest: $digest",
"Timestamp: $timestamp",
"Signed-Fields: $signed_fields",
);
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $url);
if($isPost){
curl_setopt($ch, CURLOPT_POST, 1);
curl_setopt($ch, CURLOPT_POSTFIELDS, $json);
}
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers);
curl_setopt($ch,CURLOPT_TIMEOUT,90);
$result = curl_exec($ch);
curl_close($ch);
$resp = json_decode($result, true);
return $resp;
}
function computeSignature($parameters, $signed_fields, $request_timestamp, $api_secret){
$fields_order = explode(',', $signed_fields);
$sign_data = "timestamp=$request_timestamp";
foreach ($fields_order as $key) {
$sign_data .= "&$key=".$parameters[$key];
}
//RS256 Signature Method
#$private_key_pem = openssl_get_privatekey(file_get_contents("path_to_private_key_file"));
#openssl_sign($sign_data, $signature, $private_key_pem, OPENSSL_ALGO_SHA256);
#return base64_encode($signature);
//HS256 Signature Method
return base64_encode(hash_hmac('sha256', $sign_data, $api_secret, true));
}
//Set your appropirate timezone
date_default_timezone_set('Africa/Dar_es_Salaam');
$api_key = '202cb962ac59075b964b07152d234b70';
$api_secret = '81dc9bdb52d04dc20036dbd8313ed055';
$base_url = "http://127.0.0.1/selcom-api-gateway/v1";
$api_endpoint = "/utilitypayment/process";
$url = $base_url.$api_endpoint;
$isPost =1;
$req = array("utilityref"=>"12345", "transid"=>"transid", "amount"=>"amount");
$authorization = base64_encode($api_key);
$timestamp = date('c'); //2019-02-26T09:30:46+03:00
$signed_fields = implode(',', array_keys($req));
$digest = computeSignature($req, $signed_fields, $timestamp, $api_secret);
$response = sendJSONPost($url, $isPost, json_encode($req), $authorization, $digest, $signed_fields, $timestamp);
package apigwclient;
import java.security.InvalidKeyException;
import java.security.NoSuchAlgorithmException;
import java.text.SimpleDateFormat;
import java.util.ArrayList;
import java.util.Date;
import java.util.HashMap;
import java.util.List;
import java.util.Map;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import org.apache.commons.codec.binary.Base64;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.HttpClient;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpPost;
import org.apache.http.entity.StringEntity;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.util.EntityUtils;
import org.json.simple.JSONObject;
import org.json.simple.parser.JSONParser;
/**
*
* @author selcomdeveloper
*/
public class APIGWClient {
public static void main(String[] args) {
try {
String secret = "81dc9bdb52d04dc20036dbd8313edxyz";
String postURL = "https://apigwtest.selcommobile.com/v1/utilitypayment/process";
String getURL = "https://apigwtest.selcommobile.com/v1/utilitypayment/lookup";
String api_key = "202cb962ac59075b964b07152d234abc";
SimpleDateFormat sdfDate = new SimpleDateFormat("yyyy-MM-dd'T'HH:mm:ss.SSSSSX");
Date now = new Date();
String timestamp = sdfDate.format(now);
//Post Example
JSONObject json = new JSONObject();
json.put("utilitycode", "LUKU");
json.put("utilityref", "12345678901");
json.put("transid", "101101");
json.put("msisdn", "2556828XXXXX");
json.put("vendor", "TEST");
json.put("pin", "1122");
json.put("amount", "100");
JSONObject postReponse = post(postURL, json, computeHeader( json, secret, timestamp, api_key));
if(null != postReponse){
System.out.println("POST RESPONSE: "+postReponse.toJSONString());
}
//Get Example
Map req = new HashMap();
req.put("utilitycode", "LUKU");
req.put("utilityref", "12345678901");
req.put("transid", "101102");
JSONObject getReponse = get(getURL, req, computeHeader( req, secret, timestamp, api_key));
if(null != getReponse){
System.out.println("GET RESPONSE: "+getReponse.toJSONString());
}
}
catch (Exception e){
e.printStackTrace();
}
}
public static Map computeHeader(Map params, String secret, String timestamp, String api_key) throws NoSuchAlgorithmException, InvalidKeyException{
Map header = new HashMap();
String message = "", signed_fields = "";
List<String> keys = new ArrayList<String>();
List<String> serializedJson = new ArrayList<String>();
serializedJson.add("timestamp="+timestamp);
for (Object key : params.keySet()) {
String keyStr = (String)key;
String keyvalue = params.get(keyStr).toString();
serializedJson.add(keyStr+"="+keyvalue);
keys.add(keyStr);
}
message = String.join("&", serializedJson);
signed_fields = String.join(",", keys);
Mac sha256_HMAC = Mac.getInstance("HmacSHA256");
SecretKeySpec secret_key = new SecretKeySpec(secret.getBytes(), "HmacSHA256");
sha256_HMAC.init(secret_key);
String digest = new String(Base64.encodeBase64(sha256_HMAC.doFinal(message.getBytes())));
String encodedApiKey = new String(Base64.encodeBase64(api_key.getBytes()));
header.put("Content-type", "application/json");
header.put("Authorization", "SELCOM "+encodedApiKey);
header.put("Digest-Method", "HS256");
header.put("Digest", digest);
header.put("Timestamp", timestamp);
header.put("Signed-Fields", signed_fields);
return header;
}
public static JSONObject post(String url, JSONObject json, Map header){
HttpClient httpClient = HttpClientBuilder.create().build();
try {
HttpPost request = new HttpPost(url);
StringEntity params = new StringEntity(json.toString());
for (Object key : header.keySet()) {
request.addHeader(key.toString(), header.get(key).toString());
}
request.setEntity(params);
HttpResponse hresp = httpClient.execute(request);
HttpEntity httpEntity = hresp.getEntity();
String apiOutput = EntityUtils.toString(httpEntity);
JSONParser parser = new JSONParser();
return (JSONObject)parser.parse(apiOutput);
} catch (Exception ex) {
return null;
}
}
public static JSONObject get(String url, Map getParams, Map header){
HttpClient httpClient = HttpClientBuilder.create().build();
List<String> qstring_list = new ArrayList<String>();
for (Object key : getParams.keySet()) {
qstring_list.add(key.toString() + "="+getParams.get(key).toString());
}
try {
url = url + "?" + String.join("&", qstring_list);
HttpGet request = new HttpGet(url);
for (Object key : header.keySet()) {
request.addHeader(key.toString(), header.get(key).toString());
}
HttpResponse hresp = httpClient.execute(request);
HttpEntity httpEntity = hresp.getEntity();
String apiOutput = EntityUtils.toString(httpEntity);
JSONParser parser = new JSONParser();
return (JSONObject)parser.parse(apiOutput);
} catch (Exception ex) {
return null;
}
}
}
Make sure to replace other header values with the appropriate values computed before sending the request.
Selcom Developers uses API key and API secret to allow access to the API. You can request for api credentials writing to Selcom Support.
Selcom API Gateway expects the below HTTP headers to be included in all API requests to the server for both GET and POST requests:
Header | Description |
---|---|
Authorization | Base64 encoded API key using realm SELCOM |
Timestamp | Datetime in ISO 8601 date format (YYYY-MM-DDThh:mmTZD). Example 2019-02-26T09:30:46+03:00 |
Digest-Method | HS256 for HMAC SHA256 algorithm , RS256 for RSA signature with PKCS #1 and SHA-2 |
Digest | Base64 encoded HMAC SHA256 or RSA signature of data in the format (timestamp=[timezone as in header 2019-02-26T09:30:46+03:00]&field1=value1&fielf...in the order defined in Signed-Fields) |
Signed-Fields | GET or POST Json parameters keys comma separated in the same order used for computing Digest. (Timestamp field need not be mentioned on Signed-fields header through its part of the signing). |
Refer to the below example
Authorization: SELCOM MjAyY2I5NjJhYzU5MDc1Yjk2NGIwNzE1MmQyMzRiNzA=
Digest-Method: HS256
Digest: tW32A+O1FcpRj2o2mbWgF2r+vmILqqKwHqDryj+7lvI=
Timestamp: 2019-02-26T09:30:46+03:00
Signed-Fields: utilitycode,utilityref,vendor,pin,transid,amount
API Response
API responses for failure scenario
{
"transid" : "F10001",
"reference" : "0289999288",
"resultcode" : "403",
"result" : "FAIL",
"message" : "No reponse from upstream system",
"data":[ ]
}
API responses for Success scenario
{
"transid" : "F10002",
"reference" : "0270720833",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "Airtime recharge\nReference 0270720833\nPhone 0773820XXX\nAmount TZS 10,000\nVendor XYZVENDOR\n\nPowered by Selcom",
"data":[ ]
}
Result | Errorcode | Description |
---|---|---|
SUCCESS | 000 | Transaction successful |
INPROGRESS | 111,927 | Transaction in progress please query to know the exact status of the transaction |
AMBIGOUS | 999 | Transactions status unknown wait for recon |
FAIL | All others | Transaction failed |
Incase of an INPROGRESS and AMGIBOUS error code scenario, do a transaction query status api after 3 mins interval if the status remain the same, transaction should be cleared after a manual recon with Selcom Recon team (recon_at_selcom_dot_net)
Utility Payments
Utility Payment Request
HTTP Request
POST http://example.com/v1/utilitypayment/process
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
transid | Mandatory | XYZ123444 | Unique Transaction ID of the transaction |
utilitycode | Mandatory | LUKU | Transaction type that Identifies the Utility you are paying for. Refer to Utilitycode Definitions for UtilityPayments section |
utilityref | Mandatory | 01234567891 | Payment reference for the Utility service |
amount | Mandatory | 1000 | Transaction amount |
vendor | Mandatory | 01234567891 | Float account identifier |
pin | Mandatory | 01234567891 | Float account PIN |
msisdn | Optional | 01234567891 | End-user mobile number |
Utility Look Up
HTTP Request
GET http://example.com/v1/utilitypayment/lookup?utilitycode=LUKU&utilityref=XYZ123444&transid=1001
Query Parameters
Parameter | Type | Example | Description |
---|---|---|---|
utilitycode | Mandatory | LUKU | Utility Type Identifier |
utilityref | Mandatory | 01234567891 | Payment reference for the utility |
transid | Mandatory | XYZ123444 | Transaction ID to match request and response. Transid used for lookup can be used for transaction call. transid field cannot duplicate for multiple transaction calls. |
Luku Lookup Sample response:
{
"reference":"6927759116",
"transid":"10001",
"resultcode":"000",
"result":"SUCCESS",
"message":"LUKU Confirmation\nFIROZ\nMeter# 4300071XXXX\n",
"data":[
{
"name":"FIROZ MOH"
}
]
}
GEPG Lookup Sample response:
{
"reference":"6927768243",
"transid":"10001",
"resultcode":"000",
"result":"SUCCESS",
"message":"DAWASA\nName MNYANGA\nControl# 99104217XXXX\nTZS 5,000",
"data":[
{
"name":"MNYANGA",
"amount":"5000",
"institution":"DAWASA",
"type":"PART",
"desc":"Bill Charges 2019-2"
}
]
}
Query Payment Status
Query status of the Utility Payment or Bill Pay transaction in case of a timeout or ambigous response.
HTTP Request
GET http://example.com/v1/utilitypayment/query?transid=XYZ123444
Query Parameters
Parameter | Type | Example | Description |
---|---|---|---|
transid | Mandatory | XYZ123444 | Unique Transaction ID of the transaction |
Utilitycode Definitions for UtilityPayments
Utility Services
Utilitycode | Ref Label | Ref Type | Ref Eg. | LookUp Avail | Description |
---|---|---|---|---|---|
LUKU | Meter No | Numeric(11) | 01234567891 | Yes | Prepaid Electricity |
TOP | Mobile No | Numeric(10,12) | 068XXXXXXX | No | Prepaid Airtime |
NHC and DAWASA has been migrated to GEPG. Please refer to Government Payments
section below.
TV Subscriptions
Utilitycode | Ref Label | Ref Type | Ref Eg. | LookUp Avail | Description |
---|---|---|---|---|---|
DSTV | Smartcard No | Numeric(11) | 01234567891 | Yes | DSTV Subscriptions |
DSTVBO | Smartcard No | Numeric(11) | 01234567891 | Yes | DSTV Box Office |
AZAMTV | Smartcard No | Numeric(12) | 012345678912 | Yes | AZAMTV Subscriptions |
STARTIMES | Customer ID or Smartcard No | Numeric(10,11) | 01234567891 | Yes | STARTIMES |
ZUKU | Account No | Numeric(6) | 012345 | Yes | ZUKU Subscriptions |
Prepaid Internet
Utilitycode | Ref Label | Ref Type | Ref Eg. | LookUp Avail | Description |
---|---|---|---|---|---|
SMILE | Account No | Numeric(10) | 01234567891 | Yes | SMILE 4G Internet |
ZUKUFIBER | Account No | Numeric(6) | 012345 | Yes | ZUKU Fiber Internet |
TTCL | Mobile No | Numeric(10) | 01234567891 | No | TTCL Prepaid and Broadband |
Government Payments
Utilitycode | Ref Label | Ref Type | Ref Eg. | LookUp Avail | Description |
---|---|---|---|---|---|
GEPG | Control No | Numeric(12) | 991234567891 | Yes | Goverment Bill Payment (150 Gov Enties including DAWASA, NHC, etc) |
Travel & Ticket Booking
Utilitycode | Ref Label | Ref Type | Ref Eg. | LookUp Avail | Description |
---|---|---|---|---|---|
PW | Booking Ref | Numeric(5-10) | 01234567891 | Yes | Precision Air |
COASTAL | Booking Ref | Numeric(8) | 0123456 | Yes | COASTAL Aviation |
AURIC | Booking Ref | Numeric(6) | 012345 | Yes | Auric Air |
Investment & Pension Funds
Utilitycode | Ref Label | Ref Type | Ref Eg. | LookUp Avail | Description |
---|---|---|---|---|---|
UTT | Account No | Numeric(9) | 012345678 | Yes | UTT Amis |
Merchant Payments (Over 20K Merchants)
Utilitycode | Ref Label | Ref Type | Ref Eg. | LookUp Avail | Description |
---|---|---|---|---|---|
SELCOMPAY | Account No | AlphaNumeric(6-20) | 01234567891 | Yes | SelcomPay/Masterpass Merchant Payments |
Wallet Cashin
Cashin Request
HTTP Request
POST http://example.com/v1/walletcashin/process
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
transid | Mandatory | XYZ123444 | Unique Transaction ID of the transaction |
utilitycode | Mandatory | VMCASHIN | Transaction type that Identifies the Wallet you are sending money to. Refer to Utilitycode Definitions for WalletCashin section below. |
utilityref | Mandatory | 075XXXXXXX | Mobile number that identifies the wallet |
amount | Mandatory | 1000 | Transaction amount |
vendor | Mandatory | 01234567891 | Float account identifier |
pin | Mandatory | 01234567891 | Float account PIN |
msisdn | Optional | 06534567891 | End-user or initiator mobile number. |
Wallet Cashin Name Look Up
HTTP Request
GET http://example.com/v1/walletcashin/namelookup?utilitycode=VMCASHIN&utilityref=XYZ123444&transid=1001
Query Parameters
Parameter | Type | Example | Description |
---|---|---|---|
utilitycode | Mandatory | VMCASHIN | Utility Type Identifier |
utilityref | Mandatory | 25575XXXXXXXXX | Mobile number associated with the wallet |
transid | Mandatory | XYZ123444 | Transaction ID to match request and response. Transid used for lookup can be used for transaction call. transid field cannot duplicate for multiple transaction calls. |
Luku Lookup Sample response:
{
"reference":"6927759116",
"transid":"10001",
"resultcode":"000",
"result":"SUCCESS",
"message":"Name fetch successful",
"data":[
{
"name":"FIROZ MOH"
}
]
}
GEPG Lookup Sample response:
{
"reference":"6927768243",
"transid":"10001",
"resultcode":"000",
"result":"SUCCESS",
"message":"DAWASA\nName MNYANGA\nControl# 99104217XXXX\nTZS 5,000",
"data":[
{
"name":"MNYANGA",
"amount":"5000",
"institution":"DAWASA",
"type":"PART",
"desc":"Bill Charges 2019-2"
}
]
}
Query Transaction Status
Query status of the Walelt Cashin transaction in case of a timeout or ambigous response.
HTTP Request
GET http://example.com/v1/walletcashin/query?transid=XYZ123444
Query Parameters
Parameter | Type | Example | Description |
---|---|---|---|
transid | Mandatory | XYZ123444 | Unique Transaction ID of the transaction |
Utilitycode Definitions for WalletCashin
Utilitycode | Category | Ref Label | Ref Type | Ref Eg. | LookUp Avail | Description |
---|---|---|---|---|---|---|
VMCASHIN | Wallet | Mobile No | Numeric(10,12) | 076XXXXXXX | No | Vodacom Mpesa cashin |
AMCASHIN | Wallet | Mobile No | Numeric(10,12) | 068XXXXXXX | Yes | AirtelMoney cashin |
TPCASHIN | Wallet | Mobile No | Numeric(10,12) | 065XXXXXXX | Yes | TigoPesa cashin |
EZCASHIN | Wallet | Mobile No | Numeric(10,12) | 077XXXXXXX | Yes | EzyPesa cashin |
SPCASHIN | Wallet | Mobile No or Card No | Numeric(10,12,16) | 076XXXXXXX | Yes | SelcomCard cashin |
HPCASHIN | Wallet | Mobile No | Numeric(10,12) | 062XXXXXXX | Yes | HaloPesa cashin |
TTCASHIN | Wallet | Mobile No | Numeric(10,12) | 073XXXXXXX | Yes | TTCLPesa cashin |
POS/Agent Cashout
Agent Cashout Process
The API allows thrid party businesses to send funds to a customer for a direct cashout option at Selcom Huduma agents. The API, upon debiting the float balance credits a temporary wallet of the customer on the Selcom platform, which the customer can access dialing *150*50#
and selecting option 4 Selcom, ‘Huduma Cashout’. The customer can visit any Selcom Huduma agent, dial the shortcode, enter agent code and amount to complete the withdrawal process before receiving cash from Agent.
HTTP Request
POST http://example.com/v1/hudumacashin/process
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
transid | Mandatory | XYZ123444 | Unique Transaction ID of the transaction |
utilitycode | Mandatory | HUDUMACI | Transaction type that Identifies the type of cashout. Use HUDUMACI for Agent cashout |
utilityref | Mandatory | 075XXXXXXX | Mobile number of the customer whom the token/voucher will be send |
amount | Mandatory | 1000 | Transaction amount |
vendor | Mandatory | VENDORXYZ | Float account identifier |
pin | Mandatory | 3122 | Float account PIN |
name | Optional | John Mushi | Name of the customer |
Cashout Sample response:
{
"reference":"6927759116",
"transid":"10001",
"resultcode":"000",
"result":"SUCCESS",
"message":"0312332222 Confirmed. You have received TZS 1,000 from VENDORXYZ. Dial *150*50# choose Selcom Huduma Cashout to cashout at any Selcom Huduma agent.",
"data":[
]
}
Query Transaction Status
Query status of the POS/Agent Cashout transaction in case of a timeout or ambigous response.
HTTP Request
GET http://example.com/v1/hudumacashin/query?transid=XYZ123444
Utilitycode Definitions for Agent Cashout
Utilitycode | Category | Ref Label | Ref Type | Ref Eg. | LookUp Avail | Description |
---|---|---|---|---|---|---|
HUDUMACI | Agent | Mobile No | Numeric(10,12) | 076XXXXXXX | No | POS/Agent cashout |
Float Account Management
Get Float Balance
Get available balance from float account.
HTTP Request
POST http://example.com/v1/vendor/balance
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
vendor | Mandatory | 01234567891 | Float account identifier |
pin | Mandatory | 01234567891 | Float account PIN |
Balance Sample response:
{
"reference":"6927759116",
"transid":"10001",
"resultcode":"000",
"result":"SUCCESS",
"message":"Balance successful",
"data":[
{
"balance":"1000000"
}
]
}
C2B/Collection Services
This is a realtime API which is invoked when a payment is received from one of Selcom channels to be posted to third party systems. Channels include mobile wallets, bank accounts, POS and non-POS Selcom Huduma/Huduma+ agents. The API is intiated from Selcom Gateway notifying third party system.
Authentication
All requests will include authentication token “Bearer $token” in header. Token will be shared by 3rd party. The authentication method for this API is different the one description at the first section of the documentation as its consumed by Selcom Gateway from thirdparty.
Authorization: Bearer lfksa823wera342o23
,
Content-Type: application/json
Payment Validation
Payment validation leg, verify amount, utility reference, phone number etc. A timeout or failure from this API return failure to the source channel and auto reverse the funds.
Request Format
POST /validation HTTP/1.1
Parameter | Type | Example | Description |
---|---|---|---|
operator | Available | AIRTELMONEY | Name of the channel. Values passed for mobile wallet originating transactions (AIRTELMONEY, MPESA-TZ, TIGOPESATZ, HALOPESATZ, TTCLMOBILE and ZANTELEZPESA) |
transid | Available | XYZ123444 | Unique Transaction ID of the transaction |
reference | Available | 033XX12211 | Unique transaction Identifier from Selcom Gateway |
utilityref | Available | 075XXXXXXX | Mobile number of the customer whom the token/voucher will be send |
amount | Available | 1000 | Transaction amount |
msisdn | Available | 06534567891 | End-user or initiator mobile number. |
Expected Response Format
Response Field | Description |
---|---|
reference | Same value as in request |
resultcode | Error codes. Refer to Expected Error codes from thirdpary businesses section for better guideness |
result | Transaction status. SUCCESS ro FAILED. This value is not used. |
message | Error description |
name | Name of the customer associated with the account or utilityref (Optional) |
Payment Notification
Payment confirmation after successful validation. The payload is exactly same as validate api. A timeout or no response from this API return not auto reverse funds on the source channel, transactions will be held on ambiguous status for manual recon process to be completed.
Request Format
POST /notification HTTP/1.1
Parameter | Type | Example | Description |
---|---|---|---|
operator | Available | AIRTELMONEY | Name of the channel. Values passed for mobile wallet originating transactions (AIRTELMONEY, MPESA-TZ, TIGOPESATZ, HALOPESATZ, TTCLMOBILE and ZANTELEZPESA) |
transid | Available | XYZ123444 | Unique Transaction ID from the channel |
reference | Available | 033XX12211 | Unique transaction Identifier from Selcom Gateway |
utilityref | Available | 075XXXXXXX | Mobile number of the customer whom the token/voucher will be send |
amount | Available | 1000 | Transaction amount |
msisdn | Available | 06534567891 | End-user or initiator mobile number. |
Expected Response Format
Response Field | Description |
---|---|
reference | Same value as in request |
resultcode | Error codes. Refer to Expected Error codes from thirdparty business section for better guideness |
result | Transaction status. SUCCESS ro FAILED. This value is not used. |
message | Error description |
Expected Error codes from thirdparty business
Error Code | Meaning |
---|---|
000 | Success. |
010 | Invalid account or payment reference (utilityref) |
012 | Invalid amount |
014 | Amount too high |
015 | Amount too low |
4XX | for other failure cases from your system. |
Wallet Pull Funds (Push USSD)
This API is used to trigger or push the USSD menu of a given wallet with a PIN entry request. A success response from this API shall not mean the customer wallet has been debited; it only means that the customer's wallet provider returned a successful response to a push request. The business will be notified of the transaction having been completed through usual C2B notification means.
HTTP Request
POST http://example.com/v1/wallet/pushussd
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
reference | Mandatory | XYZ123444 | Unique Transaction ID of the transaction |
utilityref | Mandatory | 075XXXXXXX | Payment reference or account number from business who will recieve the funds or paid against |
amount | Mandatory | 1000 | Transaction amount |
vendor | Mandatory | 01234567891 | Float account identifier |
msisdn | Mandatory | 06534567891 | Wallet mobile number to which push ussd should be triggered to complate wallet authentication |
Query C2B Transaction Status
This API is used to check the status of a C2B transaction using Selcom unique reference. The reference returned during Wallet Pull funds (Push USSD)
API or Selcom reference passed during validation. In cases when transaction notification is not received for a succcessfully validated c2b collection transaction clients can check the status of the transaction against Selcom gateway.
HTTP Request
GET http://example.com/v1/c2b/query-status
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
reference | Mandatory | XYZ123444 | Unique transaction Identifier from Selcom Gateway |
Status Response
Response Field | Description |
---|---|
reference | Same value as in request |
resultcode | Error codes. Refer to Expected Error codes from thirdparty business section for better guideness |
result | Transaction status. SUCCESS ro FAILED. This value is not used. |
message | Error description |
Sample response:
{
"reference":"6927759116",
"transid":"10001",
"resultcode":"000",
"result":"SUCCESS",
"message":" | COMPLETE | CONFIRMED | Payment successful\nUtility 255620685292\nAmt TZS 15,000\nTransID NBCBULK-0000024388-154\nReference 0406046312\n#RunsOnSelcom",
"data":[
]
}
Qwiksend
Qwiksend is a Selcom's Interbank product for banks to send money to another bank. API is currently available only to banks in Tanzania.
Bank Transfer
HTTP Request
POST http://example.com/v1/qwiksend/process
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
transid | Mandatory | XYZ123444 | Unique Transaction ID of the transaction |
destBank | Mandatory | AKIBA | Destination bank shortocde. Refer to List of Bank Short Names section |
destAccount | Mandatory | 1234567890 | Destination account number |
srcAccount | Mandatory | 01234567891 | Source account number |
srcAccountName | Mandatory | ROBERT MUSHI | Source account holder name |
amount | Mandatory | 1000 | Transaction amount |
vendor | Mandatory | BANKX | Float account identifier ( Used to identify the source service provider) |
pin | Mandatory | 4343 | Float account PIN |
msisdn | Mandatory | 01234567891 | End-user mobile number |
Account Name Lookup
HTTP Request
GET http://example.com/v1/qwiksend/lookup/?bank=AKIBA&account=XYZ123444&transid=1001
Query Parameters
Parameter | Type | Example | Description |
---|---|---|---|
bank | Mandatory | AIBA | Bank short name |
account | Mandatory | XYZ123444 | Account number |
transid | Mandatory | XYZ123444 | Transaction ID to match request and response. Transid used for lookup can be used for transaction call. transid field cannot duplicate for multiple transaction calls. |
Query Transaction Status
Query status of the Qwiksend transaction in case of a timeout or ambigous response.
HTTP Request
GET http://example.com/v1/qwiksend/query?transid=XYZ123444
Query Parameters
Parameter | Type | Example | Description |
---|---|---|---|
transid | Mandatory | XYZ123444 | Unique Transaction ID of the transaction |
List of Bank Short Names
Bank Shortcode | Look Up Avail | Bank Name |
---|---|---|
AKIBA | No | AKIBA Bank PLC |
ACCESSBANK | No | Access Bank |
VCN
Create VCN
HTTP Request
POST http://example.com/v1/vcn/create
Sample:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "Authorization: SELCOM {authorization-token}"
-H "Digest-Method: {digest-token}"
-H "Digest: {digest}"
-H "Timestamp: {timestamp in yyyy-dd-mm H:i:s format}"
-H "Signed-Fields: msisdn,account,first_name,last_name,middle_name,gender,dob,address,city,region,nationality,validity,email,language"
-d '{"msisdn":"25577XXXXXXXX", "account" : "013222244", "first_name":"ROBERT", "last_name":"MUSHI", "middle_name":"E", "gender":"MALE", "dob":"07112988", "address": "Plot no 99, UN Road", "city": "Dar es Salaam", "region":"Dar es Salaam", "nationality": "TANZANIAN", "validity": "12", "email":"robert@example.com", "language":"en", "vendor":"XYZBANK", "pin":"4321", "product_code": "AAVCN001"}
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "VCN creation success",
"data": {
"card_id": "0000021111",
"masked_card" "533322******0320"
}
}
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
msisdn | Mandatory | 255781234567 | Customer mobile number in international format(must be a valid TZ mobile number) |
account | Mandatory | 013222244 | Wallet Account number or Bank account number |
first_name | Mandatory | ROBERT | First name of the customer |
last_name | Mandatory | MUSHI | Last name of the customer |
middle_name | Optional | E | Middle name of the customer |
gender | Mandatory | MALE | Gender. Must be MALE or FEMALE |
dob | Mandatory | 11071987 | Date of Birth (DDMMYYYY format) |
address | Mandatory | Mktaba St, Upanga | Street and Area |
city | Mandatory | Dar es Salaam | City of residence |
region | Optional | Dar es Salaam | Region |
nationality | Mandatory | Tanzanian | Nationality |
validity | Optional | 12 | No fo months the VCN should be valid, after which it will expire. Must be 6 , 12 or 24, Default 24 months. |
Optional | test@example.com | Email address | |
language | Optional | sw | Customer language preference (to personalize responses). en for english and sw for kswahili. |
marital_status | Optional | SINGLE | Marital status MARRIED, SINGLE, DIVORCED, WIDOW |
maiden_name | Optional | EPHRAIM | Mothers maiden name |
vendor | Mandatory | XTZBANK | Float account identifier |
pin | Mandatory | 4321 | Float account PIN |
transid | Mandatory | XYZ123444 | Unique Transaction ID of the transaction (Required as the vendor will be shared the fee) |
product_code | Optional | AAVCN001 | A static product code assigned for the VCN product specific to the issuer |
Block/Unblock/Suspend Card (Change Status)
HTTP Request
POST http://example.com/v1/vcn/changestatus
Sample:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "Authorization: SELCOM {authorization-token}"
-H "Digest-Method: {digest-token}"
-H "Digest: {digest}"
-H "Timestamp: {timestamp in yyyy-dd-mm H:i:s format}"
-H "Signed-Fields: msisd,account,status,remarks"
-d '{"msisdn":"25577XXXXXXXX", "account":"T1000932222", "status":"BLOCK", "remarks":"LOST"}
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "VCN status change successful",
"data": {
"new_status":"BLOCKED"
}
}
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
msisdn | Mandatory | 255781234567 | Customer mobile number using during VCN registration in international format(must be a valid TZ mobile number) |
account | Mandatory | T1000932222 | Wallet Account number or Bank account number |
status | Mandatory | BLOCK | New status of the card to be set. Must be BLOCK or UNBLOCK or SUSPEND. SUSPEND status ends the card's life cycle. |
remarks | Optional | LOST | Reason for change status (from customer) |
card_id | Optional | 0113322 | Unique card ID return on create API call. Required only One customer with multiple card scenario and when multiple product allocated for the same issuer |
requestid | Mandatory | XYZ123444 | Unique Request ID for the request (this is not transid as its not a financial transaction on Selcom side) |
language | Optional | SW | Language to use for SMS response to end customer (EN - English, SW - Swahili) |
Show Card
API is used to push VCN card info to the customer by delivering a secure link to the customer
HTTP Request
POST http://example.com/v1/vcn/show
Sample:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "Authorization: SELCOM {authorization-token}"
-H "Digest-Method: {digest-token}"
-H "Digest: {digest}"
-H "Timestamp: {timestamp in yyyy-dd-mm H:i:s format}"
-H "Signed-Fields: msisdn,account"
-d '{"msisdn":"25577XXXXXXXX", "account":"T1000932222"}''
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "VCN details sent to customer msisdn",
"data": {}
}
}
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
msisdn | Mandatory | 255781234567 | Customer mobile number using during VCN registration in international format(must be a valid TZ mobile number) |
account | Mandatory | T1000932222 | Account number of the VCN returned on create api call |
card_id | Optional | 0113322 | Unique card ID return on create API call. Required only One customer with multiple card scenario and when multiple product allocation for the same issuer |
requestid | Mandatory | XYZ123444 | Unique Request ID for the request (this is not transid as its not a financial transaction on Selcom side) |
language | Optional | SW | Language to use for SMS response to end customer (EN - English, SW - Swahili) |
Get Card Status
The API is used to get the current VCN card status. No sms will be triggered to end customer on using this API
HTTP Request
GET http://example.com/v1/vcn/status?msisdn=25577XXXXXXXX&account=T1000932222
Sample:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "Authorization: SELCOM {authorization-token}"
-H "Digest-Method: {digest-token}"
-H "Digest: {digest}"
-H "Timestamp: {timestamp in yyyy-dd-mm H:i:s format}"
-H "Signed-Fields: msisdn,account"
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "VCN status fetch successful",
"data": [{
"masked_card":"512342XXXXXX1234",
"status":"UNBLOCKED"
}]
}
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
msisdn | Mandatory | 255781234567 | Customer mobile number using during VCN registration in international format(must be a valid TZ mobile number) |
account | Mandatory | T1000932222 | Account number of the VCN returned on create api call |
Set Transaction Limit
Set transaction limit for ecommerce transactions for the VCN
HTTP Request
POST http://example.com/v1/vcn/set-limit
Sample:
# With shell, you can just pass the correct header with each request
curl "api_endpoint_here"
-H "Authorization: SELCOM {authorization-token}"
-H "Digest-Method: {digest-token}"
-H "Digest: {digest}"
-H "Timestamp: {timestamp in yyyy-dd-mm H:i:s format}"
-H "Signed-Fields: msisd,account,status,remarks"
-d '{"msisdn":"25577XXXXXXXX", "account":"T1000932222", "limit_amount":"100000", "limit_type":"DAILY"}
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "Limit set successful",
"data": [{
}]
}
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
msisdn | Mandatory | 255781234567 | Customer mobile number using during VCN registration in international format(must be a valid TZ mobile number) |
account | Mandatory | T1000932222 | Wallet Account number or Bank account number |
limit_amount | Mandatory | 100000 | Limit amount. |
limit_type | Mandatory | MONTHLY | Transaction limit period/type (Supported types DAILY, MONTHLY, TRANSACTION) |
card_id | Optional | 0113322 | Unique card ID return on create API call. Required only One customer with multiple card scenario and when multiple product allocated for the same issuer |
Checkout API
This allows you to consume selcom's payment gateway for a complete ecommerce check process that supports Masterpass, Debit/Credit cards (Master, VISA. Amex), Mobile Money pull payments etc. Refer to the below process flow.
On demand subcription or stored card payment flow.
Create Order
Create a new order post checkout from your ecommerce website. Card payments with no billing info will get rejected. Note: All urls in the request and response are base64 encoded.
HTTP Request
POST http://example.com/v1/checkout/create-order
Sample:
# With shell, you can just pass the correct header with each request
curl "https://apigw.selcommobile.com/v1/vcn/create" \
-H "Authorization: SELCOM {authorization-token}" \
-H "Digest-Method: {digest-token}" \
-H "Digest: {digest}" \
-H "Timestamp: {timestamp in yyyy-dd-mm H:i:s format}" \
-H "Signed-Fields: vendor,order_id,buyer_email,buyer_name,buyer_user_id,buyer_phone,buyer_gateway_token,amount,currency,payment_methods,redirect_url,cancel_url,webhook,billing.firstname,billing.lastname,billing.address_1,billing.address_2,billing.city,billing.state_or_region,billing.postcode_or_pobox,billing.country,billing.email, billing.phone,shipping.firstname,shipping.lastname,shipping.address_1, shipping.address_2,shipping.city,shipping.state_or_region,shipping.country,shipping.email,shipping.phone,payer_remarks,merchant_remarks,order_items" \
-d '{
"vendor":"12323232",
"order_id":"121212",
"buyer_email": "",
"buyer_name": "",
"buyer_user_id": "",
"buyer_phone": "",
"gateway_buyer_uuid": "",
"amount": 8000,
"currency":"TZS",
"payment_methods":"ALL",
"redirect_url":"URL",
"cancel_url":"URL",
"webhook":"URL",
"billing": {
"firstname" : "John",
"lastname" : "Doe",
"address_1" : "969 Market",
"address_2" : "",
"city" : "San Francisco",
"state_or_region" : "CA",
"postcode_or_pobox" : "94103",
"country" : "US",
"phone" : "255682852526"
},
"shipping": {
"firstname" : "John",
"lastname" : "Doe",
"address_1" : "969 Market",
"address_2" : "",
"city" : "San Francisco",
"state_or_region" : "CA",
"postcode_or_pobox" : "94103",
"country" : "US",
"phone" : "255682852526"
},
"buyer_remarks":"None",
"merchant_remarks":"None",
"no_of_items": 3
}'
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "Order creation successful",
"data": [{"gateway_buyer_uuid":"12344321", "payment_token":"80008000", "qr":"QR", "payment_gateway_url":"http:example.com/Ahesmey"}]
}
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
vendor | Mandatory | SHOP203 | Vendor/Merchant ID allocated by Selcom |
order_id | Mandatory | 123 | Order id that uniquely identifies the order |
buyer_email | Mandatory | customer@example.com | Buyer email |
buyer_name | Mandatory | Joe John | Buyer's full name |
buyer_userid | Option | joejohn20 | Buyers unique user-id in the thridparty ecommerce website. Should be empty for guest check |
buyer_phone | Mandatory | 255781234XXX | Buyers msisdn |
gateway_buyer_uuid | Option | A1233232 | Used to display stored card in the payment process. The field is returned first time the user creates an order |
amount | Mandatory | 5000 | Order amount |
currency | Mandatory | TZS | International currency code TZS, USD |
payment_methods | Mandatory | ALL | Has to be comma separated list of ALL, MASTERPASS, CARD, MOBILEMONEYPULL |
redirect_url | Optional | aHR0cDovL3VybC5jb20= | Base64 encoded thirdparty ecommerce page url that the customer should be redirected after payment process is complete |
cancel_url | Optional | aHR0cDovL3VybC5jb20= | Base64 encoded thirdparty ecommerce page url that the customer should be redirected when payment process canceled by the buyer |
webhook | Optional | aHR0cDovL3VybC5jb20= | Base64 encoded webhook callback url to recieve API call back of the payment status |
billing.firstname | Mandatory | Joe | First name - Payment Billing info |
billing.lastname | Mandatory | John | Last name - Payment Billing info |
billing.address_1 | Mandatory | 23, street X | Address 1 - Payment Billing info |
billing.address_2 | Optional | Upanga Area | Address 2 - Payment Billing info |
billing.city | Mandatory | Dar es salaam | City - Payment Billing info |
billing.state_or_region | Mandatory | Dar es Salaam | Region - Payment Billing info |
billing.postcode_or_pobox | Mandatory | 43434 | PO Box- Payment Billing info |
billing.country | Mandatory | TZ | International Country code - Payment Billing info |
billing.phone | Mandatory | 25578123XXXX | Phone - Payment Billing info |
shipping.firstname | Optional | Joe | First name - Payment Billing info |
shipping.lastname | Optional | John | Last name - Payment Billing info |
shipping.address_1 | Optional | 23, street X | Address 1 - Payment Billing info |
shipping.address_2 | Optional | Upanga Area | Address 2 - Payment Billing info |
shipping.city | Optional | Dar es salaam | City - Payment Billing info |
shipping.state_or_region | Optional | Dar es Salaam | Region - Payment Billing info |
shipping.postcode_or_pobox | Optional | 43434 | PO Box- Payment Billing info |
shipping.country | Optional | TZ | International Country code - Payment Billing info |
shipping.phone | Optional | 25578123XXXX | Phone - Payment Billing info |
buyer_remarks | Optional | 255781234567 | Payer remark/decription for the order |
merchant_remarks | Optional | 255781234567 | Buyer remark/decription for the order |
no_of_items | Mandatory | 255781234567 | No of items in the order |
header_colour | Optional | #FF0012 | Payment gateway page header colour |
link_colour | Optional | #FF0012 | Payment gateway page link text colour |
button_colour | Optional | #FF0012 | Payment gateway page button colour |
Create Order - Minimal
Create a new order post checkout from your ecommerce website for non-card payments. This api cannot be used for card payments. Card payment option wont be displayed on the payment gateway page after redirection. Ideal for mobile wallet push payments and manual payments when merchant is capable of presenting the payment token or qr code to the customer. Note: All urls in the request and response are base64 encoded.
HTTP Request
POST http://example.com/v1/checkout/create-order-minimal
Sample:
# With shell, you can just pass the correct header with each request
curl "https://apigw.selcommobile.com/v1/vcn/create" \
-H "Authorization: SELCOM {authorization-token}" \
-H "Digest-Method: {digest-token}" \
-H "Digest: {digest}" \
-H "Timestamp: {timestamp in yyyy-dd-mm H:i:s format}" \
-H "Signed-Fields: vendor,order_id,buyer_email,buyer_name,buyer_user_id,buyer_phone,amount,currency,payment_methods,webhook,payer_remarks,merchant_remarks,order_items" \
-d '{
"vendor":"12323232",
"order_id":"121212",
"buyer_email": "john@example.com",
"buyer_name": "John Joh",
"buyer_phone": "255682XXXXXX",
"amount": 8000,
"currency":"TZS",
"webhook":"https://merchantdomain.com/process-order/121212",
"buyer_remarks":"None",
"merchant_remarks":"None",
"no_of_items": 1
}'
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "Order creation successful",
"data": [{"gateway_buyer_uuid":"12344321", "payment_token":"80008000", "qr":"QR", "payment_gateway_url":"aHR0cDpleGFtcGxlLmNvbS9wZy90MTIyMjI="}]
}
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
vendor | Mandatory | SHOP203 | Vendor/Merchant ID allocated by Selcom |
order_id | Mandatory | 123 | Order id that uniquely identifies the order |
buyer_email | Mandatory | customer@example.com | Buyer email |
buyer_name | Mandatory | Joe John | Buyer's full name |
buyer_phone | Mandatory | 255781234XXX | Buyers msisdn |
amount | Mandatory | 5000 | Order amount |
currency | Mandatory | TZS | International currency code TZS, USD |
redirect_url | Optional | aHR0cDovL3VybC5jb20= | Base64 encoded thirdparty ecommerce page url that the customer should be redirected after payment process is complete |
cancel_url | Optional | aHR0cDovL3VybC5jb20= | Base64 encoded thirdparty ecommerce page url that the customer should be redirected when payment process canceled by the buyer |
webhook | Optional | aHR0cDovL3VybC5jb20= | Base64 encoded webhook callback url to recieve API call back of the payment status. |
buyer_remarks | Optional | 255781234567 | Payer remark/decription for the order |
merchant_remarks | Optional | 255781234567 | Buyer remark/decription for the order |
no_of_items | Mandatory | 255781234567 | No of items in the order (No of product times no items) |
header_colour | Optional | #FF0012 | Payment gateway page header colour |
link_colour | Optional | #FF0012 | Payment gateway page link text colour |
button_colour | Optional | #FF0012 | Payment gateway page button colour |
expiry | Optional | 60 | Expiry in minutes |
Cancel Order
Cancel an order before customer completes the payment. An expired or completed order cannot be cancelled.
HTTP Request
DELETE http://example.com/v1/checkout/cancel-order?order_id={order_id}
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "Order cancellation successful",
"data": []
}
,
Get Order Status
Get status of an order.
HTTP Request
GET http://example.com/v1/checkout/order-status?order_id={order_id}
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "Order fetch successful",
"data": [{"order_id":"123", "creation_date":"2019-06-06 22:00:00", "amount":"1000", "payment_status":"PENDING","transid":null,"channel":null,"reference":null,"phone":null}]
}
JSON Response data field
Parameter | Description |
---|---|
payment_status | Payment Status (PENDING, COMPLETED, CANCELLED, USERCANCELLED, REJECTED,INPROGRESS) |
order_id | Order id |
creation_date | Order creation date |
amount | Order amount |
transid | Unique transaction identifier from the payment channel. Available on COMPLETED payments only |
channel | Channel name Eg AIRTELMONEY. Available on COMPLETED payments only |
reference | PG unique payment identifier. Available on COMPLETED payments only |
msisdn | Mobile number involved in the payment incase of a wallet / mastercard QR payment. Available on COMPLETED payments only |
List All Orders
HTTP Request
GET http://example.com/v1/checkout/list-orders?fromdate={YYYY-MM-DD}&todate={YYYY-MM-DD}
Below sample response:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "Order fetch successful",
"data": [{"order_id":"123", "creation_date":"2019-06-06 22:00:00", "amount":"1000", "payment_status":"PENDING"}, {"order_id":"124", "creation_date":"2019-06-06 22:10:00", "amount":"2000", "payment_status":"CANCEL"}]
}
JSON Response data field
Parameter | Description |
---|---|
result | Result of the order submitted (FAIL, SUCCESS, PENDING) |
payment_status | Payment Status (PENDING, COMPLETED, CANCELLED, USERCANCELLED, REJECTED,INPROGRESS) |
order_id | Order id |
creation_date | Order creation date |
Fetch Stored Card Tokens
This API allows the eccomerce website to fetch stored cards for specific user passing the gateway_buyer_uuid that was generated for each user on there first order creation.
HTTP Request
GET http://example.com/v1/checkout/stored-cards?gateway_buyer_uuid={gateway_buyer_uuid}&buyer_userid={buyer_userid}
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
buyer_userid | Mandatory | 23 | Buyers unique user-id in the thridparty ecommerce website. Same as create order request. |
gateway_buyer_uuid | Mandatory | 124343434 | Gateway Buyer UUID returned during order creation first time a buyer created an order |
Below sample response:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "Order fetch successful",
"data": [{"masked_card":"5555-12XX-XXXX-1234", "creation_date":"2019-06-06 22:00:00", "card_token":"ABC123423232", "name":"JOE JOHN", "card_type":"001"}, {"masked_card":"5555-12XX-XXXX-4321", "creation_date":"2019-06-06 23:00:00", "card_token":"ABC123423244", "name":"JOE JOHN", "card_type":"001"}]
}
JSON Response data field
Parameter | Description |
---|---|
masked_card | Masked card number |
creation_date | Card token creation date |
name | Full name of the hard holder |
card_type | Card type (001 - Visa, 002 - Mastercard) |
card_token | Card token |
id | Unique Resouce id |
Delete Stored Card
This API allows the eccomerce website to delete stored cards for specific user passing the gateway_buyer_uuid that was generated for each user on there first order creation.
HTTP Request
DELETE http://example.com/v1/checkout/delete-card?id={card-resource-id}&gateway_buyer_uuid={gateway_buyer_uuid}
JSON Payload Parameters
Parameter | Type | Example | Description |
---|---|---|---|
id | Mandatory | 23 | Stored card resource id |
gateway_buyer_uuid | Mandatory | 124343434 | Gateway Buyer UUID returned during order creation first time a buyer created an order |
Below sample response:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "Delete successful",
"data": []
}
Process Order - Card Payment
Process Order api allows the ecommerce website to process an order using stored cards directly without redirecting the user to payment gateway page. Can be used for in-app payments where users can select stored cards or for ondemand subscription type recurring payments.
HTTP Request
POST http://example.com/v1/checkout/card-payment
Parameter | Type | Example | Description |
---|---|---|---|
transid | Mandatory | A1234 | Unique transaction ID |
vendor | Mandatory | SHOW01 | Vendor/Merchant ID allocated by Selcom |
order_id | Mandatory | 123 | Order ID |
card_token | Mandatory | ABC123423232 | Card token fetched using Fetch Stored Tokenised Cards for Specific User API |
buyer_userid | Mandatory | joejohn20 | Buyers unique user-id in the thridparty ecommerce website. Should be empty for guest check |
gateway_buyer_uuid | Mandatory | 124343434 | Gateway Buyer UUID returned during order creation first time a buyer created an order |
Sample:
# With shell, you can just pass the correct header with each request
curl "http://example.com/v1/checkout/card-payment"
-H "Authorization: SELCOM {authorization-token}"
-H "Digest-Method: {digest-token}"
-H "Digest: {digest}"
-H "Timestamp: {timestamp in yyyy-dd-mm H:i:s format}"
-H "Signed-Fields: transid,order_id,card_token,buyer_gateway_token"
-d '{"transid":"T123442", "order_id":"123", "card_token":"ABC123423232", "buyer_gateway_token":"12344321"}
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "111",
"result" : "PENDING",
"message" : "Request in progress. You will receive a callback shortly.",
"data": []
}
Process Order - Wallet Pull Payment
Process Order api allows the ecommerce website to process an order using mobile wallets directly without redirecting the user to payment gateway page. Can be used for in-app payments where users can select linked mobile numbers, tigger this api call to reiceve a PUSH ussd from the mobile wallet to complete the transaction. The feature is currently supported only by TigoPesa and AirtelMoney.
HTTP Request
POST http://example.com/v1/checkout/wallet-payment
Parameter | Type | Example | Description |
---|---|---|---|
transid | Mandatory | A1234 | Unique transaction ID |
order_id | Mandatory | 123 | Order ID |
msisdn | Mandatory | 2556828XXXXX | Billing wallet mobile from which the merchant want to pull funds from using Push USSD authorization |
Sample:
# With shell, you can just pass the correct header with each request
curl "http://example.com/v1/checkout/card-payment"
-H "Authorization: SELCOM {authorization-token}"
-H "Digest-Method: {digest-token}"
-H "Digest: {digest}"
-H "Timestamp: {timestamp in yyyy-dd-mm H:i:s format}"
-H "Signed-Fields: transid,order_id,billing_msisdn"
-d '{"transid":"T123442", "order_id":"123", "msisdn":"2556828XXXXX"}
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "111",
"result" : "PENDING",
"message" : "Request in progress. You will receive a callback shortly.",
"data": []
}
Webhook Callback
Payment status callback api from payment gateway to ecommerce website.
HTTP Request
Parameter | Type | Example | Description |
---|---|---|---|
transid | Mandatory | A1234 | Thirdparty transaction id same as payment request |
order_id | Mandatory | 123 | Order ID |
reference | Mandatory | 0289124234 | Selcom Gateway transaction reference |
result | Mandatory | SUCCESS | Status of the transaction SUCCESS, FAIL |
resultcode | Mandatory | 000 | Error code |
payment_status | Mandatory | COMPLETE | Status of the payment COMPLETED, CANCELLED, PENDING, USERCANCELED |
Sample:
# With shell, you can just pass the correct header with each request
curl "{thirdparty_site_webhook url}"
-H "Authorization: SELCOM {authorization-token}"
-H "Digest-Method: {digest-token}"
-H "Digest: {digest}"
-H "Timestamp: {timestamp in yyyy-dd-mm H:i:s format}"
-H "Signed-Fields: transid,order_id,reference,result,resultcode,payment_status"
-d '{"transid":"T123442", "reference":"028912121", "order_id":"123", "reference":"0281121212", "result":"SUCCESS", "resulcode":"000","payment_status":"COMPLETED"}
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "PENDING",
"message" : "Request in progress. You will receive a callback shortly.",
"data": []
}
Payment Refund
HTTP Request
POST http://example.com/v1/checkout/refund-payment
Parameter | Type | Example | Description |
---|---|---|---|
transid | Mandatory | R1234 | Unique transaction id for the refund request |
original_transid | Mandatory | A1234 | Transaction id of the orginal payment request for which refund is required. |
amount | Mandatory | 5000 | Refund amount |
Sample:
# With shell, you can just pass the correct header with each request
curl "http://example.com/v1/checkout/refund-payment"
-H "Authorization: SELCOM {authorization-token}"
-H "Digest-Method: {digest-token}"
-H "Digest: {digest}"
-H "Timestamp: {timestamp in yyyy-dd-mm H:i:s format}"
-H "Signed-Fields: transid,order_id,reference,result,resultcode,payment_status"
-d '{"transid":"T123442", "original_transid":"028912121", "amount":"123"}
The above command returns JSON structured like this:
{
"reference" : "0289999288",
"resultcode" : "111",
"result" : "INPROGRESS",
"message" : "Transaction Acknowledged",
"data": []
}
International Money Transfer API (IMT)
Send Money
An IMT Hub or Financial institution invokes this API to an FI connected to Selcom.
HTTP Request
POST http://example.com/v1/imt/send-money
Parameter | Type | Example | Description |
---|---|---|---|
messageId | M | M1234 | Unique transaction id for the refund request |
end2endId | M | E1234 | Transaction id of the orginal payment request for which refund is required. |
sender.firstname | M | John | First name of the sender |
sender.lastname | M | Mushi | Last name of the sender |
sender.country | M | UGA | Alpha 3 country code of the sender in ISO 3166 international standard |
sender.mobile | M | 25612345678 | Mobile number of the sender in international format without plus or 00 preix |
sender.idType | O | PASSPORT | KYC info. Identity document type of the sender. PASSWORD, DRIVERSLICENCE, NATIONALID etc |
sender.idNo | M | GS1002223 | KYC info. Identity document number |
recipient.firstname | M | Benjamin | First name of the recipient |
recipient.lastname | M | Sata | Last name of the recipient |
recipient.country | M | TZA | Alpha 3 country code of the recipient in ISO 3166 international standard |
recipient.mobile | M | 5000 | Mobile number of the receipient in international format without plus or 00 preix |
vendor | M | IMTHUB001 | Float account identifier. To be shared by selcom |
pin | M | 1212 | Float account pin. To be shared by selcom |
currency | M | 5000 | Transaction currency (3 character Alphabetic code in ISO 4217 standard) |
amount | M | 5000 | Transaction amount |
purpose | M | 5000 | Purpose of the IMT (GENERAL, BUSINESS, GIFT) |
personalMessage | O | "Happy birthday" | Personal message to be passed on to the recipient |
secretMessage | O | MANGO | Secret code or code number |
sourceFI.type | M | BANK | Source Financial institution type (AGENT,CARD,BANK,WALLET) |
sourceFI.name | M | Exim Bank | Name of the source Financial Institution |
sourceFI.country | M | UGA | Source FI country (Alpha 3 country code of the sender in ISO 3166 international standard) |
sourceFI.code | M | EXIMUGA | Source FI code (to be shared by selcom) |
sourceFI.account | M | 5000 | Senders account number (to be used for refund transaction in case of a failure or refund request from Destination FI) |
destinationFI.type | M | WALLET | Source Financial institution type (AGENT,CARD,BANK,WALLET) |
destinationFI.name | M | MPESA | Name of the destination FI |
destinationFI.country | M | 5000 | Destination FI country (Alpha 3 country code of the sender in ISO 3166 international standard) |
destinationFI.code | M | VMTZ | Destination FI code (to be shared by selcom) |
destinationFI.account | M | 25575123456 | Recipient account number |
Type: M - Mandatory, O - Optional and C - Conditional Mandatory
Request
{
"messageId": "2020070101",
"end2endId": "2020070101",
"sender":{
"firstname":"John",
"lastname":"White",
"country":"UUGA",
"mobile":"25632223232",
"idType": "OPTIONAL",
"idNo":"OPTTIONAL"
},
"recipient":{
"firstname":"John",
"lastname":"White",
"country":"TZA",
"mobile":"2556828XXXXX"
},
"vendor": "IMTHUB123",
"pin":"1221",
"currency":"USD",
"amount":"1000.00",
"purpose":"Personal",
"personalMessage":"Gift",
"secretMessage":"",
"sourceFI":{
"type":"AGENT,CARD,BANK,WALLET",
"name":"MARIAM FOREX SERVICES",
"country":"UGA",
"code": "PAYPAL",
"account":"0110000021",
},
"destinationFI":{
"type":"WALLET",
"name":"NMB BANK",
"account":"0110000021",
"code":"NMBTZ",
"country":"TZA"
}
}
Response
{
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "Refund request received",
"data": []
}
Transaction Status
HTTP Request
GET http://example.com/v1/imt/query?messageId=20200721001
Response 1
{
"messageId" : "20200721001",
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "Transaction successful",
}
Response 2
{
"messageId" : "20200721001",
"reference" : "0289999288",
"resultcode" : "999",
"result" : "AMBIGOUS",
"message" : "Transaction successful",
}
Response 3
{
"messageId" : "20200721001",
"reference" : "0289999288",
"resultcode" : "404",
"result" : "FAILED",
"message" : "Invalid Account number",
}
Response 4
{
"messageId" : "20200721001",
"reference" : "0289999288",
"resultcode" : "111",
"result" : "INPROGRESS",
"message" : "Transaction is being processed",
}
Query Parameters
Parameter | Type | Example | Description |
---|---|---|---|
messageId | Mandatory | XYZ123444 | Unique Transaction ID of the transaction |
Transaction Callback - Selcom to Thirdparty
HTTP Request
Parameter | Type | Example | Description |
---|---|---|---|
messageId | Mandatory | A1234 | Thirdparty transaction id same as payment request |
reference | Mandatory | 0289124234 | Selcom Gateway transaction reference |
result | Mandatory | SUCCESS | Status of the transaction SUCCESS, FAIL, INPROGRESS, |
resultcode | Mandatory | 000 | Error code, |
message | Mandatory | Success | Description |
Request
{
"messageId" : "20200721001",
"reference" : "0289999288",
"resultcode" : "000",
"result" : "SUCCESS",
"message" : "Transaction successful",
}
Response:
HTTP 200
Refund
HTTP Request
POST http://example.com/v1/imt/refund
The payload and the response is same as Send Money
IMT Errorcodes
Result | Resultcode | Description |
---|---|---|
SUCCESS | 000 | Transaction successful |
INPROGRESS | 111,001,002,003 | Receipt acknowledged. Transaction in progress please wait for callback or query transaction status to know the exact status of the transaction |
AMBIGOUS | 999 | Transactions status unknown wait for Manual recon process |
FAIL | All others | Transaction failed |
Error Codes
Errors
The Kittn API uses the following error codes:
Error Code | Meaning |
---|---|
400 | Bad Request -- Your request is invalid. |
401 | Unauthorized -- Your API key is wrong. |
403 | Forbidden -- The kitten requested is hidden for administrators only. |
404 | Not Found -- The specified kitten could not be found. |
405 | Method Not Allowed -- You tried to access a kitten with an invalid method. |
406 | Not Acceptable -- You requested a format that isn't json. |
410 | Gone -- The kitten requested has been removed from our servers. |
418 | I'm a teapot. |
429 | Too Many Requests -- You're requesting too many kittens! Slow down! |
500 | Internal Server Error -- We had a problem with our server. Try again later. |
503 | Service Unavailable -- We're temporarily offline for maintenance. Please try again later. |