NAV
shell php java python csharp nodejs

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.

Client Packages

Following are links to the client library code repositories on github and ways to install from online using package managers. For more information and source code visit the github pages.

PHP

Installation

composer require selcom/selcom-apigw-client

PHP GITHUB REPOSITORY

JAVA

Installation

Get Snippet for relevant package manager from https://central.sonatype.com/artifact/io.github.selcompaytechltd/apigwClient/1.0.3/overview

or search for io.github.selcompaytechltd/apigwClient using package manager

JAVA GITHUB REPOSITORY

CSHARP

Installation

dotnet add package selcom-apigw-client

CSHARP GITHUB REPOSITORY

PYTHON

Installation

pip install selcom_apigw_client

PYTHON GITHUB REPOSITORY

NODE.JS

Installation

npm i selcom-apigw-client

NODE.JS GITHUB REPOSITORY

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"}'

Selcom Developers uses API key and API secret to allow access to our APIs. Kindly reach out to our business team for further information on getting access

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:mm:ssTZD). 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, Use transaction query status API after 3 mins interval if the status remains unchanged, please consult our contact center (helpdesk@selcom.net)

Utility Payments

Utility Payment Request

Utility Payment Request Sample

# With shell, you can just pass the correct header with each request
curl -X POST 'http://example.com/v1/utilitypayment/process' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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,utilitycode,utilityref,amount,vendor,pin,msisdn" \
  -d '{
  "transid":"1218d5Qb",
  "utilitycode": "LUKU",
  "utilityref": "654944949",
  "amount":8000,
  "vendor":  "66546846845",
  "pin":"48585",
  "msisdn":"255055555555",
}'
require_once __DIR__ .'/vendor/autoload.php';

//  use module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret
$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$utilityPaymentArray = array(
  "transid"=>"1218d5Qb",
  "utilitycode"=> "LUKU",
  "utilityref"=> "654944949",
  "amount"=>8000,
  "vendor"=>  "66546846845",
  "pin"=>"48585",
  "msisdn"=>"255055555555",
  );

// path relatiive to base url
$utilityPaymentPath = "/v1/utilitypayment/process";

//make new payment
$response = $client->postFunc($utilityPaymentPath,$utilityPaymentArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String utilityPaymentPath = "/v1/utilitypayment/process";

// data
JsonObject utilityPaymentDict = new JsonObject();
utilityPaymentDict.addProperty("transid","1218d5Qb");
utilityPaymentDict.addProperty("utilitycode", "LUKU");
utilityPaymentDict.addProperty("utilityref", "654944949");
utilityPaymentDict.addProperty("amount" , 8000);
utilityPaymentDict.addProperty("vendor",  "66546846845");
utilityPaymentDict.addProperty("pin","48585");
utilityPaymentDict.addProperty("msisdn","255055555555");

//post utility payment
JsonObject response = client.postFunc(utilityPaymentPath ,utilityPaymentDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> utilityPaymentDict = new Dictionary<String,Object>() ;
utilityPaymentDictAdd("transid","1218d5Qb");
utilityPaymentDictAdd("utilitycode", "LUKU");
utilityPaymentDictAdd("utilityref", "654944949");
utilityPaymentDictAdd("amount" , 8000);
utilityPaymentDictAdd("vendor",  "66546846845");
utilityPaymentDictAdd("pin","48585");
utilityPaymentDictAdd("msisdn","255055555555");

// path relatiive to base url
String utilityPaymentPath = "/v1/utilitypayment/process";

//crate new utilityPayment
var utilityPaymentRespose = client.postFunc(utilityPaymentPath,utilityPaymentDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var utilityPaymentJson = {
  "transid":"1218d5Qb",
  "utilitycode": "LUKU",
  "utilityref": "654944949",
  "amount":8000,
  "vendor":  "66546846845",
  "pin":"48585",
  "msisdn":"255055555555",
};
// path relatiive to base url
var utilityPaymentPath = "/v1/utilitypayment/process"

//crate new utilityPayment
var = utilityPaymentRespose = client.postFunc(utilityPaymentPath, utilityPaymentJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
utilityPaymentDict = {
  "transid":"1218d5Qb",
  "utilitycode": "LUKU",
  "utilityref": "654944949",
  "amount":8000,
  "vendor":  "66546846845",
  "pin":"48585",
  "msisdn":"255055555555",
}
#path relatiive to base url
utilityPaymentPath = "/v1/utilitypayment/process"

#crate new utilityPayment
response = client.postFunc(utilityPaymentPath, utilityPaymentDict)

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

Utility Look Up Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/utilitypayment/lookup?utilitycode={utilitycode}&utilityref={utilityref}&transid={transid}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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: utilitycode,utilityref,transid" 
require_once __DIR__ .'/vendor/autoload.php';

// use module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$utilityLookUpArray = array(
  "utilitycode"=> "LUKU",
  "utilityref"=> "154944949",
  "transid"=>"1218d5Qb",
  );

// path relatiive to base url
$utilityLookUpPath = "/v1/utilitypayment/lookup";

// lookup utility
$response = $client->getFunc($utilityLookUpPath,$utilityLookUpArray);
//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String utilityLookUpPath = "/v1/utilitypayment/lookup";

// data
JsonObject utilityLookUpDict = new JsonObject();
utilityLookUpDict.addProperty("utilitycode", "LUKU");
utilityLookUpDict.addProperty("utilityref", "154944949");
utilityLookUpDict.addProperty("transid","1218d5Qb");

//lookup utility
JsonObject response = client.getFunc(utilityLookUpPath ,utilityLookUpDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> utilityLookUpDict = new Dictionary<String,Object>() ;
utilityLookUpDict.Add("utilitycode", "LUKU");
utilityLookUpDict.Add("utilityref", "154944949");
utilityLookUpDict.Add("transid","1218d5Qb");

// path relatiive to base url
String utilityLookUpPath = "/v1/utilitypayment/lookup";

//crate new utilityLookUp
var utilityLookUpRespose = client.getFunc(utilityLookUpPath,utilityLookUpDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var utilityLookUpJson = {
  "utilitycode": "LUKU",
  "utilityref": "154944949",
  "transid":"1218d5Qb"
};
// path relatiive to base url
var utilityLookUpPath = "/v1/utilitypayment/lookup"

//crate new utilityLookUp
var = utilityLookUpRespose = client.getFunc(utilityLookUpPath, utilityLookUpJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
utilityLookUpDict = {
  "utilitycode": "LUKU",
  "utilityref": "154944949",
  "transid":"1218d5Qb"
}
#path relatiive to base url
utilityLookUpPath = "/v1/utilitypayment/lookup"

#crate new utilityLookUp
response = client.getFunc(utilityLookUpPath, utilityLookUpDict)

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 Payment Status Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/utilitypayment/query?transid={transid}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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" 
require_once __DIR__ .'/vendor/autoload.php';

// use module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$utilityPaymentStatusArray = array("transid"=>"1218d5Qb");

// path relatiive to base url
$utilityPaymentStatusPath = "/v1/utilitypayment/query";

// query payment status
$response = $client->getFunc($utilityPaymentStatusPath,$utilityPaymentStatusArray);
//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String utilityPaymentStatusPath = "/v1/utilitypayment/query";

// data
JsonObject utilityPaymentStatusDict = new JsonObject();
utilityPaymentStatusDict.addProperty("transid","1218d5Qb");

//lookup utility
JsonObject response = client.getFunc(utilityPaymentStatusPath ,utilityPaymentStatusDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> utilityPaymentStatusDict = new Dictionary<String,Object>() ;
utilityPaymentStatusDict.Add("transid","1218d5Qb");

// path relatiive to base url
String utilityPaymentStatusPath = "/v1/utilitypayment/query";

//crate new utilityPaymentStatus
var utilityPaymentStatusRespose = client.getFunc(utilityPaymentStatusPath,utilityPaymentStatusDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var utilityPaymentStatusJson = {
  "transid":"1218d5Qb"
};
// path relatiive to base url
var utilityPaymentStatusPath = "/v1/utilitypayment/query"

//crate new utilityPaymentStatus
var = utilityPaymentStatusRespose = client.getFunc(utilityPaymentStatusPath, utilityPaymentStatusJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
utilityPaymentStatusDict = {
  "transid":"1218d5Qb"
}
#path relatiive to base url
utilityPaymentStatusPath = "/v1/utilitypayment/query"

#crate new utilityPaymentStatus
response = client.getFunc(utilityPaymentStatusPath, utilityPaymentStatusDict)

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

**Note : Receipt data in response is present only for successful transactions and is dependent availability from thridparty FI

Response Example

{
  "messageId" : "20200721001",
  "reference" : "0289999288",
  "resultcode" : "000",
  "result" : "SUCCESS",
  "message" : "Transaction successful",
  "data": [{"receipt": "12344"}]
}

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

Cashin Request Sample

# With shell, you can just pass the correct header with each request
curl -X POST 'http://example.com/v1/walletcashin/process' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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,utilitycode,utilityref,amount,vendor,pin,msisdn" \
  -d '{
    "transid":"1218d5Qb",
    "utilitycode": "VMCASHIN",
    "utilityref": "0149449499",
    "amount" : 8000,
    "vendor" : "64654949",
    "pin" :  "3545846",
    "msisdn" : "01854595959"
}'
require_once __DIR__ .'/vendor/autoload.php';

// use module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$walletCahinRequestArray = array(
    "transid"=>"1218d5Qb",
    "utilitycode"=> "VMCASHIN",
    "utilityref"=> "0149449499",
    "amount" => 8000,
    "vendor" => "64654949",
    "pin" =>  "3545846",
    "msisdn" => "01854595959"
    );

// path relatiive to base url
$walletCahinRequestPath = "/v1/walletcashin/process";

// cahin request
$response = $client->postFunc($walletCahinRequestPath,$walletCahinRequestArray);
//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String walletCahinRequestPath = "/v1/walletcashin/process";

// data
JsonObject walletCahinRequestDict = new JsonObject();
walletCahinRequestDict.addProperty("transid","1218d5Qb");
walletCahinRequestDict.addProperty("utilitycode", "VMCASHIN");
walletCahinRequestDict.addProperty("utilityref", "654944949");
walletCahinRequestDict.addProperty("amount" , 8000);
walletCahinRequestDict.addProperty("vendor",  "66546846845");
walletCahinRequestDict.addProperty("pin","48585");
walletCahinRequestDict.addProperty("msisdn","255555555555");

//post wallet cashin request
JsonObject response = client.postFunc(walletCahinRequestPath ,walletCahinRequestDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> walletCahinRequestDict = new Dictionary<String,Object>() ;
walletCahinRequestDict.Add("transid","1218d5Qb");
walletCahinRequestDict.Add("utilitycode", "VMCASHIN");
walletCahinRequestDict.Add("utilityref", "654944949");
walletCahinRequestDict.Add("amount" , 8000);
walletCahinRequestDict.Add("vendor",  "66546846845");
walletCahinRequestDict.Add("pin","48585");
walletCahinRequestDict.Add("msisdn","255555555555");

// path relatiive to base url
String walletCahinRequestPath = "/v1/walletcashin/process";

//crate new walletCahinRequest
var walletCahinRequestRespose = client.postFunc(walletCahinRequestPath,walletCahinRequestDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient (baseUrl, apiKey, apiSecret);

//data
var walletCahinRequestJson = {
    "transid":"1218d5Qb",
    "utilitycode": "VMCASHIN",
    "utilityref": "0149449499",
    "amount" : 8000,
    "vendor" : "64654949",
    "pin" :  "3545846",
    "msisdn" : "01854595959"
};
// path relatiive to base url
var walletCahinRequestPath = "/v1/walletcashin/process"

//crate new walletCahinRequest
var = walletCahinRequestRespose = client.postFunc(walletCahinRequestPath, walletCahinRequestJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
walletCahinRequestDict = {
    "transid":"1218d5Qb",
    "utilitycode": "VMCASHIN",
    "utilityref": "0149449499",
    "amount" : 8000,
    "vendor" : "64654949",
    "pin" :  "3545846",
    "msisdn" : "01854595959"
}
#path relatiive to base url
walletCahinRequestPath = "/v1/walletcashin/process"

#crate new walletCahinRequest
response = client.postFunc(walletCahinRequestPath, walletCahinRequestDict)

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 (receiver)
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.(sender)

Wallet Cashin Name Look Up

Wallet Cashin Name Lookup Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/walletcashin/namelookup?utilitycode={uitlitycode}&utilityref={utilityref}&transid={transid}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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: utilitycode,utilityref,transid"
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$walletNameLookUpArray = array(
    "utilitycode"=> "VMCASHIN",
    "utilityref"=> "0149449499",
    "transid"=>"1218d5Qb",
    );

// path relatiive to base url
$walletNameLookUpPath = "/v1/walletcashin/namelookup";

// lookup name
$response = $client->getFunc($walletNameLookUpPath,$walletNameLookUpArray);
//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String walletNameLookUpPath = "/v1/walletcashin/namelookup";

// data
JsonObject walletNameLookUpDict = new JsonObject();
walletNameLookUpDict.addProperty("utilitycode", "VMCASHIN");
walletNameLookUpDict.addProperty("utilityref", "154944949");
walletNameLookUpDict.addProperty("transid","1218d5Qb");

//lookup walllet cashin name
JsonObject response = client.getFunc(walletNameLookUpPath ,walletNameLookUpDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> walletNameLookUpDict = new Dictionary<String,Object>() ;
walletNameLookUpDict.Add("utilitycode", "VMCASHIN");
walletNameLookUpDict.Add("utilityref", "154944949");
walletNameLookUpDict.Add("transid","1218d5Qb");

// path relatiive to base url
String walletNameLookUpPath = "/v1/walletcashin/namelookup";

//crate new walletNameLookUp
var walletNameLookUpRespose = client.getFunc(walletNameLookUpPath,walletNameLookUpDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient (baseUrl, apiKey, apiSecret);

//data
var walletNameLookUpJson = {
    "utilitycode": "VMCASHIN",
    "utilityref": "0149449499",
    "transid":"1218d5Qb",
};
// path relatiive to base url
var walletNameLookUpPath = "/v1/walletcashin/namelookup"

//crate new walletNameLookUp
var = walletNameLookUpRespose = client.getFunc(walletNameLookUpPath,walletNameLookUpJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
walletNameLookUpDict = {
    "utilitycode": "VMCASHIN",
    "utilityref": "0149449499",
    "transid":"1218d5Qb",
}
#path relatiive to base url
walletNameLookUpPath = "/v1/walletcashin/namelookup"

#crate new walletNameLookUp
response = client.getFunc(walletNameLookUpPath, walletNameLookUpDict)

Wallet Cashin Name Lookup Sample response:

{
  "reference":"6927759116",
  "transid":"10001",
  "resultcode":"000",
  "result":"SUCCESS",
  "message":"Name fetch successful",
  "data":[
    {
      "name":"FIROZ MOH"
    }
  ]
}

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.

Query Transaction Status

Query Transaction Status Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/walletcashin/query?transid={transid}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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"
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

# initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$walletCahinTransactionStatusArray = array(
    "transid"=>"1218d5Qb",
    );

// path relatiive to base url
$walletCahinTransactionStatusPath = "/v1/walletcashin/query";

// query transacrion statue
$response = $client->getFunc($walletCahinTransactionStatusPath,$walletCahinTransactionStatusArray);
//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String walletCahinTransactionStatusPath = "/v1/walletcashin/query";

// data
JsonObject walletCahinTransactionStatusDict = new JsonObject();
walletCahinTransactionStatusDict.addProperty("transid","1218d5Qb");

//query transaction status
JsonObject response = client.getFunc(walletCahinTransactionStatusPath ,walletCahinTransactionStatusDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> walletCahinTransactionStatusDict = new Dictionary<String,Object>() ;
walletCahinTransactionStatusDict.Add("transid","1218d5Qb");

// path relatiive to base url
String walletCahinTransactionStatusPath = "/v1/walletcashin/query";

//crate new walletCahinTransactionStatus
var walletCahinTransactionStatusRespose = client.getFunc(walletCahinTransactionStatusPath,walletCahinTransactionStatusDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient (baseUrl, apiKey, apiSecret);

//data
var walletCahinTransactionStatusJson = {
    "transid":"1218d5Qb",
};
// path relatiive to base url
var walletCahinTransactionStatusPath = "/v1/walletcashin/query"

//crate new walletCahinTransactionStatus
var = walletCahinTransactionStatusRespose = client.getFunc(walletCahinTransactionStatusPath, walletCahinTransactionStatusJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
walletCahinTransactionStatusDict = {
    "transid":"1218d5Qb",
}
#path relatiive to base url
walletCahinTransactionStatusPath = "/v1/walletcashin/query"

#crate new walletCahinTransactionStatus
response = client.getFunc(walletCahinTransactionStatusPath, walletCahinTransactionStatusDict)

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

**Note : Receipt data in response is present only for successful transactions and is dependent availability from thridparty FI

Response Example

{
  "messageId" : "20200721001",
  "reference" : "0289999288",
  "resultcode" : "000",
  "result" : "SUCCESS",
  "message" : "Transaction successful",
  "data": [{"receipt": "12344"}]
}

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
HPCASHIN Wallet Mobile No Numeric(10,12) 062XXXXXXX Yes HaloPesa cashin
TTCASHIN Wallet Mobile No Numeric(10,12) 073XXXXXXX Yes TTCLPesa cashin
CASHIN Wallet Mobile No Numeric(10,12) 073XXXXXXX Yes All wallet cashin (selcom will automatically route the traffic based on MNP Lookup)

POS/Agent Cashout

Agent Cashout Process

Agent Cashout Process Sample

# With shell, you can just pass the correct header with each request
curl -X POST 'http://example.com/v1/hudumacashin/process' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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,utilitycode,utilityref,amount,vendor,pin,name" \
  -d '{
      "transid":"1218d5Qb",
    "utilitycode": "HUDUMACI",
    "utilityref": "0149449499",
    "amount" : 8000,
    "vendor" : "64654949",
    "pin" :  "3545846",
    "name" : "John Jon"
}'
require_once __DIR__ .'/vendor/autoload.php';

//use selcom client module 
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$agentCashoutArray = array(
    "transid"=>"1218d5Qb",
    "utilitycode"=> "HUDUMACI",
    "utilityref"=> "0149449499",
    "amount" => 8000,
    "vendor" => "64654949",
    "pin" =>  "3545846",
    "name" => "John Jon"
    );

// path relatiive to base url
$agentCashoutPath = "/v1/hudumacashin/process";

// cashout agent
$response = $client->postFunc($agentCashoutPath,$agentCashoutArray);
//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String agentCashoutPath = "/v1/hudumacashin/process";

// data
JsonObject agentCashoutDict = new JsonObject();
agentCashoutDict.addProperty(  "transid","1218d5Qb");
agentCashoutDict.addProperty("utilitycode","HUDUMACI");
agentCashoutDict.addProperty("utilityref", "654944949");
agentCashoutDict.addProperty("amount" , 8000);
agentCashoutDict.addProperty("vendor",  "66546846845");
agentCashoutDict.addProperty("pin","48585");
agentCashoutDict.addProperty("name" ,"John Jon");

//cashout agent
JsonObject response = client.postFunc(agentCashoutPath ,agentCashoutDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> agentCashoutDict = new Dictionary<String,Object>() ;
agentCashoutDict.Add(  "transid","1218d5Qb");
agentCashoutDict.Add("utilitycode","HUDUMACI");
agentCashoutDict.Add("utilityref", "654944949");
agentCashoutDict.Add("amount" , 8000);
agentCashoutDict.Add("vendor",  "66546846845");
agentCashoutDict.Add("pin","48585");
agentCashoutDict.Add("name" ,"John Jon");

// path relatiive to base url
String agentCashoutPath = "/v1/hudumacashin/process";

//crate new agentCashout
var agentCashoutRespose = client.postFunc(agentCashoutPath, agentCashoutDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var agentCashoutJson = {
    "transid":"1218d5Qb",
    "utilitycode": "HUDUMACI",
    "utilityref": "0149449499",
    "amount" : 8000,
    "vendor" : "64654949",
    "pin" :  "3545846",
    "name" : "John Jon"
};
// path relatiive to base url
var agentCashoutPath = "/v1/hudumacashin/process"

//crate new agentCashout
var = agentCashoutRespose = client.postFunc(agentCashoutPath, agentCashoutJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
agentCashoutDict = {
      "transid":"1218d5Qb",
    "utilitycode": "HUDUMACI",
    "utilityref": "0149449499",
    "amount" : 8000,
    "vendor" : "64654949",
    "pin" :  "3545846",
    "name" : "John Jon"
}
#path relatiive to base url
agentCashoutPath = "/v1/hudumacashin/process"

#crate new agentCashout
response = client.postFunc(agentCashoutPath, agentCashoutDict)

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":[
  ]
}

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

Transaction Status Query

Query Transaction Status Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/hudumacashin/query?transid={transid}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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" 
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$agentTrasactionStatusArray = array("transid"=>"1218d5Qb");

// path relatiive to base url
$agentTrasactionStatusPath = "/v1/hudumacashin/query";

// query transaction status
$response = $client->getFunc($agentTrasactionStatusPath,$agentTrasactionStatusArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String agentTrasactionStatusPath = "/v1/hudumacashin/query";

// data
JsonObject agentTrasactionStatusDict = new JsonObject();
agentTrasactionStatusDict.addProperty(  "transid","1218d5Qb");

//query transaction status
JsonObject response = client.getFunc(agentTrasactionStatusPath ,agentTrasactionStatusDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> agentTrasactionStatusDict = new Dictionary<String,Object>() ;
agentTrasactionStatusDict.Add("transid","1218d5Qb");

// path relatiive to base url
String agentTrasactionStatusPath = "/v1/hudumacashin/query";

//crate new agentTrasactionStatus
var agentTrasactionStatusDictRespose = client.getFunc(agentTrasactionStatusPath,agentTrasactionStatusDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var agentTrasactionStatusJson = {"transid":"1218d5Qb",};
// path relatiive to base url
var agentTrasactionStatusPath = "/v1/hudumacashin/query"

//crate new agentTrasactionStatus
var = agentTrasactionStatusRespose = client.getFunc(agentTrasactionStatusPath, agentTrasactionStatusJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
agentTrasactionStatusDict = {"transid":"1218d5Qb"}
#path relatiive to base url
agentTrasactionStatusPath = "/v1/hudumacashin/query"

#crate new agentTrasactionStatus
response = client.getFunc(agentTrasactionStatusPath, agentTrasactionStatusDict)

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 Float Balance Sample

# With shell, you can just pass the correct header with each request
curl -X POST "http://example.com/v1/vendor/balance" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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,pin,transid"\
  -d '{"vendor":"12186889","pin" : "123456","transid" :"001"}
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$floatAccountBalanceArray = array(
    "vendor"=>"12186889",
    "pin" => "123456",
    "transid"=>"001"
    );

// path relatiive to base url
$floatAccountBalancePath = "/v1/vendor/balance";

// query float account balance
$response = $client->postFunc($floatAccountBalancePath,$floatAccountBalanceArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String floatAccountBalancePath = "/v1/vendor/balance";

// data
JsonObject floatAccountBalanceDict = new JsonObject();
floatAccountBalanceDict.addProperty("vendor","12186889");
floatAccountBalanceDict.addProperty("pin" , "123456");
floatAccountBalanceDict.addProperty("transid" , "001");


//query account balance
JsonObject response = client.postFunc(floatAccountBalancePath ,floatAccountBalanceDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> floatAccountBalanceDict = new Dictionary<String,Object>() ;
floatAccountBalanceDict.Add("vendor","12186889");
floatAccountBalanceDict.Add("pin" , "123456");
floatAccountBalanceDict.Add("transid" , "001");

// path relatiive to base url
String floatAccountBalancePath = "/v1/vendor/balance";

//crate new floatAccountBalance
var floatAccountBalanceRespose = client.getFunc(floatAccountBalancePath, floatAccountBalanceDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var floatAccountBalanceJson = {
    "vendor":"12186889",
    "pin" : "123456",
    "transid":"001"
}
// path relatiive to base url
var floatAccountBalancePath = "/v1/vendor/balance"

//crate new floatAccountBalance
var = floatAccountBalanceRespose = client.getFunc(floatAccountBalancePath, floatAccountBalanceJson)
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
floatAccountBalanceDict = {
    "vendor":"12186889",
    "pin" : "123456",
    "transid":"001"
}
#path relatiive to base url
floatAccountBalancePath = "/v1/vendor/balance"

#crate new floatAccountBalance
response = client.getFunc(floatAccountBalancePath, floatAccountBalanceDict)

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
transid Mandatory A1234 Unique transaction ID

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 C2B

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 Lookup

Payment lookup leg, verify amount, utility reference, phone number etc.

Request Format

POST /lookup 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 AB12345 Payment reference or account number from business who will recieve the funds
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)
amount Amount associated with the reference. If the amount is fixed for the payment requested (Optional)

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 AB12345 Payment reference or account number from business who will recieve the funds
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 AB12345 Payment reference or account number from business who will recieve the funds
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
transid Mandatory XYZ123444 Unique Transaction ID of the transaction
utilityref Mandatory AB12345 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

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":[
  ]
}

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
transid Mandatory XYZ123444 Unique Transaction ID of the transaction 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

Qwiksend

Qwiksend is a Selcom's bank disbursement product for FI and other institutions to send money to a bank.

Bank Transfer

Bank Transfer Sample

# With shell, you can just pass the correct header with each request
curl -X POST 'http://example.com/v1/qwiksend/process' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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,srecipientFiCode,recipientAccount,recipientName,senderAccount,senderName,amount,vendor,pin,msisdn,remarks" \
  -d '{"transid":"1218d5Qb",
    "recipientFiCode": "AKIBA",
    "recipientAccount" : "000000040000",
    "recipientName" : "Jon Jon",
    "senderAccount" :  "3545846654",
    "senderName" : "Jil Jill",
    "amount" : 8000,
    "vendor" :  "3545846",
    "pin" : "09959",
    "msisdn" : "0101855855",
    "remarks" :  "None",
    }'
require_once __DIR__ .'/vendor/autoload.php';

// 
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$bankTransferArray = array(
    "transid"=>"1218d5Qb",
    "recipientFiCode"=> "AKIBA",
    "recipientAccount" => "000000040000",
    "recipientName" => "Jon Jon",
    "senderAccount" =>  "3545846654",
    "senderName" => "Jil Jill",
    "amount" => 8000,
    "vendor" =>  "3545846",
    "pin" => "09959",
    "msisdn" => "0101855855",
    "remarks" =>  "None",
    );

// path relatiive to base url
$bankTransferPath = "/v1/qwiksend/process";

// lookupn utility
$response = $client->postFunc($bankTransferPath,$bankTransferArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String bankTransferPath = "/v1/qwiksend/process";

// data
JsonObject bankTransferDict = new JsonObject();
bankTransferDict.addProperty("transid","1218d5Qb");
bankTransferDict.addProperty("recipientFiCode", "AKIBA");
bankTransferDict.addProperty("recipientAccount" , "000000040000");
bankTransferDict.addProperty("senderAccount" ,  "3545846654");
bankTransferDict.addProperty("senderName" , "Jil Jill");
bankTransferDict.addProperty("amount" , 8000);
bankTransferDict.addProperty("vendor" ,  "3545846");
bankTransferDict.addProperty("pin" , "09959");
bankTransferDict.addProperty("msisdn" , "0101855855");
bankTransferDict.addProperty("remarks" ,  "None");


//post bank transfer
JsonObject response = client.postFunc(bankTransferPath ,bankTransferDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> bankTransferDict = new Dictionary<String,Object>() ;
bankTransferDict.Add("transid","1218d5Qb");
bankTransferDict.Add("recipientFiCode", "AKIBA");
bankTransferDict.Add("recipientAccount" , "000000040000");
bankTransferDict.Add("senderAccount" ,  "3545846654");
bankTransferDict.Add("senderName" , "Jil Jill");
bankTransferDict.Add("amount" , 8000);
bankTransferDict.Add("vendor" ,  "3545846");
bankTransferDict.Add("pin" , "09959");
bankTransferDict.Add("msisdn" , "0101855855");
bankTransferDict.Add("remarks" ,  "None");

// path relatiive to base url
String bankTransferPath = "/v1/qwiksend/process";

//crate new bankTransfer
var bankTransferRespose = client.postFunc(bankTransferDictPath, bankTransferDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var bankTransferJson = {
            "transid":"1218d5Qb",
    "recipientFiCode": "AKIBA",
    "recipientAccount" : "000000040000",
    "recipientName" : "Jon Jon",
    "senderAccount" :  "3545846654",
    "senderName" : "Jil Jill",
    "amount" : 8000,
    "vendor" :  "3545846",
    "pin" : "09959",
    "msisdn" : "0101855855",
    "purpose": "GIFT",
    "remarks" :  "None",
};
// path relatiive to base url
var bankTransferPath = "/v1/qwiksend/process"

//crate new bankTransfer
var = bankTransferRespose = client.postFunc(bankTransferPath, bankTransferJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
bankTransferDict = {
        "transid":"1218d5Qb",
    "recipientFiCode": "AKIBA",
    "recipientAccount" : "000000040000",
    "recipientName" : "Jon Jon",
    "senderAccount" :  "3545846654",
    "senderName" : "Jil Jill",
    "amount" : 8000,
    "vendor" :  "3545846",
    "pin" : "09959",
    "msisdn" : "0101855855",
    "purpose": "GIFT",
    "remarks" :  "None",
}
#path relatiive to base url
bankTransferPath = "/v1/qwiksend/process"

#crate new bankTransfer
response = client.postFunc(bankTransferPath, bankTransferDict)

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
recipientFiCode Mandatory AKIBA Destination bank shortocde. Refer to List of Bank Short Names section
recipientAccount Mandatory 1234567890 Destination account number
recipientName Mandatory ROBERT MUSHI Source account holder name
senderAccount Mandatory 01234567891 Source account number or Unique identifier of the sender on the source platform
senderName 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 Sender mobile number
purpose Mandatory GIFT Purpose of the transfer
remarks Optional Salary Purpose of the payment or payment description

Account Name Lookup

Account Name Lookup SAmple

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/qwiksend/lookup/?bank={bank}&account={account}&transid={transid}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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: bank,account,transid" 
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values o=>f the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$accountNameLookupArray = array(
    "bank"=> "AKIBA",
    "account" => "000000040000",
    "transid"=>"1218d5Qb",
    );

// path relatiive to base url
$accountNameLookupPath = "/v1/qwiksend/lookup/";

// lookup account name
$response = $client->getFunc($accountNameLookupPath,$accountNameLookupArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String accountNameLookupPath = "/v1/qwiksend/lookup/";

// data
JsonObject accountNameLookupDict = new JsonObject();
accountNameLookupDict.addProperty("bank", "AKIBA");
accountNameLookupDict.addProperty("account" , "000000040000");
accountNameLookupDict.addProperty("transid","1218d5Qb");

//lookup account name
JsonObject response = client.getFunc(accountNameLookupPath ,accountNameLookupDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> accountNameLookupDict = new Dictionary<String,Object>() ;
accountNameLookupDict.Add("bank", "AKIBA");
accountNameLookupDict.Add("account" , "000000040000");
accountNameLookupDict.Add("transid","1218d5Qb");

// path relatiive to base url
String accountNameLookupDictPath = "/v1/qwiksend/lookup";

//crate new accountNameLookup
var accountNameLookupRespose = client.getFunc(accountNameLookupPath,accountNameLookupDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var accountNameLookupJson = {
    "bank": "AKIBA",
    "account" : "000000040000",
    "transid":"1218d5Qb",
};
// path relatiive to base url
var accountNameLookupPath = "/v1/qwiksend/lookup"

//crate new accountNameLookup
var = accountNameLookupRespose = client.getFunc(accountNameLookupPath, accountNameLookupJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
accountNameLookupDict = {
    "bank": "AKIBA",
    "account" : "000000040000",
    "transid":"1218d5Qb",
}
#path relatiive to base url
accountNameLookupPath = "/v1/qwiksend/lookup"

#crate new accountNameLookup
response = client.getFunc(accountNameLookupPath, accountNameLookupDict)

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 Qwiksend

Query Transaction Status Qwiksend Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/qwiksend/query?transid={transid}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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" 
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values o=>f the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$trasactionStatusArray = array("transid"=>"1218d5Qb");

// path relatiive to base url
$trasactionStatusPath = "/v1/qwiksend/query";

// query transaction status
$response = $client->getFunc($trasactionStatusPath,$trasactionStatusArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String trasactionStatusPath = "/v1/qwiksend/query";

// data
JsonObject trasactionStatusDict = new JsonObject();
trasactionStatusDict.addProperty("transid","1218d5Qb");

//query transaction status
JsonObject response = client.getFunc(trasactionStatusPath ,trasactionStatusDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> trasactionStatusDict = new Dictionary<String,Object>() ;
trasactionStatusDict.Add("transid","1218d5Qb");

// path relatiive to base url
String trasactionStatusPath = "/v1/qwiksend/query";

//crate new trasactionStatus
var trasactionStatusRespose = client.getFunc(trasactionStatusPath,trasactionStatusDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var trasactionStatusJson = {"transid":"1218d5Qb",};
// path relatiive to base url
var trasactionStatusPath = "/v1/qwiksend/query"

//crate new trasactionStatus
var = trasactionStatusRespose = client.getFunc(trasactionStatusPath, trasactionStatusJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
trasactionStatusDict = {"transid":"1218d5Qb"}
#path relatiive to base url
trasactionStatusPath = "/v1/qwiksend/query"

#crate new trasactionStatus
response = client.getFunc(trasactionStatusPath, trasactionStatusDict)

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 Available Bank Name
SELCOMMFB Yes SELCOM MICROFINANCE BANK
BOBTZ Yes BOB TANZANIA
CANARABANK Yes CANARA TANZANIA
NCBA Yes NCBA TANZANIA
ECOBANK Yes ECOBANK TANZANIA
CRDBBANK Yes CRDBBANK
LETSHEGO Yes LETSHEGO BANK TANZANIA
AKIBA Yes AKIBA COMMERCIAL BANK TANZANIA
AMANABANK Yes AMANA BANK TANZANIA
BANCABC Yes BANCABC TANZANIA
BOA Yes BANK OF AFRICA TANZANIA
BANKOFBARODA Yes BANK OF BARODA TANZANIA
ABSA Yes ABSA BANK TANZANIA
EQUITYBANK Yes EQUITY BANK TANZANIA
EXIMBANK Yes EXIM BANK TANZANIA
IMBANK Yes I AND M BANK TANZANIA
KCB Yes KENYA COMMERCIAL BANK LTD
MAENDELEO Yes MAENDELEO BANK
MKOMBOZI Yes MKOMBOZI COMMERCIAL BANK
NBC Yes NATIONAL BANK OF COMMERCE
NMB Yes NATIONAL MICROFINANCE BANK
STANBIC Yes STANBIC BANK TANZANIA
STANDARDCHARTERED Yes STANDARD CHARTERED BANK
TCB Yes TANZANIA COMMERCIAL BANK
UBA Yes UNITED BANK FOR AFRICA
AZANIA Yes AZANIA TANZANIA
BANKOFINDIA Yes BANK OF INDIA TANZANIA
DTBBANK Yes DIAMOND TRUST BANK
DCBBANK Yes DCB COMMERCIAL BANK
FINCA Yes FINCA MICROFINANCE BANK
GTBANK Yes GT BANK TANZANIA
HABIBBANK Yes HABIB BANK
ICB Yes ICB BANK
KILIMANJARO Yes KILIMANJARO COMMERCIAL BANK
MWALIMU Yes MWALIMU COMMERCIAL BANK OF TANZANIA
MWANGA Yes MWANGA HAKIKA MICROFINANCE BANK
PBZ Yes PEOPLES BANK OF ZANZIBAR
CHINADASHENG Yes CHINA DASHENG BANK LTD
CITIBANK Yes CITIBANK TANZANIA LIMITED

VCN

Create VCN

Create VCN Sample

# With shell, you can just pass the correct header with each request
curl -X POST 'http://example.com/v1/vcn/create' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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"}
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module 
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";


$client = new Client($baseUrl, $apiKey, $apiSecret);


// data
$createVCNArray = array(
    "msisdn"=>"2550123456789",
    "account"=> "012265494",
    "first_name" => "Jon",
    "last_name" => "John",
    "middle_name" =>  "Jhn",
    "gender" => "MALE",
    "dob" => "01011900",
    "address" =>  "Street Area",
    "city" => "Dar es Salaam",
    "region" => "Dar es Salaam",
    "nationality" =>  "TAnzanian",
    "validity"=>"12",
    "email"=> "jon@john.com",
    "language" => "sw",
    "marital_status" => "MARRIED",
    "maiden_name" =>  "",
    "senderName" => "Jil Jill",
    "vendor" =>  "3545846",
    "pin" => "09959",
    "transid" => "XYZ123444",
    "product_code" =>  "AAVCN001",
    );

// path relatiive to base url
$createVCNPath = "/v1/vcn/create";

// create vcn
$response = $client->postFunc($createVCNPath,$createVCNArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String createVCNPath = "/v1/vcn/create";

// data
JsonObject createVCNDict = new JsonObject();
createVCNDict.addProperty("msisdn","2550123456789");
createVCNDict.addProperty("account", "012265494");
createVCNDict.addProperty("first_name" , "Jon");
createVCNDict.addProperty("last_name" , "John");
createVCNDict.addProperty("middle_name" ,  "Jhn");
createVCNDict.addProperty("gender" , "MALE");
createVCNDict.addProperty("dob" , "01011900");
createVCNDict.addProperty("address" ,  "Street Area");
createVCNDict.addProperty("city" , "Dar es Salaam");
createVCNDict.addProperty("region" , "Dar es Salaam");
createVCNDict.addProperty("nationality" ,  "Tanzanian");
createVCNDict.addProperty("validity","12");
createVCNDict.addProperty("email", "jon@john.com");
createVCNDict.addProperty("language" , "sw");
createVCNDict.addProperty("maiden_name" ,  "");
createVCNDict.addProperty("senderName" , "Jil Jill");
createVCNDict.addProperty("vendor" , "XYZABC");
createVCNDict.addProperty("pin" , "09959");
createVCNDict.addProperty("transid" , "XYZ123444");
createVCNDict.addProperty("product_code" ,  "AAVCN001");

//post bcreate vcn
JsonObject response = client.postFunc(createVCNPath ,createVCNDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> createVCNDict = new Dictionary<String,Object>() ;
createVCNDict.Add("msisdn","2550123456789");
createVCNDict.Add("account", "012265494");
createVCNDict.Add("first_name" , "Jon");
createVCNDict.Add("last_name" , "John");
createVCNDict.Add("middle_name" ,  "Jhn");
createVCNDict.Add("gender" , "MALE");
createVCNDict.Add("dob" , "01011900");
createVCNDict.Add("address" ,  "Street Area");
createVCNDict.Add("city" , "Dar es Salaam");
createVCNDict.Add("region" , "Dar es Salaam");
createVCNDict.Add("nationality" ,  "Tanzanian");
createVCNDict.Add("validity","12");
createVCNDict.Add("email", "jon@john.com");
createVCNDict.Add("language" , "sw");
createVCNDict.Add("maiden_name" ,  "");
createVCNDict.Add("senderName" , "Jil Jill");
createVCNDict.Add("vendor" , "XYZABC");
createVCNDict.Add("pin" , "09959");
createVCNDict.Add("transid" , "XYZ123444");
createVCNDict.Add("product_code" ,  "AAVCN001");

// path relatiive to base url
String createVCNPath = "/v1/vcn/create";

//crate new createVCN
var createVCNRespose = client.postFunc(createVCNPath,createVCNDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var createVCNJson = {
    "msisdn":"2550123456789",
    "account": "012265494",
    "first_name" : "Jon",
    "last_name" : "John",
    "middle_name" :  "Jhn",
    "gender" : "MALE",
    "dob" : "01011900",
    "address" :  "Street Area",
    "city" : "Dar es Salaam",
    "region" : "Dar es Salaam",
    "nationality" :  "TAnzanian",
    "validity":"12",
    "email": "jon@john.com",
    "language" : "sw",
    "marital_status" : "MARRIED",
    "maiden_name" :  "",
    "senderName" : "Jil Jill",
    "vendor" :  "3545846",
    "pin" : "09959",
    "transid" : "XYZ123444",
    "product_code" :  "AAVCN001",
};
// path relatiive to base url
var createVCNPath = "/v1/vcn/create"

//crate new createVCN
var = createVCNRespose = client.postFunc(createVCNPath, createVCNJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
createVCNDict = {
    "msisdn":"2550123456789",
    "account": "012265494",
    "first_name" : "Jon",
    "last_name" : "John",
    "middle_name" :  "Jhn",
    "gender" : "MALE",
    "dob" : "01011900",
    "address" :  "Street Area",
    "city" : "Dar es Salaam",
    "region" : "Dar es Salaam",
    "nationality" :  "TAnzanian",
    "validity":"12",
    "email": "jon@john.com",
    "language" : "sw",
    "marital_status" : "MARRIED",
    "maiden_name" :  "",
    "senderName" : "Jil Jill",
    "vendor" :  "3545846",
    "pin" : "09959",
    "transid" : "XYZ123444",
    "product_code" :  "AAVCN001",
}
#path relatiive to base url
createVCNPath = "/v1/vcn/create"

#crate new createVCN
response = client.postFunc(createVCNPath, createVCNDict)

HTTP Request

POST http://example.com/v1/vcn/create

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",
    "card_url": "dfnldafalnfalnalfnaln"
  }
}

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

Create VCN Status Enquiry

Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/vcn/create-status-enquiry?msisdn={msisdn}&transid={transid}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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,transid"
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$vcnCreateCardStatusArray = array(
    "msisdn"=>"2550123456789",
    "transid"=> "012265494",
    );

// path relatiive to base url
$vcnCreateCardStatusPath = "/v1/vcn/create-status-enquiry";

// get card status
$response = $client->getFunc($vcnCreateCardStatusPath,$vcnCreateCardStatusArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String vcnCreateCardStatusPath = "/v1/vcn/create-status-enquiry";

// data
JsonObject vcnCreateCardStatusDict = new JsonObject();
vcnCreateCardStatusDict.addProperty("msisdn"=>"2550123456789");
vcnCreateCardStatusDict.addProperty("transid"=> "012265494");

//query card status
JsonObject response = client.getFunc(vcnCreateCardStatusPath ,vcnCreateCardStatusDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> vcnCreateCardStatusDict = new Dictionary<String,Object>() ;
vcnCreateCardStatusDict.Add("msisdn"=>"2550123456789");
vcnCreateCardStatusDict.Add("transid"=> "012265494");

// path relatiive to base url
String vcnCreateCardStatusPath = "/v1/vcn/create-status-enquiry";

//crate new vcnCreateCardStatusDict
var vcnCreateCardStatusDictRespose = client.getFunc(vcnCreateCardStatusPath,vcnCreateCardStatusDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var vcnCreateCardStatusJson = {
    "msisdn":"2550123456789",
    "transid": "012265494",
};
// path relatiive to base url
var vcnCreateCardStatusPath = "/v1/vcn/create-status-enquiry"

//crate new vcnCreateCardStatus
var = vcnCreateCardStatusRespose = client.getFunc(vcnCreateCardStatusPath, vcnCreateCardStatusJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
vcnCreateCardStatusDict = {
    "msisdn":"2550123456789",
    "transid": "012265494",
}
#path relatiive to base url
vcnCreateCardStatusPath = "/v1/vcn/create-status-enquiry"

#crate new vcnCreateCardStatus
response = client.getFunc(vcnCreateCardStatusPath, vcnCreateCardStatusDict)

The API is used to get the VCN card creation status. No sms will be triggered to end customer on using this API

HTTP Request

GET http://example.com/v1/vcn/create-status-enquiry?msisdn=25577XXXXXXXX&transid=T1000932222


{
  "reference" : "0289999288",
  "resultcode" : "000",
  "result" : "SUCCESS",
  "message" : "VCN creation success",
  "data": {
    "card_id": "0000021111",
    "masked_card": "533322******0320",
    "card_url": "dfnldafalnfalnalfnaln"
  }
}

JSON Payload Parameters

Parameter Type Example Description
transid Mandatory A1234 Unique transaction ID
msisdn Mandatory 255781234567 Customer mobile number using during VCN registration in international format(must be a valid TZ mobile number)

Block/Unblock/Suspend Card (Change Status)

Block/Unblock/Suspend Card (Change Status) 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"}
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

//initalize a new Client  instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$vcnChangeStatusArray = array(
    "msisdn"=>"2550123456789",
    "account"=> "012265494",
    "status" => "BLOCK",
    "remarks" => "None",
    "card_id" =>  "0111222255",
    "requestid" => "XYZ123444",
    "language" => " SW",
    );

// path relatiive to base url
$vcnChangeStatusPath = "/v1/vcn/changestatus";

// change vcn status
$response = $client->postFunc($vcnChangeStatusPath,$vcnChangeStatusArray);
//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String vcnChangeStatusPath = "/v1/vcn/changestatus";

// data
JsonObject vcnChangeStatusDict = new JsonObject();
vcnChangeStatusDict.addProperty("msisdn","2550123456789");
vcnChangeStatusDict.addProperty("account", "012265494");
vcnChangeStatusDict.addProperty("status" , "BLOCK");
vcnChangeStatusDict.addProperty("remarks" , "None");
vcnChangeStatusDict.addProperty("card_id" ,  "0111222255");
vcnChangeStatusDict.addProperty("requestid" , "XYZ123444");
vcnChangeStatusDict.addProperty("language" , "  SW");

//post change card status
JsonObject response = client.postFunc(vcnChangeStatusPath ,vcnChangeStatusDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> vcnChangeStatusDict = new Dictionary<String,Object>() ;
vcnChangeStatusDict.Add("msisdn","2550123456789");
vcnChangeStatusDict.Add("account", "012265494");
vcnChangeStatusDict.Add("status" , "BLOCK");
vcnChangeStatusDict.Add("remarks" , "None");
vcnChangeStatusDict.Add("card_id" ,  "0111222255");
vcnChangeStatusDict.Add("requestid" , "XYZ123444");
vcnChangeStatusDict.Add("language" , "  SW");

// path relatiive to base url
String vcnChangeStatusPath = "/v1/vcn/changestatus";

//crate new vcnChangeStatus
var vcnChangeStatusRespose = client.getFunc(vcnChangeStatusPath,vcnChangeStatusDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient (baseUrl, apiKey, apiSecret);

//data
var vcnChangeStatusJson = {
    "msisdn":"2550123456789",
    "account": "012265494",
    "status" : "BLOCK",
    "remarks" : "None",
    "card_id" :  "0111222255",
    "requestid" : "XYZ123444",
    "language" : "  SW",
};
// path relatiive to base url
var vcnChangeStatusPath = "/v1/vcn/changestatus"

//crate new vcnChangeStatus
var = vcnChangeStatusRespose = client.getFunc(vcnChangeStatusPath, vcnChangeStatusJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
vcnChangeStatusDict = {
    "msisdn":"2550123456789",
    "account": "012265494",
    "status" : "BLOCK",
    "remarks" : "None",
    "card_id" :  "0111222255",
    "requestid" : "XYZ123444",
    "language" : "  SW",
}
#path relatiive to base url
vcnChangeStatusPath = "/v1/vcn/changestatus"

#crate new vcnChangeStatus
response = client.getFunc(vcnChangeStatusPath, vcnChangeStatusDict)

HTTP Request

POST http://example.com/v1/vcn/changestatus

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

Show Card Sample

# With shell, you can just pass the correct header with each request
curl -X POST 'http://example.com/v1/vcn/show' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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"}''
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$vcnshowCardArray = array(
    "msisdn"=>"2550123456789",
    "account"=> "012265494",
    "card_id" =>  "0111222255",
    "requestid" => "XYZ123444",
    "language" => " SW",
    );

// path relatiive to base url
$vcnshowCardPath = "/v1/vcn/show";

// change show card
$response = $client->postFunc($vcnshowCardPath,$vcnshowCardArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String vcnshowCardPath = "/v1/vcn/show";

// data
JsonObject vcnshowCardDict = new JsonObject();
vcnshowCardDict.addProperty("msisdn","2550123456789");
vcnshowCardDict.addProperty("account", "012265494");
vcnshowCardDict.addProperty("card_id" ,  "0111222255");
vcnshowCardDict.addProperty("requestid" , "XYZ123444");
vcnshowCardDict.addProperty("language" , "  SW");

//post show card 
JsonObject response = client.postFunc(vcnshowCardPath ,vcnshowCardDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> vcnshowCardDict = new Dictionary<String,Object>() ;
vcnshowCardDict.Add("msisdn","2550123456789");
vcnshowCardDict.Add("account", "012265494");
vcnshowCardDict.Add("card_id" ,  "0111222255");
vcnshowCardDict.Add("requestid" , "XYZ123444");
vcnshowCardDict.Add("language" , "  SW");

// path relatiive to base url
String vcnshowCardPath = "/v1/vcn/show";

//crate new vcnshowCard
var vcnshowCardRespose = client.postFunc(vcnshowCardPath,vcnshowCardDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient (baseUrl, apiKey, apiSecret);

//data
var vcnshowCardJson = {
    "msisdn":"2550123456789",
    "msisdn":"2550123456789",
    "account": "012265494",
    "card_id" :  "0111222255",
    "requestid" : "XYZ123444",
    "language" : "  SW",
};
// path relatiive to base url
var vcnshowCardPath = "/v1/vcn/show"

//crate new vcnshowCard
var = vcnshowCardRespose = client.postFunc(vcnshowCardPath, vcnshowCardJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
vcnshowCardDict = {
    "msisdn":"2550123456789",
    "msisdn":"2550123456789",
    "account": "012265494",
    "card_id" :  "0111222255",
    "requestid" : "XYZ123444",
    "language" : "  SW",
}
#path relatiive to base url
vcnshowCardPath = "/v1/vcn/show"

#crate new vcnshowCard
response = client.postFunc(vcnshowCardPath, vcnshowCardDict)

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

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

Get Card Status Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/vcn/status?msisdn={msisdn}&account={account}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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"
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$vcnCardStatusArray = array(
    "msisdn"=>"2550123456789",
    "account"=> "012265494",
    );

// path relatiive to base url
$vcnCardStatusPath = "/v1/vcn/status";

// get card status
$response = $client->getFunc($vcnCardStatusPath,$vcnCardStatusArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String vcnCardStatusPath = "/v1/vcn/status";

// data
JsonObject vcnCardStatusDict = new JsonObject();
vcnCardStatusDict.addProperty("msisdn"=>"2550123456789");
vcnCardStatusDict.addProperty("account"=> "012265494");

//query card status
JsonObject response = client.getFunc(vcnCardStatusPath ,vcnCardStatusDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> vcnCardStatusDict = new Dictionary<String,Object>() ;
vcnCardStatusDict.Add("msisdn"=>"2550123456789");
vcnCardStatusDict.Add("account"=> "012265494");

// path relatiive to base url
String vcnCardStatusPath = "/v1/vcn/status";

//crate new vcnCardStatusDict
var vcnCardStatusDictRespose = client.getFunc(vcnCardStatusPath,vcnCardStatusDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var vcnCardStatusJson = {
    "msisdn":"2550123456789",
    "account": "012265494",
};
// path relatiive to base url
var vcnCardStatusPath = "/v1/vcn/status"

//crate new vcnCardStatus
var = vcnCardStatusRespose = client.getFunc(vcnCardStatusPath, vcnCardStatusJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
vcnCardStatusDict = {
    "msisdn":"2550123456789",
    "account": "012265494",
}
#path relatiive to base url
vcnCardStatusPath = "/v1/vcn/status"

#crate new vcnCardStatus
response = client.getFunc(vcnCardStatusPath, vcnCardStatusDict)

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


{
  "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 Sample

# With shell, you can just pass the correct header with each request
curl -X POST 'http://example.com/v1/vcn/set-limit' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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"}
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$vcnSetLimitArray = array(
    "msisdn"=>"2550123456789",
    "account"=> "012265494",
    "limit_amount" => 10000,
    "limit_type" => "MONTHLY",
    "card_id" =>  "0111222255"
    );

// path relatiive to base url
$vcnSetLimitPath = "/v1/vcn/set-limit";

// set transaction limit
$response = $client->postFunc($vcnSetLimitPath,$vcnSetLimitArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String vcnSetLimitPath = "/v1/vcn/set-limit";

// data
JsonObject vcnSetLimitDict = new JsonObject();
vcnSetLimitDict.addProperty("msisdn","2550123456789");
vcnSetLimitDict.addProperty("account", "012265494");
vcnSetLimitDict.addProperty("limit_amount" , 10000);
vcnSetLimitDict.addProperty("limit_type" , "MONTHLY");
vcnSetLimitDict.addProperty("card_id" , "0111222255");

//post set card limit
JsonObject response = client.postFunc(vcnSetLimitPath ,vcnSetLimitDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> vcnSetLimitDict = new Dictionary<String,Object>() ;
vcnSetLimitDict.Add("msisdn","2550123456789");
vcnSetLimitDict.Add("account", "012265494");
vcnSetLimitDict.Add("limit_amount" , 10000);
vcnSetLimitDict.Add("limit_type" , "MONTHLY");
vcnSetLimitDict.Add("card_id" , "0111222255");

// path relatiive to base url
String vcnSetLimitPath = "/v1/vcn/set-limit";

//crate new vcnSetLimit
var vcnSetLimitRespose = client.postFunc(vcnSetLimitPath,vcnSetLimitDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient (baseUrl, apiKey, apiSecret);

//data
var vcnSetLimitJson = {
  "msisdn":"2550123456789",
    "account": "012265494",
    "limit_amount" : 10000,
    "limit_type" : "MONTHLY",
    "card_id" :  "0111222255"
};
// path relatiive to base url
var vcnSetLimitPath = "/v1/vcn/set-limit"

//crate new vcnSetLimit
var = vcnSetLimitRespose = client.postFunc(vcnSetLimitPath, vcnSetLimitJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
vcnSetLimitDict = {
  "msisdn":"2550123456789",
    "account": "012265494",
    "limit_amount" : 10000,
    "limit_type" : "MONTHLY",
    "card_id" :  "0111222255"
}
#path relatiive to base url
vcnSetLimitPath = "/v1/vcn/set-limit"

#crate new vcnSetLimit
response = client.postFunc(vcnSetLimitPath, vcnSetLimitDict)

Set transaction limit for ecommerce transactions for the VCN

HTTP Request

POST http://example.com/v1/vcn/set-limit

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 Order Sample

# With shell, you can just pass the correct header with each request
curl -X POST 'http://example.com/v1/checkout/create-order' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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,no_of_items_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" : "255082852526"
  },
  "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" : "255082852526"
  },
  "buyer_remarks":"None",
  "merchant_remarks":"None",
  "no_of_items":  3

}'
require_once __DIR__ .'/vendor/autoload.php';

// use selcom  client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$orderArray = array(
    "vendor"=>"VENDORTILL",
    "order_id"=>"85gh9p7l8",
    "buyer_email"=> "john@example.com",
    "buyer_name"=> "John Joh",
    "buyer_userid"=> "",
    "buyer_phone"=> "255xxxxxxxxx",
    "gateway_buyer_uuid"=> "",
    "amount"=>  8000,
    "currency"=>"TZS",
    "payment_methods"=>"ALL",
    "redirect_url"=>"aHR0cHM6Ly9leGFtcGxlLmNvbS8=",
    "cancel_url"=>"aHR0cHM6Ly9leGFtcGxlLmNvbS8=",
    "webhook"=>"aHR0cHM6Ly9leGFtcGxlLmNvbS8=",
    "billing.firstname" => "John",
    "billing.lastname" => "Doe",
    "billing.address_1" => "969 Market",
    "billing.address_2" => "",
    "billing.city" => "San Francisco",
    "billing.state_or_region" => "CA",
    "billing.postcode_or_pobox" => "94103",
    "billing.country" => "US",
    "billing.phone" => "255xxxxxxxxx",
    "shipping.firstname" => "John",
    "shipping.lastname" => "Doe",
    "shipping.address_1" => "969 Market",
    "shipping.address_2" => "",
    "shipping.city" => "San Francisco",
    "shipping.state_or_region" => "CA",
    "shipping.postcode_or_pobox" => "94103",
    "shipping.country" => "US",
    "shipping.phone" => "255xxxxxxxxx",
    "buyer_remarks"=>"None",
    "merchant_remarks"=>"None",
    "no_of_items"=>  3
    );

// path relatiive to base url
$orderPath = "/v1/checkout/create-order";

// create order
$response = $client->postFunc($orderPath,$orderArray);
//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";



// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String orderPath = "/v1/checkout/create-order";

// data
JsonObject orderDict = new JsonObject();
orderDict.addProperty("vendor","VENDORTILL");
orderDict.addProperty("order_id","1218d00Y");
orderDict.addProperty("buyer_email", "john@example.com");
orderDict.addProperty("buyer_name", "John Joh");
orderDict.addProperty("buyer_userid", "");
orderDict.addProperty("buyer_phone", "255xxxxxxxxxx");
orderDict.addProperty("gateway_buyer_uuid", "");
orderDict.addProperty("amount",  8000);
orderDict.addProperty("currency","TZS");
orderDict.addProperty("payment_methods","ALL");
orderDict.addProperty("redirect_url","aHR0cHM6Ly9leGFtcGxlLmNvbS8=");
orderDict.addProperty("cancel_url","aHR0cHM6Ly9leGFtcGxlLmNvbS8=");
orderDict.addProperty("webhook","aHR0cHM6Ly9leGFtcGxlLmNvbS8=");
orderDict.addProperty("billing.firstname" , "John");
orderDict.addProperty("billing.lastname" , "Doe");
orderDict.addProperty("billing.address_1" , "969 Market");
orderDict.addProperty("billing.address_2" , "");
orderDict.addProperty("billing.city" , "San Francisco");
orderDict.addProperty("billing.state_or_region" , "CA");
orderDict.addProperty("billing.postcode_or_pobox" , "94103");
orderDict.addProperty("billing.country" , "US");
orderDict.addProperty("billing.phone" , "255xxxxxxxxx");
orderDict.addProperty("shipping.firstname" , "John");
orderDict.addProperty("shipping.lastname" , "Doe");
orderDict.addProperty("shipping.address_1" , "969 Market");
orderDict.addProperty("shipping.address_2" , "");
orderDict.addProperty("shipping.city" , "San Francisco");
orderDict.addProperty("shipping.state_or_region" , "CA");
orderDict.addProperty("shipping.postcode_or_pobox" , "94103");
orderDict.addProperty("shipping.country" , "US");
orderDict.addProperty("shipping.phone" , "255xxxxxxxxx");
orderDict.addProperty("buyer_remarks","None");
orderDict.addProperty("merchant_remarks","None");
orderDict.addProperty("no_of_items",  3);


//post data
JsonObject response = client.postFunc(orderPath ,orderDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> orderDict = new Dictionary<String,Object>() ;
orderDict.Add("vendor","VENDORTILL");
orderDict.Add("order_id","1218d00Y");
orderDict.Add("buyer_email", "john@example.com");
orderDict.Add("buyer_name", "John Joh");
orderDict.Add("buyer_userid", "");
orderDict.Add("buyer_phone", "255xxxxxxxxxx");
orderDict.Add("gateway_buyer_uuid", "");
orderDict.Add("amount",  8000);
orderDict.Add("currency","TZS");
orderDict.Add("payment_methods","ALL");
orderDict.Add("redirect_url","aHR0cHM6Ly9leGFtcGxlLmNvbS8=");
orderDict.Add("cancel_url","aHR0cHM6Ly9leGFtcGxlLmNvbS8=");
orderDict.Add("webhook","aHR0cHM6Ly9leGFtcGxlLmNvbS8=");
orderDict.Add("billing.firstname" , "John");
orderDict.Add("billing.lastname" , "Doe");
orderDict.Add("billing.address_1" , "969 Market");
orderDict.Add("billing.address_2" , "");
orderDict.Add("billing.city" , "San Francisco");
orderDict.Add("billing.state_or_region" , "CA");
orderDict.Add("billing.postcode_or_pobox" , "94103");
orderDict.Add("billing.country" , "US");
orderDict.Add("billing.phone" , "255xxxxxxxxx");
orderDict.Add("shipping.firstname" , "John");
orderDict.Add("shipping.lastname" , "Doe");
orderDict.Add("shipping.address_1" , "969 Market");
orderDict.Add("shipping.address_2" , "");
orderDict.Add("shipping.city" , "San Francisco");
orderDict.Add("shipping.state_or_region" , "CA");
orderDict.Add("shipping.postcode_or_pobox" , "94103");
orderDict.Add("shipping.country" , "US");
orderDict.Add("shipping.phone" , "255xxxxxxxxx");
orderDict.Add("buyer_remarks","None");
orderDict.Add("merchant_remarks","None");
orderDict.Add("no_of_items",  3);

// path relatiive to base url
String orderPath = "/v1/checkout/create-order";

//crate new order
var orderRespose = client.postFunc(orderPath, orderDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var orderJson = {
    "vendor":"VENDORTILL",
    "order_id":"85gh9p7l8",
    "buyer_email": "john@example.com",
    "buyer_name": "John Joh",
    "buyer_userid": "",
    "buyer_phone": "255xxxxxxxxx",
    "gateway_buyer_uuid": "",
    "amount":  8000,
    "currency":"TZS",
    "payment_methods":"ALL",
    "redirect_url":"aHR0cHM6Ly9leGFtcGxlLmNvbS8=",
    "cancel_url":"aHR0cHM6Ly9leGFtcGxlLmNvbS8=",
    "webhook":"aHR0cHM6Ly9leGFtcGxlLmNvbS8=",
    "billing.firstname" : "John",
    "billing.lastname" : "Doe",
    "billing.address_1" : "969 Market",
    "billing.address_2" : "",
    "billing.city" : "San Francisco",
    "billing.state_or_region" : "CA",
    "billing.postcode_or_pobox" : "94103",
    "billing.country" : "US",
    "billing.phone" : "255xxxxxxxxx",
    "shipping.firstname" : "John",
    "shipping.lastname" : "Doe",
    "shipping.address_1" : "969 Market",
    "shipping.address_2" : "",
    "shipping.city" : "San Francisco",
    "shipping.state_or_region" : "CA",
    "shipping.postcode_or_pobox" : "94103",
    "shipping.country" : "US",
    "shipping.phone" : "255xxxxxxxxx",
    "buyer_remarks":"None",
    "merchant_remarks":"None",
    "no_of_items":  3
  }
// path relatiive to base url
var orderPath = "/v1/checkout/create-order"

//crate new order
var = orderRespose = client.postFunc(orderPath, orderJson)
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
orderDict = {
"vendor":"VENDORTILL",
    "order_id":"85gh9p7l8",
    "buyer_email": "john@example.com",
    "buyer_name": "John Joh",
    "buyer_userid": "",
    "buyer_phone": "255xxxxxxxxx",
    "gateway_buyer_uuid": "",
    "amount":  8000,
    "currency":"TZS",
    "payment_methods":"ALL",
    "redirect_url":"aHR0cHM6Ly9leGFtcGxlLmNvbS8=",
    "cancel_url":"aHR0cHM6Ly9leGFtcGxlLmNvbS8=",
    "webhook":"aHR0cHM6Ly9leGFtcGxlLmNvbS8=",
    "billing.firstname" : "John",
    "billing.lastname" : "Doe",
    "billing.address_1" : "969 Market",
    "billing.address_2" : "",
    "billing.city" : "San Francisco",
    "billing.state_or_region" : "CA",
    "billing.postcode_or_pobox" : "94103",
    "billing.country" : "US",
    "billing.phone" : "255xxxxxxxxx",
    "shipping.firstname" : "John",
    "shipping.lastname" : "Doe",
    "shipping.address_1" : "969 Market",
    "shipping.address_2" : "",
    "shipping.city" : "San Francisco",
    "shipping.state_or_region" : "CA",
    "shipping.postcode_or_pobox" : "94103",
    "shipping.country" : "US",
    "shipping.phone" : "255xxxxxxxxx",
    "buyer_remarks":"None",
    "merchant_remarks":"None",
    "no_of_items":  3
}
#path relatiive to base url
orderPath = "/v1/checkout/create-order"

#crate new order
response = client.postFunc(orderPath, orderDict)

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

The above command returns JSON structured like this:


{
  "reference" : "0289999288",
  "resultcode" : "000",
  "result" : "SUCCESS",
  "message" : "Payment notification logged",
  "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
expiry Optional 60 Expiry in minutes

Create Order - Minimal

Create Order - Minimal Sample

# With shell, you can just pass the correct header with each request
curl -X POST 'http://example.com/v1/checkout/create-order-minimal' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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

}'
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$orderMinArray = array(
    "vendor"=>"VENDORTILL",
    "order_id"=>"85gh9p7l8",
    "buyer_email"=> "john@example.com",
    "buyer_name"=> "John Joh",
    "buyer_phone"=> "255xxxxxxxxx",
    "amount"=>  8000,
    "currency"=>"TZS",
    "redirect_url"=>"aHR0cHM6Ly9leGFtcGxlLmNvbS8=",
    "cancel_url"=>"aHR0cHM6Ly9leGFtcGxlLmNvbS8=",
    "webhook"=>"aHR0cHM6Ly9leGFtcGxlLmNvbS8=",
    "buyer_remarks"=>"None",
    "merchant_remarks"=>"None",
    "no_of_items"=>  3
    );

// path relatiive to base url
$orderMinPath = "/v1/checkout/create-order-minimal";

// create order minimal
$response = $client->postFunc($orderMinPath,$orderMinArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";



// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String orderPath = "/v1/checkout/create-order-minimal";

// data
JsonObject orderDict = new JsonObject();
orderDict.addProperty("vendor","VENDORTILL");
orderDict.addProperty("order_id","1218d00Y");
orderDict.addProperty("buyer_email", "john@example.com");
orderDict.addProperty("buyer_name", "John Joh");
orderDict.addProperty("buyer_phone", "255082555555");
orderDict.addProperty("amount",  8000);
orderDict.addProperty("currency","TZS");
orderDict.addProperty("buyer_remarks","None");
orderDict.addProperty("merchant_remarks","None");
orderDict.addProperty("no_of_items", 1 );

//post data
JsonObject response = client.postFunc(orderPath ,orderDict);

//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> orderDict = new Dictionary<String,Object>() ;
orderDict.Add("vendor","VENDORTILL");
orderDict.Add("order_id","1218d5Qb");
orderDict.Add("buyer_email", "john@example.com");
orderDict.Add("buyer_name", "John Joh");
orderDict.Add("buyer_phone","255082555555");
orderDict.Add("amount",  8000);
orderDict.Add("currency","TZS");
orderDict.Add("buyer_remarks","None");
orderDict.Add("merchant_remarks","None");
orderDict.Add("no_of_items",  1);

// path relatiive to base url
String orderPath = "/v1/checkout/create-order-minimal";

//crate new order
var orderRespose = client.postFunc(orderPath, orderDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var orderJson = {
"vendor":"VENDORTILL",
"order_id":"1218d5Qb",
"buyer_email": "john@example.com",
"buyer_name": "John Joh",
"buyer_phone": "255082555555",
"amount":  8000,
"currency":"TZS",
"buyer_remarks":"None",
"merchant_remarks":"None",
"no_of_items":  1
}
// path relatiive to base url
var orderPath = "/v1/checkout/create-order-minimal"

//crate new order
var = orderRespose = client.postFunc(orderPath, orderJson)
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
orderDict = {
"vendor":"VENDORTILL",
"order_id":"1218d5Qb",
"buyer_email": "john@example.com",
"buyer_name": "John Joh",
"buyer_phone": "255082555555",
"amount":  8000,
"currency":"TZS",
"buyer_remarks":"None",
"merchant_remarks":"None",
"no_of_items":  1
}
#path relatiive to base url
orderPath = "/v1/checkout/create-order-minimal"

#crate new order
response = client.postFunc(orderPath, orderDict)

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

The above command returns JSON structured like this:


{
  "reference" : "0289999288",
  "resultcode" : "000",
  "result" : "SUCCESS",
  "message" : "Payment notification logged",
  "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 Order Sample

# With shell, you can just pass the correct header with each request
curl -X DELETE 'http://example.com/v1/checkout/cancel-order?order_id={order_id}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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: order_id"

require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$orderCancelArray = array("order_id"=>"85gh9p7l8");

// path relatiive to base url
$orderCancelPath = "/v1/checkout/cancel-order";

// cancel order
$response = $client->deleteFunc($orderCancelPath,$orderCancelArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";



// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String orderCancelPath = "/v1/checkout/cancel-order";

// data
JsonObject orderCancelDict = new JsonObject();
orderCancelDict.addProperty("order_id","1218d00Y");


//post data
JsonObject response = client.deleteFunc(orderCancelPath ,orderCancelDict);

//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> orderCancelDict = new Dictionary<String,Object>() ;
orderCancelDict.addProperty("order_id","1218d00Y");

// path relatiive to base url
String orderCancelPath = "/v1/checkout/cancel-order";

//crate new orderCancel
var orderCancelRespose = client.deleteFunc(orderCancelPath, orderCancelDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var orderCancelJson = {
"order_id":"1218d00Y"
}
// path relatiive to base url
var orderCancelPath = "/v1/checkout/cancel-order"

//crate new orderCancel
var = orderCancelRespose = client.deleteFunc(orderCancelPath, orderCancelJson)
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
orderCancelDict = {
"order_id":"1218d00Y"
}
#path relatiive to base url
orderCancelPath = "/v1/checkout/cancel-order"

#crate new orderCancel
response = client.deleteFunc(orderCancelPath, orderCancelDict)

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 cancelled successfully",
  "data": []
}

Get Order Status

Get Order Status Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/checkout/order-status?order_id={order_id}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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: order_id" 
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";


$client = new Client($baseUrl, $apiKey, $apiSecret);


// data
$orderStatusArray = array("order_id"=>"85gh9p7l8");

// path relatiive to base url
$orderStatusPath = "/v1/checkout/order-status";

// get order status
$response = $client->getFunc($orderStatusPath,$orderStatusArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String orderStatusPath = "/v1/checkout/order-status";

// data
JsonObject orderStatusDict = new JsonObject();
orderStatusDict.addProperty("order_id","85gh9p7l8");


//get order status
JsonObject response = client.getFunc(orderStatusPath ,orderStatusDict);

//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> orderStatusDict = new Dictionary<String,Object>() ;
orderStatusDict.Add("order_id","85gh9p7l8");

// path relatiive to base url
String orderStatusPath = "/v1/checkout/order-status";

//crate new orderStatus
var orderStatusRespose = client.getFunc(orderStatusPath, orderStatusDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var orderStatusJson = {"order_id":"85gh9p7l8",}
// path relatiive to base url
var orderStatusPath = "/v1/checkout/order-status"

//crate new orderStatus
var = orderStatusRespose = client.getFunc(orderStatusPath, orderStatusJson)
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
orderStatusDict = {"order_id":"85gh9p7l8"}
#path relatiive to base url
orderStatusPath = "/v1/checkout/order-status"

#crate new orderStatus
response = client.getFunc(orderStatusPath, orderStatusDict)

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

List All Orders Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/checkout/list-orders?fromdate={YYYY-MM-DD}&todate={YYYY-MM-DD}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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: fromdate, todate" 
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$listOrdersArray = array(
    "fromdate"=>"2023-02-10",
    "todate"=>"2023-02-16");

// path relatiive to base url
$listOrdersPath = "/v1/checkout/list-orders";

// list orders between selected dates
$response = $client->getFunc($listOrdersPath,$listOrdersArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";



// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String listOrdersPath = "/v1/checkout/list-orders";

// data
JsonObject listOrdersDict = new JsonObject();
listOrdersDict.addProperty("fromdate"=>"2023-02-10");
listOrdersDict.addProperty("todate"=>"2023-02-16");


//get orders
JsonObject response = client.getFunc(listOrdersPath ,listOrdersDict);

//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> listOrdersDict = new Dictionary<String,Object>() ;
listOrdersDict.Add("fromdate"=>"2023-02-10");
listOrdersDict.Add("todate"=>"2023-02-16");

// path relatiive to base url
String listOrdersPath = "/v1/checkout/list-orders";

//crate new listOrders
var listOrdersRespose = client.getFunc(listOrdersPath, listOrdersDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var listOrdersJson = {
    "fromdate":"2023-02-10",
    "todate":"2023-02-16"
}
// path relatiive to base url
var listOrdersPath = "/v1/checkout/list-orders"

//crate new listOrders
var = listOrdersRespose = client.getFunc(listOrdersPath, listOrdersJson)
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
listOrdersDict = {
    "fromdate":"2023-02-10",
    "todate":"2023-02-16"
}
#path relatiive to base url
listOrdersPath = "/v1/checkout/list-orders"

#crate new listOrders
response = client.getFunc(listOrdersPath, listOrdersDict)

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

Fetch Stored Card Tokens Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/checkout/stored-cards?gateway_buyer_uuid={gateway_buyer_uuid}&buyer_userid={buyer_userid}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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: gateway_buyer_uuid, buyer_userid" 
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$fetchStoredTokensArray = array(
    "buyer_userid"=>"0000001",
    "gateway_buyer_uuid"=>"00000001");

// path relatiive to base url
$fetchStoredTokensPath = "/v1/checkout/stored-cards";

// fetch stored card tokens
$response = $client->getFunc($fetchStoredTokensPath,$fetchStoredTokensArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String fetchCardTokensPath = "/v1/checkout/stored-cards";

// data
JsonObject fetchCardTokensDict = new JsonObject();
fetchCardTokensDict.addProperty("buyer_userid"=>"0000001");
fetchCardTokensDict.addProperty("gateway_buyer_uuid"=>"00000001");

//post data
JsonObject response = client.getFunc(fetchCardTokensPath ,fetchCardTokensDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> fetchCardTokensDict = new Dictionary<String,Object>() ;
fetchCardTokensDict.Add("buyer_userid"=>"0000001");
fetchCardTokensDict.Add("gateway_buyer_uuid"=>"00000001");

// path relatiive to base url
String fetchCardTokensPath = "/v1/checkout/stored-cards";

//crate new fetchCardTokens
var fetchCardTokensRespose = client.getFunc(fetchCardTokensPath, fetchCardTokensDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var fetchCardTokensJson = {
"buyer_userid":"0000001",
    "gateway_buyer_uuid":"00000001"
}
// path relatiive to base url
var fetchCardTokensPath = "/v1/checkout/stored-cards"

//crate new fetchCardTokens
var = fetchCardTokensRespose = client.getFunc(fetchCardTokensPath, fetchCardTokensJson)
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
fetchCardTokensDict = {
    "buyer_userid":"0000001",
    "gateway_buyer_uuid":"00000001"
}
#path relatiive to base url
fetchCardTokensPath = "/v1/checkout/stored-cards"

#crate new fetchCardTokens
response = client.getFunc(fetchCardTokensPath, fetchCardTokensDict)

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"}]
}

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

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

Delete Stored Card Sample

# With shell, you can just pass the correct header with each request
curl -X DELETE 'http://example.com/v1/checkout/delete-card?id={card-resource-id}&gateway_buyer_uuid=   {gateway_buyer_uuid}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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: id,gateway_buyer_uuid " 

require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$deleteCardArray = array(
    "id"=>"0000001",
    "gateway_buyer_uuid"=>"00000001");

// path relatiive to base url
$deleteCardPath = "/v1/checkout/delete-card";

// delete stored card
$response = $client->deleteFunc($deleteCardPath,$deleteCardArray);
//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";



// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String deleteCardPath = "/v1/checkout/delete-card";

// data
JsonObject deleteCardDict = new JsonObject();
deleteCardDict.addProperty("id","0000001");
deleteCardDict.addProperty("gateway_buyer_uuid","00000001");


//delete card
JsonObject response = client.deleteFunc(deleteCardPath ,deleteCardDict);

//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> deleteCardDict = new Dictionary<String,Object>() ;
deleteCardDict.Add("id","0000001");
deleteCardDict.Add("gateway_buyer_uuid","00000001");

// path relatiive to base url
String deleteCardPath = "/v1/checkout/delete-card";

//crate new deleteCard
var deleteCardRespose = client.deleteFunc(deleteCardPath, deleteCardDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var deleteCardJson = {
    "id":"0000001",
    "gateway_buyer_uuid":"00000001"
}
// path relatiive to base url
var deleteCardPath = "/v1/checkout/delete-card"

//crate new deleteCard
var = deleteCardRespose = client.deleteFunc(deleteCardPath, deleteCardJson)
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
deleteCardDict = {
    "id":"0000001",
    "gateway_buyer_uuid":"00000001"
}
#path relatiive to base url
deleteCardPath = "/v1/checkout/delete-card"

#crate new deleteCard
response = client.deleteFunc(deleteCardPath, deleteCardDict)

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 - Card Payment Sample

# With shell, you can just pass the correct header with each request
curl -X POST 'http://example.com/v1/checkout/card-payment' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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,vendor,order_id,card_token,buyer_userid,gateway_buyer_uuid" \
  -d '{"transid":"T123442","vendor":"VENDORTILL", "order_id":"123", "card_token":"ABC123423232", "buyer_userid":"adfm311",gateway_buyer_uuid":"12344321"}
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$cardPaymentArray = array(
    "transid"=> "A1234",
    "vendor"=>"VENDORTILL",
    "order_id"=>"85gh9p7l8",
    "card_token"=> "ABC123423232",
    "buyer_userid"=> "255xxxxxxxxx",
    "gateway_buyer_uuid"=>"12434343",
    );

// path relatiive to base url
$cardPaymentPath = "/v1/checkout/card-payment";

//  card payment
$response = $client->postFunc($cardPaymentPath,$cardPaymentArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";



// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String cardPaymentPath = "/v1/checkout/card-payment";

// data
JsonObject cardPaymentDict = new JsonObject();
cardPaymentDict.addProperty("transid", "A1234");
cardPaymentDict.addProperty("vendor","VENDORTILL");
cardPaymentDict.addProperty("order_id","85gh9p7l8");
cardPaymentDict.addProperty("card_token", "ABC123423232");
cardPaymentDict.addProperty("buyer_userid", "255xxxxxxxxx");
cardPaymentDict.addProperty("gateway_buyer_uuid","12434343");

//post data
JsonObject response = client.postFunc(cardPaymentPath ,cardPaymentDict);

//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> cardPaymentDict = new Dictionary<String,Object>() ;
cardPaymentDict.Add("transid", "A1234");
cardPaymentDict.Add("vendor","VENDORTILL");
cardPaymentDict.Add("order_id","85gh9p7l8");
cardPaymentDict.Add("card_token", "ABC123423232");
cardPaymentDict.Add("buyer_userid", "255xxxxxxxxx");
cardPaymentDict.Add("gateway_buyer_uuid","12434343");

// path relatiive to base url
String cardPaymentPath = "/v1/checkout/card-payment";

//crate new cardPayment
var cardPaymentRespose = client.postFunc(cardPaymentPath, cardPaymentDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var cardPaymentJson = {
  "transid": "A1234",
  "vendor":"VENDORTILL",
  "order_id":"85gh9p7l8",
  "card_token": "ABC123423232",
  "buyer_userid": "255xxxxxxxxx",
  "gateway_buyer_uuid":"12434343",
};
// path relatiive to base url
var cardPaymentPath = "/v1/checkout/card-payment";

//crate new cardPayment
var = cardPaymentRespose = client.postFunc(cardPaymentPath, cardPaymentJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
cardPaymentDict = {
"transid": "A1234",
  "vendor":"VENDORTILL",
  "order_id":"85gh9p7l8",
  "card_token": "ABC123423232",
  "buyer_userid": "255xxxxxxxxx",
  "gateway_buyer_uuid":"12434343",
}
#path relatiive to base url
cardPaymentPath = "/v1/checkout/card-payment"

#crate new cardPayment
response = client.postFunc(cardPaymentPath, cardPaymentDict)

{
  "reference" : "0289999288",
  "resultcode" : "111",
  "result" : "PENDING",
  "message" : "Request in progress. You will receive a callback shortly.",
  "data": []
}

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

Process Order - Wallet Pull Payment

Process Order - Wallet Pull Payment Sample

# With shell, you can just pass the correct header with each request
curl -X POST "http://example.com/v1/checkout/wallet-payment" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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,msisdn"  \
  -d '{"transid":"T123442", "order_id":"123", "msisdn":"2556828XXXXX"} 
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$walletPaymentArray = array(
    "transid"=> "A1234",
    "order_id"=>"85gh9p7l8",
    "msisdn"=> "255xxxxxxxxx",
    );

// path relatiive to base url
$walletPaymentPath = "/v1/checkout/wallet-payment";

// wallet payment
$response = $client->postFunc($walletPaymentPath,$walletPaymentArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String walletPaymentPath = "/v1/checkout/wallet-payment";

// data
JsonObject walletPaymentDict = new JsonObject();
walletPaymentDict.addProperty("transid", "R1234");
walletPaymentDict.addProperty("order_id","85gh9p7l8");
walletPaymentDict.addProperty("msisdn", "255xxxxxxxxx");


//post wallet payment 
JsonObject response = client.postFunc(walletPaymentPath ,walletPaymentDict);

//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> walletPaymentDict = new Dictionary<String,Object>() ;
walletPaymentDict.Add("transid", "R1234");
walletPaymentDict.Add("order_id","85gh9p7l8");
walletPaymentDict.Add("msisdn", "255xxxxxxxxx");

// path relatiive to base url
String walletPaymentPath = "/v1/checkout/wallet-payment";

//crate new walletPayment
var walletPaymentRespose = client.postFunc(walletPaymentPath, walletPaymentDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var walletPaymentJson = {
  "transid": "A1234",
    "order_id":"85gh9p7l8",
    "msisdn": "255xxxxxxxxx",
}
// path relatiive to base url
var walletPaymentPath = "/v1/checkout/wallet-payment"

//crate new walletPayment
var = walletPaymentRespose = client.postFunc(walletPaymentPath, walletPaymentJson)
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
walletPaymentDict = {
  "transid": "A1234",
    "order_id":"85gh9p7l8",
    "msisdn": "255xxxxxxxxx",
}
#path relatiive to base url
walletPaymentPath = "/v1/checkout/wallet-payment"

#crate new walletPayment
response = client.postFunc(walletPaymentPath, walletPaymentDict)

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.

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

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

Webhook Callback Sample

# With shell, you can just pass the correct header with each request
curl "{thirdparty_site_webhook url}"\
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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"}
# Webhook payload sample
{
  "result": "SUCCESS",
  "resultcode": "000",
  "order_id": "602021152",
  "transid": "7945454515",
  "reference": "856266164161",
  "channel": "TIGOPESATZ",
  "amount": "10000",
  "phone": "255000000001",
  "payment_status": "COMPLETED"
}

Payment status callback api from payment gateway to ecommerce website. **Note : Webhook only on successful transcations

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

Integrated Merchants

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 C2B (to be implemented on Merchants Side)

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 to Merchant's ERP

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

This API request is initiated from Selcom to Merchant's ERP system. 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 Invoice No or Merchant Unique reference for the payment
amount Available 1000 Transaction amount (Incase of a fixed invoices. This will be zero and expected amount on the response. So customer dont have to enter the amount and the amount is returned from Merchants ERP)
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)
amount Payment amount associated with the utilityref. (optional)

Payment Notification to Merchant's ERP

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

This API request is initiated from Selcom to Merchant's ERP system.

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 Invoice No or Merchant Unique reference for the payment
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 Merchant's System or ERP

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.

Prompt Payment Flow on POS Terminal

API is used to trigger a Payment on POS terminal by a Merchant intiated by the Merchant Billing System, ERP or Cash counter. On completion on payment flow on the POS terminal the Notification Api in the previous section is triggered.

Sample

# With shell, you can just pass the correct header with each request
curl -X POST "http://example.com/v1/checkout/initiate-pos-payment" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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,currency,amount,payment_method,msisdn"\
  -d '{"currency":"TZS",  "amount":"123","payment_method":"MOBILEMONEY" "msisdn":"255111111111"}
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$refundPaymentArray = array(
    "currency"=> "A1234",
    "amount"=>8000,
    "payment_method"=>"MOBILEMONEY",
    "msisdn"=>"255111111111"
    );

// path relatiive to base url
$refundPaymentPath = "/v1/checkout/initiate-pos-payment";

//  refund payment
$response = $client->postFunc($refundPaymentPath,$refundPaymentArray);
//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String promptPaymentPath = "/v1/checkout/initiate-pos-payment";

// data
JsonObject promptPaymentDict = new JsonObject();
promptPaymentDict.addProperty("currency", "A1234");
promptPaymentDict.addProperty("amount",8000);
promptPaymentDict.addProperty("payment_method","MOBILEMONEY");
promptPaymentDict.addProperty("msisdn","255111111111");


//post payment refund
JsonObject response = client.postFunc(promptPaymentPath ,promptPaymentDict);

//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> promptPaymentDict = new Dictionary<String,Object>() ;
promptPaymentDict.Add("currency", "A1234");
promptPaymentDict.Add("amount",8000);
promptPaymentDict.Add("payment_method","MOBILEMONEY");
promptPaymentDict.Add("msisdn","255111111111");

// path relatiive to base url
String promptPaymentPath = "/v1/checkout/initiate-pos-payment";

//crate new promptPayment
var promptPaymentRespose = client.postFunc(promptPaymentPath, promptPaymentDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var promptPaymentJson = {
  "currency":"A1234",
  "amount":8000,
  "payment_method":"MOBILEMONEY",
  "msisdn":"255111111111"
}
// path relatiive to base url
var promptPaymentPath = "/v1/checkout/initiate-pos-payment"

//crate new promptPayment
var = promptPaymentRespose = client.postFunc(promptPaymentPath, promptPaymentJson)
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
promptPaymentDict = {
    "currency":"A1234",
    "amount":8000,
    "payment_method":"MOBILEMONEY",
    "msisdn":"255111111111"

}
#path relatiive to base url
promptPaymentPath = "/v1/checkout/initiate-pos-payment"

#crate new promptPayment
response = client.postFunc(promptPaymentPath, promptPaymentDict)

HTTP Request

POST http://example.com/v1/checkout/initiate-pos-payment

Parameter Type Example Description
currency Mandatory TZS Currency
amount Mandatory 5000 Amount
payment_method Optional CARD MOBILEMONEY, CARD
msisdn Optional 255XXXXXXXX Billing wallet mobile from which the merchant want to pull funds. MANDATORY when payment_method is MOBILEMONEY
invoice_no Optional BAD001 Invoice for payment

International Money Transfer API (IMT)

Wallet Name Look Up

Wallet Name Lookup Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/imt/wallet-namelookup?utilitycode={uitlitycode}&utilityref={utilityref}&transid={transid}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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: utilitycode,utilityref,transid"
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$walletNameLookUpArray = array(
    "utilitycode"=> "REMITIN",
    "utilityref"=> "0149449499",
    "transid"=>"1218d5Qb",
    );

// path relatiive to base url
$walletNameLookUpPath = "/v1/imt/wallet-namelookup";

// lookup name
$response = $client->getFunc($walletNameLookUpPath,$walletNameLookUpArray);
//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String walletNameLookUpPath = "/v1/imt/wallet-namelookup";

// data
JsonObject walletNameLookUpDict = new JsonObject();
walletNameLookUpDict.addProperty("utilitycode", "REMITIN");
walletNameLookUpDict.addProperty("utilityref", "154944949");
walletNameLookUpDict.addProperty("transid","1218d5Qb");

//lookup walllet cashin name
JsonObject response = client.getFunc(walletNameLookUpPath ,walletNameLookUpDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> walletNameLookUpDict = new Dictionary<String,Object>() ;
walletNameLookUpDict.Add("utilitycode", "REMITIN");
walletNameLookUpDict.Add("utilityref", "154944949");
walletNameLookUpDict.Add("transid","1218d5Qb");

// path relatiive to base url
String walletNameLookUpPath = "/v1/imt/wallet-namelookup";

//crate new walletNameLookUp
var walletNameLookUpRespose = client.getFunc(walletNameLookUpPath,walletNameLookUpDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient (baseUrl, apiKey, apiSecret);

//data
var walletNameLookUpJson = {
    "utilitycode": "REMITIN",
    "utilityref": "0149449499",
    "transid":"1218d5Qb",
};
// path relatiive to base url
var walletNameLookUpPath = "/v1/imt/wallet-namelookup"

//crate new walletNameLookUp
var = walletNameLookUpRespose = client.getFunc(walletNameLookUpPath,walletNameLookUpJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
walletNameLookUpDict = {
    "utilitycode": "REMITIN",
    "utilityref": "0149449499",
    "transid":"1218d5Qb",
}
#path relatiive to base url
walletNameLookUpPath = "/v1/imt/wallet-namelookup"

#crate new walletNameLookUp
response = client.getFunc(walletNameLookUpPath, walletNameLookUpDict)

Wallet Name Lookup Sample response:

{
  "reference":"6927759116",
  "transid":"10001",
  "resultcode":"000",
  "result":"SUCCESS",
  "message":"Name fetch successful",
  "data":[
    {
      "name":"FIROZ MOH"
    }
  ]
}

HTTP Request

GET http://example.com/v1/imt/wallet-namelookup?utilitycode=REMITIN&utilityref=XYZ123444&transid=1001

Query Parameters

Parameter Type Example Description
utilitycode Mandatory REMITIN 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.

Utilty Codes

Wallet Type Utility code
MPESA MPREMITIN
TIGOPESA TPREMITIN
HALOPESA HPREMITIN
AIRTELMONEY AMREMITIN
TTCL Pesa TTREMITIN

Bank Account Name Lookup

Bank Account Name Lookup SAmple

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/imt/bank-namelookup/?bank={bank}&account={account}&transid={transid}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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: bank,account,transid" 
require_once __DIR__ .'/vendor/autoload.php';

// use selcom client module
use Selcom\ApigwClient\Client;

// initalize a new Client instace with values o=>f the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$accountNameLookupArray = array(
    "bank"=> "AKIBA",
    "account" => "000000040000",
    "transid"=>"1218d5Qb",
    );

// path relatiive to base url
$accountNameLookupPath = "/v1/imt/bank-namelookup/";

// lookup account name
$response = $client->getFunc($accountNameLookupPath,$accountNameLookupArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String accountNameLookupPath = "/v1/imt/bank-namelookup/";

// data
JsonObject accountNameLookupDict = new JsonObject();
accountNameLookupDict.addProperty("bank", "AKIBA");
accountNameLookupDict.addProperty("account" , "000000040000");
accountNameLookupDict.addProperty("transid","1218d5Qb");

//lookup account name
JsonObject response = client.getFunc(accountNameLookupPath ,accountNameLookupDict);
//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> accountNameLookupDict = new Dictionary<String,Object>() ;
accountNameLookupDict.Add("bank", "AKIBA");
accountNameLookupDict.Add("account" , "000000040000");
accountNameLookupDict.Add("transid","1218d5Qb");

// path relatiive to base url
String accountNameLookupDictPath = "/v1/imt/bank-namelookup";

//crate new accountNameLookup
var accountNameLookupRespose = client.getFunc(accountNameLookupPath,accountNameLookupDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
var accountNameLookupJson = {
    "bank": "AKIBA",
    "account" : "000000040000",
    "transid":"1218d5Qb",
};
// path relatiive to base url
var accountNameLookupPath = "/v1/imt/bank-namelookup"

//crate new accountNameLookup
var = accountNameLookupRespose = client.getFunc(accountNameLookupPath, accountNameLookupJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
accountNameLookupDict = {
    "bank": "AKIBA",
    "account" : "000000040000",
    "transid":"1218d5Qb",
}
#path relatiive to base url
accountNameLookupPath = "/v1/imt/bank-namelookup"

#crate new accountNameLookup
response = client.getFunc(accountNameLookupPath, accountNameLookupDict)

HTTP Request

GET http://example.com/v1/imt/bank-namelookup/?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.

.

Send Money

IMT Send Money Sample

# With shell, you can just pass the correct header with each request
curl -X POST 'http://example.com/v1/imt/send-money' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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: messageId,end2endId,sender.firstname,sender.lastname,sender.country,sender.mobile,sender.idType,sender.idNo,sender.dateOfBirth,sender.placeOfBirth,sender.nationality,sender.idIssuedCountry,sender.occupation,sourceOfFundsrecipient.firstname,recipient.lastname,recipient.country,recipient.mobile,vendor,pin,currency,amount,purpose,personalMessage,secretMessage,sourceFI.type,sourceFI.name,sourceFI.country,sourceFI.code,sourceFI.account,destinationFI.type,destinationFI.name,destinationFI.country,destinationFI.code,destinationFI.account" \
  -d '{
    "messageId":"M1234",
    "end2endId":"E1234",
    "sender.firstname": "John",
    "sender.lastname": "Joh",
    "sender.country": "UGA",
    "sender.mobile": "256xxxxxxxxx",
    "sender.idType":  "PASSPORT",
    "sender.idNo":"GS1002223",
    "sender.dateOfBirth" :"2019-02-26",
    "sender.placeOfBirth":"XYZ",
    "sender.nationality": "TZA",
    "sender.idIssuedCountry":"TZA",
    "sender.occupation":"Doctor",
    "sourceOfFunds":"SALARY",
    "recipient.firstname":"Benjamin",
    "recipient.lastname":"Beny",
    "recipient.country":"TZA",
    "recipient.mobile":"255xxxxxxxxxx",
    "vendor" : "IMTHUB001",
    "pin" : "123123",
    "currency" : "TZS",
    "amount" : 80000,
    "purpose" : "GIFT",
    "personalMessage" : "Happy birthday",
    "secretMessage" : "MANGO",
    "sourceFI.type" : "BANK",
    "sourceFI.name" : "Exim Bank",
    "sourceFI.country" : "EXIMUGA",
    "sourceFI.code" : "Doe",
    "sourceFI.account" : "9693546",
    "destinationFI.type" : "WALLET",
    "destinationFI.name" : "MPESA",
    "destinationFI.country" : "TZA",
    "destinationFI.code" : "    VMTZ",
    "destinationFI.account" : "255xxxxxxxxx"
}'
require_once __DIR__ .'/vendor/autoload.php';

// 
use Selcom\ApigwClient\Client;

# initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";


$client = new Client($baseUrl, $apiKey, $apiSecret);


// data
$sendMoneyArray = array(
    "messageId"=>"M1234",
    "end2endId"=>"E1234",
    "sender.firstname"=> "John",
    "sender.lastname"=> "Joh",
    "sender.country"=> "UGA",
    "sender.mobile"=> "256xxxxxxxxx",
    "sender.idType"=>  "PASSPORT",
    "sender.idNo"=>"GS1002223",
    "sender.dateofbirth" =>"2019-02-26",
    "sender.placeOfBirth"=>"XYZ",
    "sender.nationality"=> "TZA",
    "sender.idIssuedCountry"=>"TZA",
    "sender.occupation"=>"Doctor"
    "sourceOfFunds"=>"SALARY"
    "recipient.firstname"=>"Benjamin",
    "recipient.lastname"=>"Beny",
    "recipient.country"=>"TZA",
    "recipient.mobile"=>"255xxxxxxxxxx",
    "vendor" => "IMTHUB001",
    "pin" => "123123",
    "currency" => "TZS",
    "amount" => 80000,
    "purpose" => "GIFT",
    "personalMessage" => "Happy birthday",
    "secretMessage" => "MANGO",
    "sourceFI.type" => "BANK",
    "sourceFI.name" => "Exim Bank",
    "sourceFI.country" => "EXIMUGA",
    "sourceFI.code" => "Doe",
    "sourceFI.account" => "9693546",
    "destinationFI.type" => "WALLET",
    "destinationFI.name" => "MPESA",
    "destinationFI.country" => "TZA",
    "destinationFI.code" => "   VMTZ",
    "destinationFI.account" => "255xxxxxxxxx"
);

// path relatiive to base url
$sendMoneyPath = "/v1/imt/send-money";

// send money imt
$response = $client->postFunc($sendMoneyPath,$sendMoneyArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String sendMoneyPath = "/v1/imt/send-money";

// data
JsonObject sendMoneyDict = new JsonObject();
sendMoneyDict.addProperty("messageId","M1234");
sendMoneyDict.addProperty("end2endId","E1234");
sendMoneyDict.addProperty("sender.firstname", "John");
sendMoneyDict.addProperty("sender.lastname", "Joh");
sendMoneyDict.addProperty("sender.country", "UGA");
sendMoneyDict.addProperty("sender.mobile", "256xxxxxxxxx");
sendMoneyDict.addProperty("sender.idType",  "PASSPORT");
sendMoneyDict.addProperty("sender.idNo","GS1002223");
sendMoneyDict.addProperty("sender.dateOfBirth" ,"2019-02-26");
sendMoneyDict.addProperty("sender.placeOfBirth","XYZ");
sendMoneyDict.addProperty("sender.nationality", "TZA");
sendMoneyDict.addProperty("sender.idIssuedCountry","TZA");
sendMoneyDict.addProperty("sender.occupation","Doctor");
sendMoneyDict.addProperty("sourceOfFunds","SALARY");
sendMoneyDict.addProperty("recipient.firstname","Benjamin");
sendMoneyDict.addProperty("recipient.lastname","Beny");
sendMoneyDict.addProperty("recipient.country","TZA");
sendMoneyDict.addProperty("recipient.mobile","255xxxxxxxxxx");
sendMoneyDict.addProperty("vendor" , "IMTHUB001");
sendMoneyDict.addProperty("pin" , "123123");
sendMoneyDict.addProperty("currency" , "TZS");
sendMoneyDict.addProperty("amount" , 80000);
sendMoneyDict.addProperty("purpose" , "GIFT");
sendMoneyDict.addProperty("personalMessage" , "Happy birthday");
sendMoneyDict.addProperty("secretMessage" , "MANGO");
sendMoneyDict.addProperty("sourceFI.type" , "BANK");
sendMoneyDict.addProperty("sourceFI.name" , "Exim Bank");
sendMoneyDict.addProperty("sourceFI.country" , "EXIMUGA");
sendMoneyDict.addProperty("sourceFI.code" , "Doe");
sendMoneyDict.addProperty("sourceFI.account" , "9693546");
sendMoneyDict.addProperty("destinationFI.type" , "WALLET");
sendMoneyDict.addProperty("destinationFI.name" , "MPESA");
sendMoneyDict.addProperty("destinationFI.country" , "TZA");
sendMoneyDict.addProperty("destinationFI.code" , "  VMTZ");
sendMoneyDict.addProperty("destinationFI.account" , "255xxxxxxxxx");

//post send money
JsonObject response = client.postFunc(sendMoneyPath ,sendMoneyDict);

//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> sendMoneyDict = new Dictionary<String,Object>() ;
sendMoneyDict.Add("messageId","M1234");
sendMoneyDict.Add("end2endId","E1234");
sendMoneyDict.Add("sender.firstname", "John");
sendMoneyDict.Add("sender.lastname", "Joh");
sendMoneyDict.Add("sender.country", "UGA");
sendMoneyDict.Add("sender.mobile", "256xxxxxxxxx");
sendMoneyDict.Add("sender.idType",  "PASSPORT");
sendMoneyDict.Add("sender.idNo","GS1002223");
sendMoneyDict.Add("sender.dateOfBirth" ,"2019-02-26");
sendMoneyDict.Add("sender.placeOfBirth","XYZ");
sendMoneyDict.Add("sender.nationality", "TZA");
sendMoneyDict.Add("sender.idIssuedCountry","TZA");
sendMoneyDict.Add("sender.occupation","Doctor");
sendMoneyDict.Add("sourceOfFunds","SALARY");
sendMoneyDict.Add("recipient.firstname","Benjamin");
sendMoneyDict.Add("recipient.lastname","Beny");
sendMoneyDict.Add("recipient.country","TZA");
sendMoneyDict.Add("recipient.mobile","255xxxxxxxxxx");
sendMoneyDict.Add("vendor" , "IMTHUB001");
sendMoneyDict.Add("pin" , "123123");
sendMoneyDict.Add("currency" , "TZS");
sendMoneyDict.Add("amount" , 80000);
sendMoneyDict.Add("purpose" , "GIFT");
sendMoneyDict.Add("personalMessage" , "Happy birthday");
sendMoneyDict.Add("secretMessage" , "MANGO");
sendMoneyDict.Add("sourceFI.type" , "BANK");
sendMoneyDict.Add("sourceFI.name" , "Exim Bank");
sendMoneyDict.Add("sourceFI.country" , "EXIMUGA");
sendMoneyDict.Add("sourceFI.code" , "Doe");
sendMoneyDict.Add("sourceFI.account" , "9693546");
sendMoneyDict.Add("destinationFI.type" , "WALLET");
sendMoneyDict.Add("destinationFI.name" , "MPESA");
sendMoneyDict.Add("destinationFI.country" , "TZA");
sendMoneyDict.Add("destinationFI.code" , "  VMTZ");
sendMoneyDict.Add("destinationFI.account" , "255xxxxxxxxx");

// path relatiive to base url
String sendMoneyPath = "/v1/imt/send-money";

//crate new sendMoney
var sendMoneyRespose = client.postFunc(sendMoneyPath, sendMoneyDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient (baseUrl, apiKey, apiSecret);

//data
var sendMoneyJson = {
    "messageId":"M1234",
    "end2endId":"E1234",
    "sender.firstname": "John",
    "sender.lastname": "Joh",
    "sender.country": "UGA",
    "sender.mobile": "256xxxxxxxxx",
    "sender.idType":  "PASSPORT",
    "sender.idNo":"GS1002223",
    "sender.dateOfBirth" :"2019-02-26",
    "sender.placeOfBirth":"XYZ",
    "sender.nationality": "TZA",
    "sender.idIssuedCountry":"TZA",
    "sender.occupation":"Doctor",
    "sourceOfFunds":"SALARY",
    "recipient.firstname":"Benjamin",
    "recipient.lastname":"Beny",
    "recipient.country":"TZA",
    "recipient.mobile":"255xxxxxxxxxx",
    "vendor" : "IMTHUB001",
    "pin" : "123123",
    "currency" : "TZS",
    "amount" : 80000,
    "purpose" : "GIFT",
    "personalMessage" : "Happy birthday",
    "secretMessage" : "MANGO",
    "sourceFI.type" : "BANK",
    "sourceFI.name" : "Exim Bank",
    "sourceFI.country" : "EXIMUGA",
    "sourceFI.code" : "Doe",
    "sourceFI.account" : "9693546",
    "destinationFI.type" : "WALLET",
    "destinationFI.name" : "MPESA",
    "destinationFI.country" : "TZA",
    "destinationFI.code" : "    VMTZ",
    "destinationFI.account" : "255xxxxxxxxx"
}
// path relatiive to base url
var sendMoneyPath = "/v1/imt/send-money"

//crate new sendMoney
var = sendMoneyRespose = client.postFunc(sendMoneyPath, sendMoneyJson)
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
sendMoneyDict = {
    "messageId":"M1234",
    "end2endId":"E1234",
    "sender.firstname": "John",
    "sender.lastname": "Joh",
    "sender.country": "UGA",
    "sender.mobile": "256xxxxxxxxx",
    "sender.idType":  "PASSPORT",
    "sender.idNo":"GS1002223",
    "sender.dateofbirth" :"2019-02-26",
    "sender.placeOfBirth":"XYZ",
    "sender.nationality": "TZA",
    "sender.idIssuedCountry":"TZA",
    "sourceOfFunds":"SALARY",
    "recipient.firstname":"Benjamin",
    "recipient.lastname":"Beny",
    "recipient.country":"TZA",
    "recipient.mobile":"255xxxxxxxxxx",
    "vendor" : "IMTHUB001",
    "pin" : "123123",
    "currency" : "TZS",
    "amount" : 80000,
    "purpose" : "GIFT",
    "personalMessage" : "Happy birthday",
    "secretMessage" : "MANGO",
    "sourceFI.type" : "BANK",
    "sourceFI.name" : "Exim Bank",
    "sourceFI.country" : "EXIMUGA",
    "sourceFI.code" : "Doe",
    "sourceFI.account" : "9693546",
    "destinationFI.type" : "WALLET",
    "destinationFI.name" : "MPESA",
    "destinationFI.country" : "TZA",
    "destinationFI.code" : "    VMTZ",
    "destinationFI.account" : "255xxxxxxxxx"
}
#path relatiive to base url
sendMoneyPath = "/v1/imt/send-money"

#crate new sendMoney
response = client.postFunc(sendMoneyPath, sendMoneyDict)
Request
{
  "messageId": "2020070101",
  "end2endId": "2020070101",
  "sender":{
    "firstname":"John",
    "lastname":"White",
    "country":"UGA",
    "mobile":"25632223232",
    "idType": "PASSOPORT",
    "idNo":"ABCDEFGH",
    "dateOfBirth" :"2019-02-26",
    "placeOfBirth":"XYZ",
    "nationality": "TZA",
    "idIssuedCountry":"TZA",
    "occupation":"Doctor"

  },
  "sourceOfFunds":"SALARY",
  "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": []
}

An IMT Hub or Financial institution invokes this API to an FI connected to Selcom. Note : This API is async and callback gives final confirmation that the recipient has recieved the funds.

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
sender.idIssuedCountry M TZA Alpha 3 country code of the country that issued sender identity document in ISO 3166 international standard
sender.dateOfBirth M 2019-02-26 Date of birth of sender in the format ( yyyy-mm-dd )
sender.nationality M TZA Alpha 3 country code of the country Nationality of the sender
sender.placeOfBirth M XYZ Place of birth of the sender
sender.occupation M DOCTOR Occupation of sender
sourceOfFunds M SALARY Source of funds to be sent (SALARY, BUISSINESS)
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 255000888777 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 USD Transaction currency (3 character Alphabetic code in ISO 4217 standard)
amount M 5000 Transaction amount
purpose M GIFT 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 TZA 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

Transaction Status

Transaction Status Sample

# With shell, you can just pass the correct header with each request
curl -X GET 'http://example.com/v1/imt/query?messageId={messageId}' \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -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: messageId" 
require_once __DIR__ .'/vendor/autoload.php';

//use selcom client module

use Selcom\ApigwClient\Client;

// initalize a new Client instace with values of the base url, api key and api secret

$apiKey = '202cb962ac59075b964b07152d234b70';
$apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
$baseUrl = "http://example.com";

$client = new Client($baseUrl, $apiKey, $apiSecret);

// data
$imtTransactionSatausArray = array(
    "messageId"=>"M1234");

// path relatiive to base url
$imtTransactionSatausPath = "/v1/imt/query";

// imt transaction status
$response = $client->getFunc($imtTransactionSatausPath,$imtTransactionSatausArray);

//import selcom client package
import io.github.selcompaytechltd.ApigwClient;
import java.util.Map;
import com.google.gson.*;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
Client client = new ApigwClient(baseUrl,apiKey,apiSecret);

// path relatiive to base url
String transactionStatusPath = "/v1/imt/query";

// data
JsonObject transactionStatusDict = new JsonObject();
transactionStatusDict.addProperty("messageId","M1234");


//get transaction status
JsonObject response = client.getFunc(transactionStatusPath ,transactionStatusDict);

//import package
using selcom_apgw_client;

String apiKey = '202cb962ac59075b964b07152d234b70';
String apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
String baseUrl = "http://example.com";

// initalize a new Client instace with values of the base url, api key and api secret
var client = new apigwClient(baseUrl, apiKey, apiSecret);

//data
Dictionary<String, Object> transactionStatusDict = new Dictionary<String,Object>() ;
transactionStatusDict.Add("messageId","M1234");

// path relatiive to base url
String transactionStatusPath = "/v1/imt/query";

//crate new transactionStatus
var transactionStatusRespose = client.getFunc(transactionStatusPath, transactionStatusDict);
//import package
const {apigwClient } = require("selcom-apigw-client");

// initalize a new Client instace with values of the base url, api key and api secret
const apiKey = '202cb962ac59075b964b07152d234b70';
const apiSecret = '81dc9bdb52d04dc20036dbd8313ed055';
const baseUrl = "http://example.com"

const client = new apigwClient (baseUrl, apiKey, apiSecret);

//data
var transactionStatusJson = {"messageId":"M1234",};
// path relatiive to base url
var transactionStatusPath = "/v1/imt/query"

//crate new transactionStatus
var = transactionStatusRespose = client.getFunc(transactionStatusPath, transactionStatusJson);
#import package
from selcom_apigw_client import apigwClient

# initalize a new Client instace with values of the base url, api key and api secret
apiKey = '202cb962ac59075b964b07152d234b70'
apiSecret = '81dc9bdb52d04dc20036dbd8313ed055'
baseUrl = "http://example.com"

client = apigwClient.Client(baseUrl, apiKey, apiSecret)

#data
transactionStatusDict = {"messageId":"M1234"}
#path relatiive to base url
transactionStatusPath = "/v1/imt/query"

#crate new transactionStatus
response = client.getFunc(transactionStatusPath, transactionStatusDict)

HTTP Request

GET http://example.com/v1/imt/query?messageId=20200721001

Response 1

{
  "messageId" : "20200721001",
  "reference" : "0289999288",
  "resultcode" : "000",
  "result" : "SUCCESS",
  "message" : "Transaction successful",
  "data": [{"receipt": "12344"}]
}

Response 2
{
  "messageId" : "20200721001",
  "reference" : "0289999288",
  "resultcode" : "999",
  "result" : "AMBIGOUS",
  "message" : "Transaction successful",
  "data":[]
}

Response 3
{
  "messageId" : "20200721001",
  "reference" : "0289999288",
  "resultcode" : "404",
  "result" : "FAILED",
  "message" : "Invalid Account number",
  "data":[]

}


Response 4
{
  "messageId" : "20200721001",
  "reference" : "0289999288",
  "resultcode" : "111",
  "result" : "INPROGRESS",
  "message" : "Transaction is being processed",
  "data":[]
}

Query Parameters

Parameter Type Example Description
messageId Mandatory XYZ123444 Unique Transaction ID of the transaction

**Note : Receipt data in response is present only for successful transactions and is dependent availability from thridparty FI

Transaction Callback - Selcom to Thirdparty

Request
{
  "messageId" : "20200721001",
  "reference" : "0289999288",
  "resultcode" : "000",
  "result" : "SUCCESS",
  "message" : "Transaction successful",
  "data": [{"receipt": "12344"}]
}

Response:
HTTP 200

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

**Note : Receipt data in response is present only for successful transactions and is dependent availability from thridparty FI

IMT Errorcodes

Synchronous Response

Resultcode Description
111, 001, 002, 003 Transaction in progress ( Async transaction wait for callback)
000 Successful ( transaction completed synchronously)
999 Ambiguous status
010 Invalid mobile number or operator not supported.
029 Customer account on suspended state
103 Invalid recipient account/mobile number
015 Invalid amount
013 Amount higher than allowed limit
611 Source FI not found
612, 012 Destination FI not found.
202, 201 Invalid account number or name validation failed
203 Recipient Name mismatch
218, 889, 900 , 151 Service unavailable
400 Transaction failed. (general)
415 KYC Validation failure.

Callback Status

Resultcode Description
000 Success
404, 400 Transaction failed to reach destination FI
500 , 501 Transaction rejected by destination FI
701 Transaction rejected by destination FI
702 Destination FI Internal Errors or Unavailable
703 Account currency mismatch
704 Transfer aborted due to customer maximum limit
200 Transaction Failed and reversed manually