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
Github Link
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
Github Link
CSHARP
Installation
dotnet add package selcom-apigw-client
Github Link
PYTHON
Installation
pip install selcom_apigw_client
Github Link
NODE.JS
Installation
npm i selcom-apigw-client
Github Link
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. |
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.
On demand subcription or stored card payment 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 |