NAV
shell php java

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

alt Ecommerce Flow

On demand subcription or stored card payment flow.

alt Stored Card 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.